package genspio

  1. Overview
  2. Docs

Compiler from EDSL.t to POSIX shell scripts (one-liners or multiline scripts).

type internal_error_details = Standard_compiler.internal_error_details = {
  1. variable : string;
    (*

    The incriminated issue was stored in a shell variable.

    *)
  2. content : string;
    (*

    The shell-code that produced the variable.

    *)
  3. code : string;
    (*

    Pretty-printed version of the above EDSL code.

    *)
}

When a compiled script runs into an error, these details are accessible to the user.

type death_message = Standard_compiler.death_message =
  1. | User of string
    (*

    The argument of the EDSL.fail is the “user” case.

    *)
  2. | C_string_failure of internal_error_details
    (*

    The checking that a byte-array is a C-String can fail when the byte-array contains '\x00'.

    *)
  3. | String_to_int_failure of internal_error_details
    (*

    string_to_int can obviously fail.

    *)

The kinds of messages that can be output or stored before exiting a script.

type death_function = comment_stack:string list -> death_message -> string

When failing (either with EDSL.fail or because of internal reasons) the compiler uses a customizable function to output the “error” message and then quiting the process.

type compilation_error = Standard_compiler.compilation_error = {
  1. error : [ `No_fail_configured of death_message | `Max_argument_length of string | `Not_a_c_string of string ];
    (*

    Error description.

    *)
  2. code : string option;
    (*

    Chunk of relevant, pretty-printed EDSL code.

    *)
  3. comment_backtrace : string list;
    (*

    Stack of `Comment` constructs at the point of the error.

    *)
}

The potential compilation error.

val pp_error : Format.formatter -> compilation_error -> unit

Printer for error values.

val error_to_string : compilation_error -> string

Convenience display of error values.

type parameters = {
  1. style : [ `Multi_line | `One_liner ];
    (*

    The kind of script to output: in one-liners sequences are separated with ";", in multi-line scripts, sequences are separated with new lines.

    *)
  2. max_argument_length : int option;
    (*

    A limit on the length of the literal command line arguments generated by the compiler.

    • None means “do not check.”
    • The default value for is Some 100_000, meaning that ≥ 100 000 B arguments will make the compiler fail with an exception.
    *)
  3. fail_with : [ `Kill of string | `Nothing | `Trap_and_kill of int * string ];
    (*

    How to implement the EDSL.fail construct (which appears also internally e.g. when EDSL.to_c_string fails.).

    • `Nothing: the compiler will fail to compile fail constructs.
    • `Kill signal_name: the compiler will store the “toplevel” process id of the script and EDSL.fail will be trying to kill the script with the signal signal_name (e.g. "USR2").
    • `Trap_and_kill (exit_status, signal_name): the EDSL.fail construct will kill the script with signal_name and the signal will be caught with the POSIX "trap" command in order to exit with exit_status.
    *)
  4. print_failure : death_function;
    (*

    How to deal with the death_message in case of failure. The function should return a shell command, like the result of compiling a unit EDSL.t expression or what Sys.command can work with.

    *)
}

Configuration of the compilation to POSIX shell scripts.

val failure_to_stderr : death_function

The default death_function just prints to stderr.

val one_liner : parameters

The default parameters for one-liners: 

{
  style = `One_liner;
  max_argument_length = Some 100_000;
  fail_with = `Trap_and_kill (78, "USR2");
  print_failure = failure_to_stderr;
}
val multi_line : parameters

The default parameters for multi-liners (similar to one_liner).

val default_options : parameters

The default value for ?option in string, which is one_liner.

val string : ?options:parameters -> 'a EDSL.t -> (string, compilation_error) result

Compile a Genspio expression to a POSIX shell “phrase” (one-liner or multi-line) according to the ?options (see parameters).