diff --git a/doc/spec/06.standard_library.tex b/doc/spec/06.standard_library.tex index 9c868f47a..9ac7f9dcc 100644 --- a/doc/spec/06.standard_library.tex +++ b/doc/spec/06.standard_library.tex @@ -4,6 +4,7 @@ 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}} +\label{sec: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|" @@ -81,6 +82,7 @@ is automatically created and closed within the call.} prints these parameters according to the format string on the standard error and exits. Note: indexed arguments are not supported.)} \section{Unit \texttt{Array}} +\label{sec:array} Array processing functions: @@ -97,10 +99,10 @@ Array processing functions: \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.} + is the left-to-right manner. The function "\lstinline|f|" takes two arguments~--- an accumulator and an array element.} \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.} + is the right-to-left manner. The function "\lstinline|f|" takes two arguments~--- an accumulator and an array element.} \descr{\lstinline|fun iterArray (f, a)|}{Applies a function "\lstinline|f|" to each element of an array "\lstinline|a|"; does not return a value.} @@ -108,13 +110,103 @@ Array processing functions: does not return a value.} \section{Unit \texttt{Collection}} +\label{sec:collection} -Collections, implemented as AVL-trees. Three types of collections are provided: sets of ordered elements, maps of ordered keys +Collections, implemented as AVL-trees. Four types of collections are provided: sets of ordered elements, maps of ordered keys to other values, memo +tables and hash tables. For sets and maps the generic "\lstinline|compare|" function from the unit "\lstinline|Std|" is used +as ordering relation. For memo table and hash tables the comparison of generic hash values, delivered by function "\lstinline|hash|" of unit "\lstinline|Std|" +is used. +\subsection{Maps} + +Maps are immutable structures with the following interface: + +\descr{\lstinline|fun emptyMap ()|}{Creates an empty map.} + +\descr{\lstinline|fun addMap (m, k, v)|}{Adds a binding of a key "\lstinline|k|" to a value "\lstinline|v|" into a map "\lstinline|m|". As a result, a new map is +returned.} + +\descr{\lstinline|fun findMap (m, k)|}{Finds a binding for a key "\lstinline|k|" in the map "\lstinline|m|". Returns the value "\lstinline|None|" if +no binding is found, and "\lstinline|Some (v)|" if "\lstinline|k|" is bound to "\lstinline|v|".} + +\descr{\lstinline|fun removeMap (m, k)|}{Removes the binding for "\lstinline|k|" from the map "\lstinline|m|" and returns a new map. This function +restores a value which was previously bound to "\lstinline|k|". If there were no binding for "\lstinline|k|" in "\lstinline|m|" then "\lstinline|m|" +is returned unchanged.} + +\descr{\lstinline|fun bindings (m)|}{Returns all bindings for the map "\lstinline|m|" as a list of key-value pairs, in key-ascending order.} + +\descr{\lstinline|fun listMap (l)|}{Converts a list of key-value pairs into a map.} + +\descr{\lstinline|fun iterMap (f, m)|}{Iterates a function "\lstinline|f|" over the bindings of map "\lstinline|m|". The function takes two + arguments (key and value). The bindings are enumerated in an ascending order.} + +\descr{\lstinline|fun mapMap (f, m)|}{Maps a function "\lstinline|f|" over all values of "\lstinline|m|" and returns a new map of results.} + +\descr{\lstinline|fun foldMap (f, acc, m)|}{Folds a map "\lstinline|m|" using a function "\lstinline|f|" and initial value "\lstinline|acc|". +The function takes an accumulator and a pair key-value. The bindings are enumerated in an ascending order.} + +\subsection{Sets} + +Sets are immutable structures with the following interface: + +\descr{\lstinline|fun emptySet ()|}{Creates an empty set.} + +\descr{\lstinline|fun addSet (s, v)|}{Adds an element "\lstinline|v|" into a set "\lstinline|s|" and returns a new set.} + +\descr{\lstinline|fun memSet (s, v)|}{Tests if an element "\lstinline|v|" is contained in the set "\lstinline|s|". Returns zero if +there is no such element and non-zero otherwise.} + +\descr{\lstinline|fun removeSet (s, v)|}{Removes an element "\lstinline|v|" from the set "\lstinline|s|" and returns a new set. Returns the +same set if there were nothing to remove.} + +\descr{\lstinline|fun elements (s)|}{Returns a list of elements of a given set in ascending order.} + +\descr{\lstinline|fun union (a, b)|}{Returns a union of given sets as a new set.} + +\descr{\lstinline|fun diff (a, b)|}{Returns a difference between sets "\lstinline|a|" and "\lstinline|b|" (a set of those elements + of "\lstinline|a|" which are not in "\lstinline|b|") as a new set.} + +\descr{\lstinline|fun listSet (l)|}{Converts a list into a set. } + +\descr{\lstinline|fun iterSet (f, s)|}{Applied a function "\lstinline|f|" to each element of the set "\lstinline|s|". The elements are +enumerated in ascending order.} + +\descr{\lstinline|fun mapSet (f, s)|}{Applies a function "\lstinline|f|" to each element of the set "\lstinline|s|" and returns a new set of images. The +elements are enumerated in an ascending order.} + +\descr{\lstinline|fun foldSet (f, acc, s)|}{Folds a set "\lstinline|s|" unsing the function "\lstinline|f|" and initial value "\lstinline|acc|". The function +"\lstinline|f|" takes two arguments~--- an accumulator and an element of the set. The elements of set are enumerated in an ascending order.} + +\subsection{Memoization Tables} + +Memoization tables can be used for \emph{hash-consing}~\cite{hashConsing}~--- a data transformation which converts structurally equal +data structures into physically equal. Memoization tables are mutable; they do not work for cyclic data structures. + +\descr{\lstinline|fun emptyMemo ()|}{Creates an empty memo table.} + +\descr{\lstinline|fun lookupMemo (m, v)|}{Lookups a value "\lstinline|v|" in a memo table "\lstinline|m|", performing hash-consing and + returning a hash-consed value.} + +\subsection{Hash Tables} + +Hash table is an immutable map which uses hashes as keys and lists of key-value pairs as values. For hashing a generic +hash function is used, the search within the same hash class is linear with physical equality "\lstinline|==|" used for +comparison. + +\descr{\lstinline|fun emptyHashTab ()|}{Creates an empty hash table.} + +\descr{\lstinline|fun addHashTab (t, k, v)|}{Adds a binding of "\lstinline|k|" to "\lstinline|v|" to the hash table "\lstinline|t|" and returns a +new hash table.} + +\descr{\lstinline|fun findHashTab (t, k)|}{Searches for a binding for a key "\lstinline|k|" in the table "\lstinline|t|". Returns "\lstinline|None|" +if no binding is found and "\lstinline|Some (v)|" otherwise, where "\lstinline|v|" is a bound value.} + +\descr{\lstinline|fun removeHashTab (t, k)|}{Removes a binding for the key "\lstinline|k|" from hash table "\lstinline|t|" and returns a new hash table. + The previous binding for "\lstinline|k|" (if any) is restored. If there is no binding for "\lstinline|k|" returns unchanged hash table.} \section{Unit \texttt{Fun}} -Some generic functional stuff: +The unit defines some generic functional stuff: \descr{\lstinline|fun id (x)|}{The identify function.} @@ -141,12 +233,92 @@ Some generic functional stuff: } \section{Unit \texttt{Lazy}} +\label{sec:lazy} + +The unit provides primitives for lazy evaluation. + +\descr{\lstinline|fun makeLazy (f)|}{Creates a lazy value from a function "\lstinline|f|". The function must not require any arguments.} + +\descr{\lstinline|fun force (f)|}{Returns a suspended value, forcing its evaluation if needed.} \section{Unit \texttt{List}} +The unit provides some list-manipulation functions. None of the functions mutate their arguments. + +\descr{\lstinline|fun singleton (x)|}{Returns a one-element list with the value "\lstinline|x|" as its head.} + +\descr{\lstinline|fun size (l)|}{Returns the length of the list.} + +\descr{\lstinline|fun foldl (f, acc, l)|}{Folds a list "\lstinline|l|" with a function "\lstinline|f|" and initial value "\lstinline|acc|" + is the left-to-right manner. The function "\lstinline|f|" takes two arguments~--- an accumulator and a list element.} + +\descr{\lstinline|fun foldr (f, acc, l)|}{Folds a list "\lstinline|l|" with a function "\lstinline|f|" and initial value "\lstinline|acc|" + is the right-to-left manner. The function "\lstinline|f|" takes two arguments~--- an accumulator and a list element.} + +\descr{\lstinline|fun iter (f, l)|}{Applies a function "\lstinline|f|" to the elements of the list "\lstinline|l|" in the +giver order.} + +\descr{\lstinline|fun map (f, l)|}{Maps a function "\lstinline|f|" to the elements of the list "\lstinline|l|" and returns a +fresh list if images in the same order.} + +\descr{\lstinline|infix +++ at + (x, y)|}{Returns the concatenation of lists "\lstinline|x|" and "\lstinline|y|".} + +\descr{\lstinline|fun reverse (l)|}{Reverses a list.} + +\descr{\lstinline|fun assoc (l, x)|}{Finds a value for a key "\lstinline|x|" in an associative list "\lstinline|l|". Returns + "\lstinline|None|" if no value is found and "\lstinline|Some (v)|" otherwise, where "\lstinline|v|"~--- the first value + whise key equals "\lstinline|x|". Uses generic comparison to compare keys.} + +\descr{\lstinline|fun find (f, l)|}{Finds a value in a list "\lstinline|l|" which satisfies the predicate "\lstinline|f|". The + predicate must return integer value, treated as boolean. Returns "\lstinline|None|" if no element satisfies "\lstinline|f|" and + "\lstinline|Some (v)|" otherwise, where "\lstinline|v|"~--- the first value to satisfy "\lstinline|f|". +} + +\descr{\lstinline|fun flatten (l)|}{Flattens a list of lists into a regular list. The order of elements is preserved in both senses.} + +\descr{\lstinline|fun zip (a, b)|}{Zips a pair of lists into the list of pairs. Does not work for lists of different lengths.} + +\descr{\lstinline|fun unzip (a)|}{Splits a list of pairs into pairs of lists.} + +\descr{\lstinline|fun remove (f, l)|}{Removes the first value, satisfying the predicate "\lstinline|f|", from the list "\lstinline|l|". The function +"\lstinline|f|" should return integers, treated as booleans.} + +\descr{\lstinline|fun filter (f, l)|}{Removes all values, not satisfying the predicate "\lstinline|f|", from the list "\lstinline|l|". The function +"\lstinline|f|" should return integers, treated as booleans.} + \section{Unit \texttt{Matcher}} +The unit provides some primitives for matching strings against regular patterns. Matchers are immutable structures which store +string buffers with current positions. Matchers are designed to be used as stream representation for +parsers written using combinators of "\lstinline|Ostap|"; in particular, return values for "\lstinline|endOf|", "\lstinline|matchString|" +and "\lstinline|matchRegexp|" respect the conventions for such parsers. + +\descr{\lstinline|fun createRegexp (r, name)|}{Creates an internal representation of regular expression; argument "\lstinline|r|" is a + string representation of regular expression (as per function "\lstinline|regexp|"), "\lstinline|name|"~--- a string name for +diagnostic purposes.} + +\descr{\lstinline|fun initMatcher (buf)|}{Takes a string argument and returns a fresh matcher.} + +\descr{\lstinline|fun show (m)|}{Returns a printable representation for a matcher "\lstinline|m|" (for debugging purposes).} + +\descr{\lstinline|fun endOf (m)|}{Tests if the matcher "\lstinline|m|" reached the end of string. Return value represents parsing +result as per "\lstinline|Ostap|".} + +\descr{\lstinline|fun matchString (m, s)|}{Tests if a matcher "\lstinline|m|" at current position matches the string "\lstinline|s|". +Return value represents parsing result as per "\lstinline|Ostap|".} + +\descr{\lstinline|fun matchRegexp (m, r)|}{Tests if a matcher "\lstinline|m|" at current position matches the regular expression "\lstinline|r|", which + has to be constructed using the function "\lstinline|createRegexp|". Return value represents parsing result as per "\lstinline|Ostap|".} + \section{Unit \texttt{Ostap}} \section{Unit \texttt{Ref}} +The unit provides an emulation for first-class references. + +\descr{\lstinline|fun ref (x)|}{Creates a mutable reference with the contents "\lstinline|x|".} + +\descr{\lstinline|fun deref (x)|}{Dereferences a reference "\lstinline|x|" and returns stored value.} + +\descr{\lstinline|infix ::= before := (x, y)|}{Assigns a value "\lstinline|y|" to a cell designated by the "\lstinline|x|". Returns "\lstinline|y|".} + diff --git a/doc/spec/spec.bib b/doc/spec/spec.bib index c8e818e89..43d8443c8 100644 --- a/doc/spec/spec.bib +++ b/doc/spec/spec.bib @@ -10,4 +10,22 @@ organization = "{Free Software Foundation}", bibdate = "February 1, 2020", bibsource = "https://www.gnu.org/software/libc/manual" -} \ No newline at end of file +} + +@inproceedings{HashConsing, +author = {Filliundefinedtre, Jean-Christophe and Conchon, Sylvain}, +title = {Type-Safe Modular Hash-Consing}, +year = {2006}, +isbn = {1595934839}, +publisher = {Association for Computing Machinery}, +address = {New York, NY, USA}, +url = {https://doi.org/10.1145/1159876.1159880}, +doi = {10.1145/1159876.1159880}, +booktitle = {Proceedings of the 2006 Workshop on ML}, +pages = {12–19}, +numpages = {8}, +keywords = {data structures, hash-consing, sharing}, +location = {Portland, Oregon, USA}, +series = {ML ’06} +} +