funcons-tools-0.2.0.11: A modular interpreter for executing funcons
Safe HaskellNone
LanguageHaskell2010

Funcons.Tools

Synopsis

Creating standalone interpreters.

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.

mkMain :: IO () Source #

Creates a main function for the default interpreter (no extension). The executable made from this main function receives command line argumenst as explained above (Funcons.Tools).

mkMainWithLibrary :: FunconLibrary -> IO () Source #

Creates a main function for the interpreter obtained by extending the default library with the funcons in the FunconLibrary argument.

mkMainWithLibraryEntities :: FunconLibrary -> EntityDefaults -> IO () Source #

Creates a main function for the interpreter obtained by extending the main interpreter with the funcons in the FunconLibrary argument and with default values for entities defined in the EntityDefaults argument.

mkMainWithLibraryTypes :: FunconLibrary -> TypeRelation -> IO () Source #

Creates a main function for the interpreter obtained by extending the main interpreter with the funcons in the FunconLibrary argument and with a TypeRelation mapping datatypes to their constructors and type arguments.

mkMainWithLibraryEntitiesTypes :: FunconLibrary -> EntityDefaults -> TypeRelation -> IO () Source #

Creates a main function for the interpreter obtained by extending the main interpreter with funcons, EntityDefaults and a TypeRelation.

mkFullyFreshInterpreter :: FunconLibrary -> EntityDefaults -> TypeRelation -> IO () Source #

Creates a main function for the interpreter aware of only the given FunconLibrary, EntityDefaults and TypeRelation.

mkFreshInterpreter :: FunconLibrary -> EntityDefaults -> TypeRelation -> IO () Source #

Creates a main function for the interpreter aware of only the given FunconLibrary, EntityDefaults and TypeRelation, and the built-in types and operations.

Creating embedded interpreters.

run :: [String] -> Maybe Funcons -> IO () Source #

Creates a main function by passing in a list of command line arguments and an optional initial Funcons to execute. The Funcons argument is optional as one of the command line arguments may refer to an .fct file or .config file that specifies an initial Funcons term. Useful when a translation to Funcons has been implemented in Haskell.

runWithExtensions :: FunconLibrary -> EntityDefaults -> TypeRelation -> [String] -> Maybe Funcons -> IO () Source #

Same as run, except receiving additional interpreter extensions as arguments. Useful when a translation to Funcons has been implemented in Haskell as well as Funcons, entities or datatypes specific to the object language. Includes the Core funcons.

runWithExtensionsNoCore :: FunconLibrary -> EntityDefaults -> TypeRelation -> [String] -> Maybe Funcons -> IO () Source #

Same as run, except receiving additional interpreter extensions as arguments. Useful when a translation to Funcons has been implemented in Haskell as well as Funcons, entities or datatypes specific to the object language. Does not include the Core funcons.

runWithExtensionsNoNothing :: FunconLibrary -> EntityDefaults -> TypeRelation -> [String] -> Maybe Funcons -> IO () Source #

Same as run, except receiving additional interpreter extensions as arguments. Useful when a translation to Funcons has been implemented in Haskell as well as Funcons, entities or datatypes specific to the object language. Does not include the Core funcons.

Utility functions for interpreter extensions.

Funcon libraries.

type FunconLibrary = Map Name EvalFunction Source #

A funcon library maps funcon names to their evaluation functions.

libOverrides :: [FunconLibrary] -> FunconLibrary Source #

Right-based union of list of FunconLibrarys

libFromList :: [(Name, EvalFunction)] -> FunconLibrary Source #

Creates a FunconLibrary from a list.

Type environments.

type TypeRelation = Map Name DataTypeMembers Source #

The typing environment maps datatype names to their definitions.

data DataTypeMembers Source #

A datatype has `zero or more' type parameters and `zero or more' alternatives.

Constructors

DataTypeMemberss Name [TPattern] [DataTypeAltt] 

Instances

Instances details
Show DataTypeMembers Source # 
Instance details

Defined in Funcons.Types

data DataTypeAltt Source #

An alternative is either a datatype constructor or the inclusion of some other type. The types are arbitrary funcon terms (with possible variables) that may require evaluation to be resolved to a Types.

Instances

Instances details
Show DataTypeAltt Source # 
Instance details

Defined in Funcons.Types

type TypeParam = (Maybe MetaVar, Maybe SeqSortOp, FTerm) Source #

A type parameter is of the form X:T where the name of the parameter,X, is optional. When present, X can be used to specify the type of constructors. Variable X be a sequence variable.

typeEnvFromList :: [(Name, DataTypeMembers)] -> TypeRelation Source #

Creates a TypeRelation from a list.

Entity declarations

type EntityDefaults = [EntityDefault] Source #

A list of EntityDefaults is used to declare (and possibly initialise) entities.

data EntityDefault Source #

Default values of entities can be specified for inherited and mutable entities.

Constructors

DefMutable Name Funcons 
DefInherited Name Funcons 
DefOutput Name

For the purpose of unit-testing it is advised to notify an interpreter of the existence of control, output and input entities as well.

DefControl Name 
DefInput Name 

noEntityDefaults :: [EntityDefault] Source #

The empty collection of entity defaults.