This module exports functions for creating executables for funcon interpeters. The executables accepts a number of command line and configuration options that are explained here. The funcons-tools package exports an interpreter for the core library of reusable funcons. This executable is called runfct and is used as an example here.

 dist/build/runfct/runfct <options>

Options

Options are used to change the behaviour of the interpreter and to change the output the interpreter provides after execution. An option is either a boolean-option, a string-option, a .config file or a .fct file. All command line flags are considered from left to right, each changing the current configuration.

1. Funcon term file: A file containing a funcon term. (must have .fct extension). These files contain funcon terms written in prefix form with parentheses surrounding comma-separated arguments, e.g. integer-multiply(6,7). The parser also accepts notation for lists, tuples, sets and map. For example, [1,2,3], (1,2,3), {1,2,3}, and {1 |-> true, 2 |-> false, 3 |-> true } respectively.
2. Configurations file: A file containing configuration options (see below). (must have .config extension)

3. String options (comma-separate strings for multiple inputs):

   • --display-mutable-entity <string>: by default mutable entities are not displayed this option is used to display one or more mutable entities.
   • --hide-output-entity <string>: by default output entities are displayed when output is available. this option is used to hide one or more output entities.
   • --hide-control-entity <string>: by default control entities are displayed when a signal is raised. this option is used to hide one or more control entities .
   • --hide-input-entity <string>: by default input entities are displayed when input has not been consumed. this option is used to hide one or more input entities.
   • --max-restarts <natural>: perform a maximum of n transitive steps, useful for debugging.

4. Boolean options (true, false or no argument (true by default)):

   • --refocus <bool>: use refocusing, only valid under certain conditions.
   • --full-environments <bool>: when printing funcons, display environments using map-notation, by default an environment is printed as "...".
   • --hide-result <bool>: do not show the resulting funcon term.
   • --display-steps <bool>: show meta-information about the interpretation, e.g. the number of steps, rewrites and restarts.
   • --no-abrupt-termination <bool>: disable abrupt termination (affects uncaught control signals).
   • --interactive-mode <bool>: use real I/O for input and output. By default I/O is simulated and all input is expected to be provided in a configuration file (see below) and output is collected and displayed after execution is finished. In interactive mode, the user has to provide input via the standard input, and output is printed to the standard output as soon as it is available.
   • --string-inputs <bool>: by default input is parsed into a Values. This option tells the interpreter to yield the given string as input.
   • --format-string-outputs <bool>: if all output values are strings (and with this option on), any escape characters are interpreted (e.g. "\n" becomes an actual newline), and the strings are concatenated and not enclosed in double quotes.
   • --hide-tests <bool>: do not execute tests (by default tests are executed if specified in a configuration file).
   • --show-output-only <bool>: print only output (omits all other information).
   • --auto-config <bool>: if a .fct file is given, search for a .config file with the same name and apply it (on by default).

Configuration files

A configuration file is a sequence of fragments, where each fragment is of the form:

<group> {
   <keyvalue>*
}

A <keyvalue> is a colon separated key-value pair, closed off by a semicolon, e.g.

hide-control-entity: failed,thrown;

There are 4 valid groups: general, funcons, tests and inputs.

1. general: The general group is used as an alternative to command line flags, All Boolean and string options are available. Additionally, the option "funcon-term" is available for giving an initial funcon term:

   general {
       funcon-term: integer-add(3,2);
   }

2. funcons: This group is used to define simple (nullary) funcons. They key is the name of the funcon, the value is a funcon term to which the funcon will rewrite once evaluated. Keys and values are separated by '=' in this group. This group is useful to choose an interpretation for unspecified components of a language specification. For example (from a Caml Light specification):

   funcons {
       implemented-vectors        = vectors(values);
       implemented-floats-format  = binary64;
       implemented-integers-width = 31;
       implemented-characters     = unicode-characters;
       implemented-strings        = strings;
   }

3. tests: With this group unit-tests can be defined. Each key-value pairs specifies the expected value of a semantic entities, where the key is the name of a semantic entity and the value is the expected value. Additionally, the key "result-term" can be used to specify the expected result term. The tests group is useful to specify a complete unit-test in a single file, e.g.

   general {
       funcon-term: else(integer-add(integer-add(2,3),fail),print(3));
   }
   tests {
      result-term: ();
      standard-out: [3];
   }

4. inputs: The inputs group is used to specify default values for input entities, e.g.

   inputs {
       standard-in: [1,2,3];
   }

   When input entities are given default values, simulation mode is turned on (even if --interactive-mode is used).

Languages specific interpreters

This package does not provide just one interpreter, it provides the ability to play `mix and match' with FunconLibrarys to form interpreters. This enables the creation of interpreters for object languages from funcons (entities, or datatypes) specific to that object language.

For this purpose, this module exports mkMainWithLibraryEntitiesTypes (and variants). Say that a module exporting a FunconLibrary is a "funcon module". An interpreter is obtained by importing the chosen "funcon modules" and uniting their FunconLibrarys (with libUnions), perhaps together with default values for entities (EntityDefault) and information about custom datatypes (TypeRelation). The resulting maps are given as arguments to mkMainWithLibraryEntitiesTypes (or variant). By using mkMainWithLibraryEntitiesTypes, all interpreters inherit the core reusable funcon library.