Module System

module System: sig  end

System-related functions: command, i/o, etc.

 'beep : any -> any

Make a sound and print a beep on standard output. The returned value is the argument. The number of calls to this function can be monitored. This function is used for debugging purposes.
See : beep_cpt
See : beep_cpt_reset
See : !!

 'beep_cpt : unit -> int

Beep count. Returns the number of calls to the function beep since the last call to beep_cpt_reset (or since the begining of the program if no call to beep_cpt_reset has occured).
See : beep
See : beep_cpt_reset

 'beep_cpt_reset : any -> int

Reset the counter of calls to the function beep to zero. The value 0 is returned.
See : beep
See : beep_cpt

 '<< : string -> any -> string

"file" << v outputs the text representation of the value v in the file specified by "file". The value returned by this expression is "file", so such expressions can be easely chained; for example:

  "file" << v1 << v2 << v3 << "\n"

The '<< operator is infix and its first argument must evaluate to a string "file" which can be either:

1. the string "stdout" (which is the value of the variable 'stdin)
2. the string "stderr" (which is the value of the variable 'stderr)
3. a relative path or an absolute path to an executable file
4. a relative path or an absolute path to a non-existing or to a non executable file

and refers abstractly to a output which can be (1) the standard output of the running MGS program, (2) the standard output for error of the running MGS program, (3) the standard input of a process or (4) an ordinary file.

If "file" refers to a non-existent or an existing file which is not an executable, then the file is created if needed or truncated to an empty file (if the file preexists). The successive "file" << ... operations write their arguments to this file.

If "file" is the path of an existing file which is executable, then this command is run and the successive "file" << ... operations send their arguments to the standard input of this process. This is the way to achieve a pipe to an external process in MGS.

An abstract output "file" can be closed explicitly with a call to close("file"). Closing a process also terminates this process. If a command "file" << ... is executed after a close("file"), then the file is re-opened (if "file" refers to a real file, it means, that the data previously written to "file" are lost because the file will be truncated during its reopening). All opened outputs that remain open at the exit of the MGS interpreter will be explicitely closed.

For example, the evaluation of the expression:

  "/usr/bin/gnuplot" << "plot cos(x) ;\n";; 

will open a pipe to a new process gnuplot and send to it the commands that draws the graph of the function cos. The subsequent command

 "/usr/bin/gnuplot" << "plot x+sin(x) ;\n";; 

will replace the plot of the cos function by the plot of the x+sin(x) function in the window opened by gnuplot. An additional

 
  close("/usr/bin/gnuplot");;
  

command will kill the process and the window opened by gnuplot is closed.

Sometimes there is a need to open a pipe to several instances of the same executable. For example suppose that you want to plot simultaneously two functions with gnuplot. It is possible to tell gnuplot to draw the second function in a second window. It is simpler to spawn two processes. The '<< cannot be used the second time to spawn the second process and the function '<<< must be used instead.
See : stdout
See : stderr
See : close
See : print_coll
See : <<<

 '<<< : string -> any -> string

Force the opening of a file. The expression "file" <<< exp force the opening of an output called file even if its already opened. Then exp is outputed. The returned value is a unique string that identifies the new output and that must be used jointly with << for the subsequent outputs.
See : <<

 'close : string -> undef

Close a file. Returns <undef: close>.
See : <<

 'read_line : string

read_line(str) returns a line from the file str.
See : <<

 'open : string -> int

open(str, io) opens file str for input (io = 0) or output (io = 1) and returns the file descriptor associated to it.

 'fold_io : funct -> any -> string

fold_io(f, zero, str) applys the binary function f to the lines of the file str and replaces EOF by the zero argument.

 'print_coll : string ->
       collection ->
       funct -> any -> any -> any -> string

Print a collection with prefix, infix and suffix strings. print_coll(file, coll, f, prefix, infix, suffix) outputs in file file, the elements of the collection coll in the following way:

• first the ascii representation of prefix is written,
• then all elements e are enumerated and the ascii representations of f(e) are outputed. The values are separated by the ascii representation of infix.
• Finally, the ascii representation of suffix is written

Example :

print_coll(stdout, (1, 2, 3), (\x."toto-"+x), "(|", " : ", "|)")

writes to the standard output

(|toto-1 : toto-2 : toto-3|)

and then returns "stdout" (the value of the predefined variable stdout).
See : print_coll2
See : <<
See : stdout
See : stderr

 'uprint_coll : string ->
       collection ->
       funct -> any -> any -> any -> string

Has the same behavior as print_coll, without any automatical indentation.
See : print_coll
See : <<
See : stdout
See : stderr

 'print_coll2 : string -> seq -> any -> string

Print a nested collection with prefix, infix and suffix strings. print_coll(file, desc, coll) outputs in file file, the elements of the collection coll following the description specified by desc. This argument is a list of lists. Each sublist l correspond the the specification of the printing behavior of a collection type.

A sublist l is a list made of five elements (pred, f, prefix, infix, suffix) with the following meaning: pred is a predicate applied to an element e of the collection to be printed if e is itself a collection. When returning true, the arguments f, prefix, infix and suffix are used to print e in a way similar to print_coll. However, if e contains itself other collections, the procedure applies recursively. If pred(e) returns false, another sublist l is looked. I there are no specification that applies, e is printed as usual.
Example :Let

desc :=  ((set, (\x.x), "{", ";", "}")

        ::(seq, (\x.x), "<", ".", ">")

        ::seq:());; 

a list of two sublists l1 and l2. The first sublist l1 specifies that sets must be printed between brackets with the element printed as such and separated by a ;. The sublist l2 specifies that sequence must be printed between < and > with the elements separated by a dot. The list desc can be used to print the nested collection

nested_coll :=   (1, 2, 3)    

               ::(4, 5, 6, set:()))    

               ::(7::8::9::(11, 12, 13)::(14,15,16, set:())::seq:()))    

               ::(17::18::19::(21, 22, 23)::(24,25,26, set:())::set:()))    

               ::seq:() ;;    

and the result of

print_coll2(stdout, desc, nested_coll)

prints on the standard output:

<<1.2.3 >.{4;5;6 }.<7.8.9.<11.12.13 >.{14;15;16 } >. 

 {17;18;19;<21.22.23 >;{24;25;26 } } > 

See : print_coll
See : <<
See : stdout
See : stderr

 'trace : string -> undef

Trace the function calls. trace takes as argument the name a string that represents the name of a function. It returns <undef>. All subsequent calls to this function are traced on the standard output. This function can be used to debug programs.

Beware that all function calls are curryed. So, there are several lines written to the standard output for the application of a n-ary function to several arguments. For example, if we suppose that the function 'add is traced, the expression add(2, 3) produces an output:

'add(2) ->

'add(2) <- [funct]

'add(2)(3) ->

'add(2)(3) <- 5

that must be interpreted in the following way: 'add(2) -> indicates the application of 'add to the argument 2. The result of this function call is a function, as indicated by the line 'add(2) <- [funct]. This function is applied to the argument 3 and the result is 5 as indicated by the line 'add(2)(3) <- 5.

Here is another example. We define a function fib :

fun fib(x) = if x <= 1 then 1 else fib(x-1) + fib(x-2) fi;;

If the tracing of fib is enabled, then the call fib(3) produces:

fib(3) ->

  fib(2) ->

    fib(1) ->

    fib(1) <- 1

    fib(0) ->

    fib(0) <- 1

  fib(2) <- 2

  fib(1) ->

  fib(1) <- 1

fib(3) <- 3

The indentation corresponds to the level of the nesting of calls.

Function can also be traced using the command at the top-level of the MGS interpreter (typing !help;; at top-level gives a short summary of the available commands).
See : 'untrace

 'untrace : string -> undef

Untrace the function calls. untrace takes as argument the name a string that represents the name of a traced function. It returns <undef>. The tracing of the calls to this function are stopped.
See : 'trace

 'set_error_handler : funct -> funct

Change the current error handler. The error handler is a function that accept one string argument. This function is called after the evaluation has been interupted by an error, and before the computation resume at top-level. The value returned is the previous error handler.

The handling of errors is parameterized by three boolean parameters silent_error, abort_on_error and exit_on_error. These parameters can be set with a top-level command of the interpreter:

!set xxx := exp ;;

where xxx is one of the previous parameters and exp is an expression whose value is used as a boolean:

• If silent_error is set to true, then no message are emitted to warn the user during the handling of an error. The default value is false, which means that some output are done using the standard output error. The precise behavior of the error handling procedure is fixed by the following two parameters.
• If exit_on_error is set to true, then the entire MGS interpreter is aborted. If exit_on_error is set to false (the default), then the behavior is fixed by the last parameter.
• If abort_on_error is false, then the current error handler is called with a string sss which gives some clue on the cause of the error. The default error handler use this string to return an undef value <undef: sss>. An user that provides it own error handler can use this string to take some action. Beware that if an error occurs in the evaluation of the error handler, an infinite loop may occur. The value returned by the current error handler is then used to resume the evaluation. This value becomes the value of the faulty expression and the evaluation proceed. Beware that if silent_error is true, then there is no indication that an error has happened.

  If abort_on_error is true (the default value) then the evaluation process is stoped and the top-level is restarted (i.e. the error handler is not called at all).

See : 'reset_default_error_handler
See : 'abort
See : 'exit

 'reset_default_error_handler : funct

This function with no argument changes the current error handler for the default one. The value returned is the previous error handler. Beware that reseting the default error handler does not reset the three parameters silent_error, abort_on_error and exit_on_error to their default value (i.e. respectively false, true and false).
See : 'set_error_handler

 'exit : any -> undef

Exit the evaluation. This function never returns. The entire evaluation is aborted and the interpreter exited. If the argument of exit is an integer, then this integer is returned as the result of the program evaluation to the shell. If the argument is not an integer, the process exit with the value 2.
See : 'abort
See : '!!
See : 'set_error_handler
See : 'reset_default_error_handler

 'sleep : int

Halts the computation for a given number of seconds

 'abort : any -> undef

Abort the evaluation. This function never returns. The entire evaluation is aborted and the interpreter returns to the top-level. If the argument of abort is a string, then this string is used in a warning emited to the user. If the argument is not a string, it is simply ignored.
See : 'exit
See : '!!
See : 'set_error_handler
See : 'reset_default_error_handler

 'top_level : any -> bool

Change the top-level for a user function. The top-level can be changed for a user-defined function set to the parameter top-level:

 !set top_level := f 

where f is a user defined function that takes no argument and returns a value interpreted as a boolean. If the argument of the parameter is not a function, the default top-level is restored. Recall that setting a parameter is a command of the interpreter, not an MGS expression. Such command can be issued only at the standard top-level.

Another way to change the top_level is to call the function 'top_level(f). The change is effective only after the current top_level exit which can be long away. The returned value is the current user-top-level or an <undef> value if the current top-level is the default one.

If the function f returns a value that is interpreted as true, then the interpreter exit gracefully (as if the input stream is exhausted). If the function f returns a value that is interpreted as false, then this function is called again.

The standard top-level parses the input stream and display the results. The standard top-level returns after the processing of a complete sentence. It returns also when an error is encountered. The standard top-level always returns false except when an end-of-file is encountered in the input stream.

A user-top-level is a function that can do any mgs computation. For instance, it can open a file, then read and eval the content of this file (using e.g. 'read_lineor 'fold_io and 'parse).

The processing of the command-line, as well as the processing of the errors, is not part of the top-level function.
Example :

    a := 0;; 

    fun top(x) = begin ?("OK"); a := a+1; (a > 100) end;;

    !set top_level := top;; 

prints alist of 100 OK to the standard ouput and then exit.
See : 'exit
See : 'abort
See : 'fold_io
See : 'parse
See : 'set_error_handler
See : 'reset_default_error_handler

 'while : funct -> funct

The while operator. The expression while (c) do e evaluates the expression e until the expression c evaluates to false. The returned value is the value of e; if c evaluates to false at the first iteration the returned value is <undef>.

The expression while (c) do e is converted into the expression 'while(\x.c, \y.e) where x and y are fresh variables. Beware that the function 'while cannot be accessed with the unquoted notation because while is a keyword.
Example :

while (true) do ?("OK\n");;

prints an infinite list of OK to the terminal.

 'listvar : undef

Return a sequence of strings. The strings are the name of all defined variables in the system (both user and predefined variables). Predefined variables are quoted.

 '? : any -> any

?(v) print the ascii representation of the value v to the standard output and then return v.
See : <<
See : stdout

 'parse : string -> undef

Parse and evaluate a string.

The argument is a string that represents a valid MGS expression. This expression is parsed and evaluated. The returned value is always <undef: parse>, so this function is useful only if the evaluation induces some side effects. For instance, in the evaluation of this sequentials statments:

a := 0; parse("a := 1;;")

the evaluation of parse changes the value refered by a (the evaluation of a now returns 1). Note the ;; needed to indicate the end of the statment and force its evaluation (without the final ;; the parser waits for a possible completion of the command and the evaluation is not triggered).

 'system : string -> undef

Execute a shell command. The returned value is <undef: ...ok exited>.

 '!! : any -> any

Assertion. The argument is evaluated and if it corresponds to a false value, then the entire evaluation is aborted with a message given the text of the argument in the program and the results of its evaluation. If the argument evaluates to a value v corresponding to a true value, then the returned value is v and the evaluation continue.