bistro
  1. Overview
  2. Docs
package bistro
Legend:
Library
Module
Module type
Parameter
Class
Class type

This module provides combinators to define new workflows that execute shell commands.

include module type of Template with type t := Template.t

Represents a text with special symbols

val dest : Template.t

Symbol representing the location where a workflow is expected to produce its result

val tmp : Template.t

Symbol representing an existing empty directory that can be used as a temporary space for a workflow's execution.

val np : Template.t

Symbol representing the number of cores allocated to the workflow

val mem : Template.t

Symbol representing the memory size allocated to the workflow, in GB.

val exe : Template.t

Symbol representing the path of the current executable, as specified by Sys.argv.(0)

val string : string -> Template.t

A chunk of text

val int : int -> Template.t

Int formatting

val float : float -> Template.t

Float formatting

val path : Path.t -> Template.t

Path formatting

val dep : _ Workflow.t -> Template.t

dep w is interpreted as the path where to find the result of workflow w

val quote : ?using:char -> Template.t -> Template.t

quote ~using:c t surrounds template t with character c

val option : ('a -> Template.t) -> 'a option -> Template.t

option f o is f x if o = Some x and string "" otherwise

val list : ('a -> Template.t) -> ?sep:string -> 'a list -> Template.t

list combinator, optional value of sep is ","

val seq : ?sep:string -> Template.t list -> Template.t

another list combinator, default value for sep is ""

val enum : ('a * string) list -> 'a -> Template.t

combinator for enumerations

val file_dump : Template.t -> Template.t

file_dump t can be used when a command needs a configuration script: at run-time, it will generate a text using t, save it to a path, deterministically chosen as a function of t. Finally the template file_dump t is interpreted as this path.

type command
val workflow : ?descr:string -> ?mem:int -> ?np:int -> ?version:int -> command list -> 'a workflow

Workflow constructor, taking a list of commands in input. Other arguments are:

  • @param descr

    description of the workflow, used for logging

  • @param mem

    required memory

  • @param np

    maximum number of cores (could be given less at execution)

  • @param version

    version number, used to force the rebuild of a workflow

val input : ?may_change:bool -> string -> 'a workflow

Constructs a workflow from an existing file on the filesystem. The argument may_change indicates that the file may be modified, which is detected by giving the workflow a digest of the file as an input.

val selector : Path.t -> ('a, 'b) selector

Selector constructor

val (/) : _ directory workflow -> ('a, 'b) selector -> 'b workflow

Constructs a workflow by selecting a dir or file from a directory workflow

val map_command : ?descr:string -> ?mem:int -> ?np:int -> _ directory workflow -> (_ workflow -> command) -> _ directory workflow
val cmd : string -> ?env:docker_image -> ?stdin:Template.t -> ?stdout:Template.t -> ?stderr:Template.t -> Template.t list -> command

Command-line constructor, e.g. cmd "echo" ~stdout:dest [ string "foo" ] will generate a shell command like "echo foo > /some/path".

  • @param env

    specifies a Docker image where to run the command

  • @param stdin

    adds a "< /some/path" token at the end of the command

  • @param stdout

    adds a "> /some/path" token at the end of the command

  • @param stderr

    adds a "2> /some/path" token at the end of the command

val internal_cmd : string -> ?stdin:Template.t -> ?stdout:Template.t -> ?stderr:Template.t -> Template.t list -> command

Alternative command-line constructor, calling the current executable as specified by Sys.argv.(0). More precisely internal_cmd subcmd calls Sys.argv.(0) with subcommand subcmd.

val opt : string -> ('a -> Template.t) -> 'a -> Template.t

Command-line option formatting, e.g.: opt "--output" dep dest will be rendered like "--output /some/path"

val opt' : string -> ('a -> Template.t) -> 'a -> Template.t

Same as opt but renders options with an equal sign, e.g. "--output=/some/path"

val flag : ('a -> Template.t) -> 'a -> bool -> Template.t

flag f x b renders as f x if b is true

val or_list : command list -> command

OR-sequence of commands ( || )

val and_list : command list -> command

AND-sequence of commands ( && )

val pipe : command list -> command

Pipe of commands ( | )

val (//) : Template.t -> string -> Template.t

Similar to Filename.concat, but with other types.

Useful commands
val mkdir : Template.t -> command
val mkdir_p : Template.t -> command
val wget : ?no_check_certificate:bool -> ?user:string -> ?password:string -> ?dest:Template.t -> string -> command
val cd : Template.t -> command
val rm_rf : Template.t -> command
val docker_image : ?tag:string -> ?registry:string -> account:string -> name:string -> unit -> docker_image

Construct a description of a publicly available docker image

val docker : docker_image -> command -> command

docker cmd transforms cmd so that it can be executed in a Docker container.

val (%) : ('a -> 'b) -> ('b -> 'c) -> 'a -> 'c

Function composition