lama_byterun/doc/spec/06.standard_library.tex

\chapter{Standard Library}
\label{sec:stdlib}

The standard library is comprised of the runtime for the language and the set of pre-shipped units written in \lama itself.

\section{Unit \texttt{Std}}

The unit "\lstinline|Std|" provides the interface for the runtime of the language. The implementation of
entities, defined in "\lstinline|Std|", resides in the runtime itself. The import of "\lstinline|Std|"
is added implicitly by the compiler and can not be specified by an end user.

The following declarations are accessible:

\descr{\lstinline|fun read ()|}{Reads an integer value from the standard input, printing a prompt "\lstinline|>|".}

\descr{\lstinline|fun write (int)|}{Writes an integer value to the standard output.}

\descr{\lstinline|sysargs|}{A variable which holds an array of command-line arguments of the application (including the
name of the executable itself).}

\descr{\lstinline|fun makeArray (size)|}{Creates a fresh array of a given length. The elements of the array are left uninitialized.}

\descr{\lstinline|fun makeString (size)|}{Creates a fresh string of a given length. The elements of the string are left uninitialized.}

\descr{\lstinline|fun stringcat (list)|}{Takes a list of strings and returns the concatenates all its elements.}

\descr{\lstinline|fun matchSubString (subj, patt, pos)|}{Takes two strings "\lstinline|subj|" and "\lstinline|patt|" and integer position "\lstinline|pos|" and
checks if a substing of "\lstinline|subj|" starting at position "\lstinline|pos|" is equal to "\lstinline|patt|"; returns integer value.}

\descr{\lstinline|fun sprintf (fmt, ...)|}{Takes a format string (as per GNU C Library~\cite{GNUCLib}) and a variable number of arguments and
returns a string, acquired via processing these arguments according to the format string. Note: indexed arguments are not supported.}

\descr{\lstinline|fun substring (str, pos, len)|}{Takes a string, an integer position and length, and returs a substring of requested length of
  given string starting from given position. Raises an error if the original string is shorter then \lstinline|pos+len-1|.}

\descr{\lstinline|infix ++ at + (str1, str2)|}{String concatenation infix operator.}

\descr{\lstinline|fun clone (value)|}{Performs a shallow cloning of the argument value.}

\descr{\lstinline|fun hash (value)|}{Returns integer hash for the argument value; also works for cyclic data structures.}

\descr{\lstinline|fun compare (value1, value2)|}{Performs a structural deep comparison of two values. Determines a
  linear order relation for every pairs of values. Returns \lstinline|0| if the values are structurally equal, negative or
  positive integers otherwise. May not work for cyclic data structures.}

\descr{\lstinline|fun fst (value)|}{Returns the first subvalue for a given boxed value.}

\descr{\lstinline|fun snd (value)|}{Returns the second subvalue for a given boxed value.}

\descr{\lstinline|fun hd (value)|}{Returns the head of a given list.}

\descr{\lstinline|fun tl (value)|}{Return the tail of a given list.}

\descr{\lstinline|fun readLine ()|}{Reads a line from the standard input and returns it as a string.}

\descr{\lstinline|fun printf (fmt, ...)|}{Takes a format string (as per GNU C Library~\cite{GNUCLib} and a variable number of arguments and
prints these arguments on the standard output, according to the format string.}

\descr{\lstinline|fun fopen (fname, mode)|}{Opens a file of given name in a given mode. Both arguments are strings, the return value is
an external pointer to file structure.}

\descr{\lstinline|fun fclose (file)|}{Closes a file. The file argument should be that acquired by "\lstinline|fopen|" function.}

\descr{\lstinline|fun fread (fname)|}{Reads a file content and returns it as a string. The argument is a file name as a string, the file
is automatically open and closed within the call.}

\descr{\lstinline|fun fwrite (fname, contents)|}{Writes a file. The arguments are file name and the contents to write as strings. The file
is automatically created and closed within the call.}

\descr{\lstinline|fun fprintf (file, fmt, ...)|}{Same as "\lstinline|printf|", but outputs to a given file. The file argument should be that acquired
  by \lstinline|fopen| function.}

\descr{\lstinline|fun regexp (str)|}{Compiles a string representation of a regular expression (as per GNULib's regexp~\cite{GNULib}) into
  an internal representation. The return value is a external pointer to the internal representation.}

\descr{\lstinline|fun regexpMatch (pattern, subj, pos)|}{Matches a string "\lstinline{subj}", starting from the position "\lstinline|pos|",
  against a pattern "\lstinline{pattern}". The pattern is an external pointer to a compiled representation, returned by the
  function "\lstinline|regexp|". The return value is the number of matched characters.}

\descr{\lstinline|fun failure (fmt, ...)|}{Takes a format string (as per GNU C Library~\cite{GNUCLib}, and a variable number of parameters,
  prints these parameters according to the format string on the standard error and exits. Note: indexed arguments are not supported.)}

\section{Unit \texttt{Array}}

Array processing functions:

\descr{\lstinline|fun initArray (n, f)|}{Takes an integer value "\lstinline|n|" and a function "\lstinline|f|" and creates an array
  \[
     \mbox{\lstinline|[f (0), f (1), ..., f (n-1)]|}
  \]
}

\descr{\lstinline|fun mapArray (f, a)|}{Maps a function "\lstinline|f|" over an array "\lstinline|a|" and returns a new array.}

\descr{\lstinline|fun arrayList (a)|}{Converts an array to list (preserving the order of elements).}

\descr{\lstinline|fun listArray (l)|}{Converts a list to array (preserving the order of elements).}

\descr{\lstinline|fun foldlArray (f, acc, a)|}{Folds an array "\lstinline|a|" with a function "\lstinline|f|" and initial value "\lstinline|acc|"
  is the left-to-right manner.}

\descr{\lstinline|fun foldrArray (f, acc, a)|}{Folds an array "\lstinline|a|" with a function "\lstinline|f|" and initial value "\lstinline|acc|"
  is the right-to-left manner.}

\descr{\lstinline|fun iterArray (f, a)|}{Applies a function "\lstinline|f|" to each element of an array "\lstinline|a|"; does not return a value.}

\descr{\lstinline|fun iteriArray (f, a)|}{Applies a function "\lstinline|f|" to each element of an array "\lstinline|a|" and its index (index first);
  does not return a value.}

\section{Unit \texttt{Collection}}

Collections, implemented as AVL-trees. Three types of collections are provided: sets of ordered elements, maps of ordered keys 


\section{Unit \texttt{Fun}}

Some generic functional stuff:

\descr{\lstinline|fun id (x)|}{The identify function.}

\descr{\lstinline[mathescape=false]|infixl $ after := (f, x)|}{Left-associative infix for function application.}

\descr{\lstinline|infix # after * (f, g)|}{Non-associative infix for functional composition.}

\newsavebox\factbox

\begin{lrbox}{\factbox}
\begin{lstlisting}
    fix (fun (f) { 
           fun (n) { 
             if n == 1 then 1 else n * f (n-1) fi
           }
         })     
\end{lstlisting}
\end{lrbox}

\descr{\lstinline|fun fix (f)|}{Fixpoint combinator. The argument is a knot-accepting function, thus a factorial can be
  defined as

  \usebox\factbox
}

\section{Unit \texttt{Lazy}}

\section{Unit \texttt{List}}

\section{Unit \texttt{Matcher}}

\section{Unit \texttt{Ostap}}

\section{Unit \texttt{Ref}}