package yocaml

  1. Overview
  2. Docs
Core engine of the YOCaml Static Site Generator

Install 

dune-project
 Dependency

github.com Readme Changelog Edit opam file Versions (11)

Authors

  1. T
    The XHTMLBoy <xhtmlboi@gmail.com>

Maintainers

  1. T
    The XHTMLBoy <xhtmlboi@gmail.com>

Sources

yocaml-2.7.0.tbz
sha256=89a74bd5cb37e580e45e4ed3d43b07b2cca5af9ab7f98966c48fe9730dc4af2e
sha512=ae77555570320c28c47d748e75056ccc44bb43cddf6fef70e8b556254fd809d67b915b313bd1833c28581db1fdeefbe34e81d5548744d6ecabe466ee1ef6284c

doc/yocaml/Yocaml/Cmd/index.html

Module Yocaml.CmdSource

Used to describe Unix-style commands for executing arbitrary shell commands. It is up to the Runtime to use this representation to be cross-platform (for example, to use it with Windows).

The library does not ensure typeafety but should be expressive enough to describe many CLI calls (and can serve as a basis for slightly stricter libraries).

Types

The way an order is structured respects this logic: cmd_name -a --b foo bar1 bar2:

  • cmd_name is the command name (and is a regular string).
  • -a is a flag and has the type arg
  • --b foo is param and has the type arg.
  • foo, bar1 and bar2 are values, with type value.

A value can be a plain text or a Yocaml.Path.t (that can be watched to form a dependency set).

  # make "a-complicated_command" [
       flag "f";
       flag "w";
       param ~suffix:"=" "priority" @@ s "high";
       param "into" @@ w (Yocaml.Path.rel ["foo"; "bar"; "baz"]);
       arg @@ list ["a"; "b"; "c"; "d"]
    ] ;;
  - : t =
  a-complicated_command -f -w --priority=high --into ./foo/bar/baz a b c d
Sourcetype t

Describe a full command.

Sourcetype arg

Describe an argument of a command.

Sourcetype value

Describe a value.

Building commands

Sourceval make : string -> arg list -> t

make cmd_name args builds a shell command.

Building Arguments

Sourceval flag : ?prefix:string -> string -> arg

flag ?prefix name build a shell flag. The default prefix is -. Ie: flag "foo" is "-foo", but flag ~prefix:"--T" "foo" is "--Tfoo".

  # flag "foo" ;;
  - : arg = -foo
  # flag ~prefix:"--T" "foo" ;;
  - : arg = --Tfoo
Sourceval param : ?prefix:string -> ?suffix:string -> string -> value -> arg

param ?prefix ?suffix key value build a shell labeled argument. The default prefix is -- and the default suffix is " ". A param use the following scheme: prefix^key^suffix^value. Ie: param "foo" (string "bar") is --foo bar, but param ~prefix:"--T" ~suffix:"=" "foo" (int 10) is --Tfoo=10.

  # param "foo" @@ string "bar" ;;
  - : arg = --foo bar
  # param ~prefix:"--T" ~suffix:"=" "foo" @@ int 10 ;;
  - : arg = --Tfoo=10
Sourceval arg : value -> arg

arg x create a plain argument. Ie: arg (string "foo") is foo. Value can be used to deal with non-structured argument, ie: arg (string "--a b --c -d -eee") seems perfectly valid.

Building values

Sourceval string : string -> value

string x build a regular string value.

Sourceval int : int -> value

int x build a value from an integer.

Sourceval char : char -> value

char x build a value from a char.

Sourceval float : float -> value

float x build a value from a float.

Sourceval bool : bool -> value

int x build a value from a list.

Sourceval list : ?sep:string -> string list -> value

list ?sep values collapse a list of string into one argument. By default sep is a space.

The function does not lift an arbitrary list of values, as this would result in the loss of observable paths.

Sourceval path : ?watched:bool -> Path.t -> value

path ?watched p build a value from a path p. If watched is true, the path can be observed as a dependency. (by default, watched is false. )

Sourceval watched : Path.t -> value

watched p is path ~watched:true p.

Shortcuts

As it can be boring to build complex commands, the API provides a few shortcuts:

Sourceval s : string -> value

see string

Sourceval i : int -> value

see int

Sourceval c : char -> value

see char

Sourceval f : float -> value

see float

Sourceval p : ?watched:bool -> Path.t -> value

see path

Sourceval w : Path.t -> value

see watched

Dependencies

When a path is provided to a command, it may or may not be observed as a dependency.

Sourceval deps_of : t -> Path.t list

deps_of cmd gives the set of observed dependencies. For example :

  # deps_of @@ make "foo" [
       param "input"  @@ w (Yocaml.Path.rel ["a"; "b"; "c.txt"])
     ; param "with"   @@ w (Yocaml.Path.rel ["deps.txt"])
     ; param "output" @@ p (Yocaml.Path.rel ["out"; "abc.txt"])
    ] ;;
  - : Yocaml.Path.t list = [./a/b/c.txt; ./deps.txt]

(The output path is not watched).

Helpers

Sourceval pp : Format.formatter -> t -> unit

Pretty-printer for cmd.

Sourceval pp_arg : Format.formatter -> arg -> unit

Pretty-printer for arg.

Sourceval to_string : t -> string

to_string cmd convert a command to a string.

Sourceval normalize : t -> string * string list

normalize cmd return a pair of command and arguments.