From 0379e505a152a0aa52fe83f36efcd1b1d604d919 Mon Sep 17 00:00:00 2001 From: Dmitry Boulytchev Date: Mon, 10 Feb 2020 19:09:59 +0300 Subject: [PATCH] Std in Spec --- doc/spec/06.standard_library.tex | 89 +++++++++++++++++++++----------- doc/spec/spec.bib | 7 +++ doc/spec/spec.tex | 3 ++ 3 files changed, 68 insertions(+), 31 deletions(-) diff --git a/doc/spec/06.standard_library.tex b/doc/spec/06.standard_library.tex index bb3e2d4cc..7d0e6aba1 100644 --- a/doc/spec/06.standard_library.tex +++ b/doc/spec/06.standard_library.tex @@ -5,51 +5,78 @@ The standard library is comprised of the runtime for the language and the set of \section{Unit \texttt{Std}} -The unit "\texttt{Std}" provides the interface for the runtime of the language. The implementation of -entities, defined in "\texttt{Std}", reside in the runtime itself. The import of "\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: -\paragraph{\lstinline|fun read ()|}~--- reads an integer value from the standard input, printing a prompt "\texttt{>}". +\descr{\lstinline|fun read ()|}{Reads an integer value from the standard input, printing a prompt "\lstinline|>|".} -\paragraph{\lstinline|fun write (int)|}~--- writes an integer value to the standard output. +\descr{\lstinline|fun write (int)|}{Writes an integer value to the standard output.} -\paragraph{\lstinline|sysargs|}~--- a variable which holds an array of command-lines arguments of the application (including the -name of the executable itself). +\descr{\lstinline|sysargs|}{A variable which holds an array of command-line arguments of the application (including the +name of the executable itself).} -\paragraph{\lstinline|fun makeArray (size)|}~--- creates a fresh array of a given length. The elements of the array are left uninitialized. +\descr{\lstinline|fun makeArray (size)|}{Creates a fresh array of a given length. The elements of the array are left uninitialized.} -\paragraph{\lstinline|fun makeString (size)|}~--- creates a fresh string of a given length. The elements of the string are left uninitialized. +\descr{\lstinline|fun makeString (size)|}{Creates a fresh string of a given length. The elements of the string are left uninitialized.} -\paragraph{\lstinline|fun stringcat (list)|}~--- takes a list of strings and returns the concatenates all its elements. +\descr{\lstinline|fun stringcat (list)|}{Takes a list of strings and returns the concatenates all its elements.} -\paragraph{\lstinline|fun matchSubString (subj, patt, pos)|}~--- takes two strings "\texttt{subj}" and "\text{patt}" and integer position "\texttt{pos}" and -checks if a substing of "\texttt{subj}" starting at position "\texttt{pos}" is equal to "\text{patt}"; returns integer value. +\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.} -\lstinline|fun sprintf (fmt, ...)| -\lstinline|fun substring (str, pos, len)| -\lstinline|infix ++ at + (str1, str2)| +\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.} -\lstinline|fun clone (value)| -\lstinline|fun hash (value)| -\lstinline|fun compare (value1, value2)| +\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|.} -\lstinline|fun fst (value)| -\lstinline|fun snd (value)| -\lstinline|fun hd (value)| -\lstinline|fun tl (value)| +\descr{\lstinline|infix ++ at + (str1, str2)|}{String concatenation infix operator.} -\lstinline|fun readLine ()| -\lstinline|fun printf (fmt, ...)| -\lstinline|fun fopen (fname, mode)| -\lstinline|fun fclose (file)| -\lstinline|fun fread (fname)| -\lstinline|fun fwrite (fname, contents)| -\lstinline|fun fprintf (file, fmt, ...)| +\descr{\lstinline|fun clone (value)|}{Performs a shallow cloning of the argument value.} -\lstinline|fun regexp (str)| -\lstinline|fun regexpMatch (pattern, subj, pos)| +\descr{\lstinline|fun hash (value)|}{Returns integer hash for the argument value; also works for cyclic data structures.} -\lstinline|fun failure (fmt, ...)| +\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.)} diff --git a/doc/spec/spec.bib b/doc/spec/spec.bib index 6bf414b15..c8e818e89 100644 --- a/doc/spec/spec.bib +++ b/doc/spec/spec.bib @@ -4,3 +4,10 @@ bibdate = "February 24, 2019", bibsource = "https://www.gnu.org/software/gnulib/manual" } + +@manual{GNUCLib, + title = "{The GNU C Library}", + organization = "{Free Software Foundation}", + bibdate = "February 1, 2020", + bibsource = "https://www.gnu.org/software/libc/manual" +} \ No newline at end of file diff --git a/doc/spec/spec.tex b/doc/spec/spec.tex index 1bd2343b9..12c98296c 100644 --- a/doc/spec/spec.tex +++ b/doc/spec/spec.tex @@ -27,6 +27,7 @@ \usepackage{placeins} \usepackage{xspace} \usepackage{bm} +\usepackage{enumitem} \makeatletter @@ -85,6 +86,8 @@ \newcommand{\alt}{\s\mid\s} \newcommand{\s}{\:\:} +\newcommand{\descr}[2]{\smallskip{#1}\begin{itemize}[noitemsep,topsep=0pt]\item[]{#2}\end{itemize}} + \lstdefinelanguage{alm}{ keywords={skip,if,then,else,elif,fi,while,do,od,repeat,until,for,fun,local,public,return,import,length, string,case,of,esac,when,boxed,unboxed,string,sexp,array,infix,infixl,infixr,at,before,after,true,false},