Verified Commit c45fca76 authored by Camil Staps's avatar Camil Staps 🚀

Documentation

parent 38755ec5
system module StdBool
/**
* Class instances and basic functions for the Bool type.
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 3.0
// Copyright 2019 University of Nijmegen
......@@ -16,8 +20,30 @@ instance fromBool {#Char} :: !Bool -> {#Char} :== code { .d 0 1 b ; jsr Bto
// Additional Logical Operators:
/**
* Logical negation.
*
* @param The boolean to negate
* @result True if the parameter was False; False if True
*/
not :: !Bool -> Bool :== code { notB }
// Not arg1
(||) infixr 2 :: !Bool Bool -> Bool // Conditional or of arg1 and arg2
(&&) infixr 3 :: !Bool Bool -> Bool // Conditional and of arg1 and arg2
/**
* Logical disjunction. The second parameter is not strict and will not be
* evaluated if the first parameter is True.
*
* @param First boolean
* @param Second boolean
* @result True iff at least one of the parameters is True
*/
(||) infixr 2 :: !Bool Bool -> Bool
/**
* Logical conjunction. The second parameter is not strict and will not be
* evaluated if the first parameter is False.
*
* @param First boolean
* @param Second boolean
* @result True iff both parameters are True
*/
(&&) infixr 3 :: !Bool Bool -> Bool
system module StdChar
/**
* Class instances and basic functions for the Char type.
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 3.0
// Copyright 2019 University of Nijmegen
......@@ -24,20 +28,116 @@ instance fromChar {#Char} :: !Char -> {#Char} :== code { CtoAC }
// Additional conversions:
digitToInt :: !Char -> Int // Convert Digit into Int
toUpper :: !Char -> Char // Convert Char into an uppercase Char
toLower :: !Char -> Char // Convert Char into a lowercase Char
/**
* Converts a character from ['0'..'9'] to an integer.
*
* @param The character
* @result 0-9 if the character was from ['0'..'9'], otherwise another Int
*/
digitToInt :: !Char -> Int
/**
* Converts a character to uppercase.
*
* @param The character
* @result The same character, with bit 5 cleared
*/
toUpper :: !Char -> Char
/**
* Converts a character to lowercase.
*
* @param The character
* @result The same character, with bit 5 set
*/
toLower :: !Char -> Char
// Tests on Characters:
isUpper :: !Char -> Bool // True if arg1 is an uppercase character
isLower :: !Char -> Bool // True if arg1 is a lowercase character
isAlpha :: !Char -> Bool // True if arg1 is a letter
isAlphanum :: !Char -> Bool // True if arg1 is an alphanumerical character
isDigit :: !Char -> Bool // True if arg1 is a digit
isOctDigit :: !Char -> Bool // True if arg1 is a digit
isHexDigit :: !Char -> Bool // True if arg1 is a digit
isSpace :: !Char -> Bool // True if arg1 is a space, tab etc
isControl :: !Char -> Bool // True if arg1 is a control character
isPrint :: !Char -> Bool // True if arg1 is a printable character
isAscii :: !Char -> Bool // True if arg1 is a 7 bit ASCII character
/**
* Check for uppercase
*
* @param The character
* @result True iff the parameter is from ['A'..'Z']
*/
isUpper :: !Char -> Bool
/**
* Check for lowercase
*
* @param The character
* @result True iff the parameter is from ['a'..'z']
*/
isLower :: !Char -> Bool
/**
* Check for an alphabetic character
*
* @param The character
* @result True iff the parameter is from ['a'..'z'] ++ ['A'..'Z']
*/
isAlpha :: !Char -> Bool
/**
* Check for an alphabetic or numerical character
*
* @param The character
* @result True iff the parameter is from ['a'..'z'] ++ ['A'..'Z'] ++ ['0'..'9']
*/
isAlphanum :: !Char -> Bool
/**
* Check for a numerical character
*
* @param The character
* @result True iff the parameter is from ['0'..'9']
*/
isDigit :: !Char -> Bool
/**
* Check for an octal digit
*
* @param The character
* @result True iff the parameter is from ['0'..'7']
*/
isOctDigit :: !Char -> Bool
/**
* Check for a hexadecimal digit
*
* @param The character
* @result True iff the parameter is from ['0'..'9'] ++ ['a'..'f'] ++ ['A'..'F']
*/
isHexDigit :: !Char -> Bool
/**
* Check for whitespace
*
* @param The character
* @result True iff the parameter is one of ' ', '\t', '\n', '\r', '\f', '\v'
*/
isSpace :: !Char -> Bool
/**
* Check for an ASCII control character
*
* @param The character
* @result True iff the parameter is from ['\x00'..'\x1f'] ++ ['\x7f']
*/
isControl :: !Char -> Bool
/**
* Check for a printable ASCII character
*
* @param The character
* @result True iff the parameter is from [' '..'~']
*/
isPrint :: !Char -> Bool
/**
* Check for a 7-bit ASCII character
*
* @param The character
* @result True iff the integer value of the parameter is less than 128
*/
isAscii :: !Char -> Bool
definition module StdCharList
/**
* Basic functions for manipulating lists of characters.
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen
// ****************************************************************************************
cjustify :: !.Int ![.Char] -> .[Char] // Center [Char] in field with width arg1
ljustify :: !.Int ![.Char] -> .[Char] // Left justify [Char] in field with width arg1
rjustify :: !.Int ![.Char] -> [Char] // Right justify [Char] in field with width arg1
/**
* Center-align a text with spaces, s.t. the right margin is 0 or 1 spaces
* longer than the left margin.
*
* @param The minimum length of the result
* @param The text to center
* @result A list of max(|param 2|, param 1), with param 2 surrounded by spaces
*/
cjustify :: !.Int ![.Char] -> .[Char]
/**
* Left-align a text with spaces
*
* @param The minimum length of the result
* @param The text to align
* @result A list of max(|param 2|, param 1), with spaces appended to param 2
*/
ljustify :: !.Int ![.Char] -> .[Char]
/**
* Right-align a text with spaces
*
* @param The minimum length of the result
* @param The text to align
* @result A list of max(|param 2|, param 1), with spaces prepended to param 2
*/
rjustify :: !.Int ![.Char] -> [Char]
/**
* Concatenate a list of texts, interspersing it with newlines
*
* @param The texts
* @result All texts concatenated, with newlines in between
*/
flatlines :: ![[u:Char]] -> [u:Char]
flatlines :: ![[u:Char]] -> [u:Char] // Concatenate by adding newlines
mklines :: ![Char] -> [[Char]] // Split in lines removing newlines
/**
* Split a text on newlines
*
* @param The text
* @result A list of texts without newlines
*/
mklines :: ![Char] -> [[Char]]
spaces :: !.Int -> .[Char] // Make [Char] containing n space characters
/**
* A list of a number of ' ' characters
*
* @param The number of characters
* @result A list of param 1 spaces
*/
spaces :: !.Int -> .[Char]
definition module StdClass
/**
* Meta-classes with derived functions.
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen
......@@ -12,40 +16,73 @@ from StdBool import not
// For the time-being, macro definitions are used for this purpose
// This may cause misleading error messages in case of type errors
//* Meta-class describing interval types with an absolute zero.
class PlusMin a | + , - , zero a
//* Meta-class describing ratio types.
class MultDiv a | * , / , one a
//* Meta-class describing arithmetical types.
class Arith a | PlusMin , MultDiv , abs , sign , ~ a
//* Meta-class describing types that can be incremented and decremented.
class IncDec a | + , - , one , zero a
where
//* Increment a value by one.
inc :: !a -> a | + , one a
inc x :== x + one
//* Decrement a value by one.
dec :: !a -> a | - , one a
dec x :== x - one
//* Meta-class describing types that can be enumerated.
class Enum a | < , IncDec a
/**
* Equality.
* @var The type for which values can be equated
*/
class Eq a | == a
where
/**
* Inequality.
* @result True iff the parameters are not equal
*/
(<>) infix 4 :: !a !a -> Bool | Eq a
(<>) x y :== not (x == y)
/**
* Ordering.
* @var The type that can be ordered.
*/
class Ord a | < a
where
/**
* Greater than.
* @result True iff the first value is strictly greater than the second value.
*/
(>) infix 4 :: !a !a -> Bool | Ord a
(>) x y :== y < x
/**
* Smaller than or equal to.
* @result True iff the first value is smaller than or equal to the second value.
*/
(<=) infix 4 :: !a !a -> Bool | Ord a
(<=) x y :== not (y<x)
/**
* Greater than or equal to.
* @result True iff the first value is greater than or equal to the second value.
*/
(>=) infix 4 :: !a !a -> Bool | Ord a
(>=) x y :== not (x<y)
//* The minimum of two values.
min::!a !a -> a | Ord a
min x y :== case (x<y) of True = x; _ = y
//* The maximum of two values.
max::!a !a -> a | Ord a
max x y :== case (x<y) of True = y; _ = x
definition module StdDebug
/**
* Functions that write intermediate results to stderr for debugging purposes.
*/
// ********************************************************
// Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen
......@@ -12,16 +16,48 @@ from StdString import instance toString {#Char},instance toString Int
// The following functions should only be used for debugging,
// because these functions have side effects
trace :: !msg .a -> .a | toString msg // write toString msg to stderr
// before evaluating a
special msg={#Char}; msg=Int
trace_n :: !msg .a -> .a | toString msg // write toString msg and newline to stderr
// before evaluating a
special msg={#Char}; msg=Int
trace_t :: !msg -> Bool | toString msg // write toString msg to stderr
// result is True
special msg={#Char}; msg=Int
trace_tn :: !msg -> Bool | toString msg // write toString msg and newline to stderr
// result is True
special msg={#Char}; msg=Int
/**
* Write a message to stderr before returning a value.
*
* @param The message to write to stderr
* @param The value to return
* @result Param 2
*/
trace :: !msg .a -> .a | toString msg special msg={#Char}; msg=Int
/**
* Write a message and a newline to stderr before returning a value.
*
* @param The message to write to stderr
* @param The value to return
* @result Param 2
*/
trace_n :: !msg .a -> .a | toString msg special msg={#Char}; msg=Int
/**
* Write a message to stderr and return True. This is useful in guards, for
* example:
*
* ```
* square x
* | trace_t x = x * x
* ```
*
* @param The message to write to stderr
* @result True
*/
trace_t :: !msg -> Bool | toString msg special msg={#Char}; msg=Int
/**
* Write a message and a newline to stderr and return True. This is useful in
* guards, for example:
*
* ```
* square x
* | trace_tn x = x * x
* ```
*
* @param The message to write to stderr
* @result True
*/
trace_tn :: !msg -> Bool | toString msg special msg={#Char}; msg=Int
definition module StdEnum
/**
* This module must be imported if dotdot expressions are used.
* Then, the following constructs can be used:
*
* - `[from .. ]` -> `{{_from}} from`
* - `[from .. to]` -> `{{_from_to}} from to`
* - `[from, then .. ]` -> `{{_from_then}} from then`
* - `[from, then .. to]` -> `{{_from_then_to}} from then to`
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen
// ****************************************************************************************
/*
This module must be imported if dotdot expressions are used
[from .. ] -> _from from
[from .. to] -> _from_to from to
[from, then .. ] -> _from_then from then
[from, then .. to] -> _from_then_to from then to
*/
import _SystemEnum
definition module StdEnv
/**
* Clean's official Standard Environment library.
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 3.0
// Copyright 2018 Radboud University
......
system module StdFile
/**
* Functions to manipulate the file system with the File type.
*/
// ****************************************************************************************
// Concurrent Clean Standard Library Module Version 3.0
// Copyright 2019 University of Nijmegen
......@@ -7,110 +11,206 @@ system module StdFile
// File modes synonyms
FReadText :== 0 // Read from a text file
FWriteText :== 1 // Write to a text file
FAppendText :== 2 // Append to an existing text file
FReadData :== 3 // Read from a data file
FWriteData :== 4 // Write to a data file
FAppendData :== 5 // Append to an existing data file
//* File mode: read text
FReadText :== 0
//* File mode: write text
FWriteText :== 1
//* File mode: append text
FAppendText :== 2
//* File mode: read data
FReadData :== 3
//* File mode: write data
FWriteData :== 4
//* File mode: append data
FAppendData :== 5
// Seek modes synonyms
FSeekSet :== 0 // New position is the seek offset
FSeekCur :== 1 // New position is the current position plus the seek offset
FSeekEnd :== 2 // New position is the size of the file plus the seek offset
//* Seek mode: the new position is the seek offset
FSeekSet :== 0
:: *Files
//* Seek mode: the new position is the current position plus the seek offset
FSeekCur :== 1
// Acces to the FileSystem (Files)
//* Seek mode: the new position is the size of the file plus the seek offset
FSeekEnd :== 2
/**
* The filesystem environment, independent from *World. This type can only be
* used through the FileSystem and FileEnv classes.
*/
:: *Files
/**
* Access to the filesystem.
*
* @var The unique type that is used to ensure purity.
*/
class FileSystem f where
/**
* Opens a file for the first time in a certain mode.
* @param The filename
* @param The mode (read / write / append; text / data)
* @param The {{`FileSystem`}} (usually {{`World`}})
* @result A boolean indicating success
* @result The {{`File`}}
* @result The new {{`FileSystem`}}
*/
fopen :: !{#Char} !Int !*f -> (!Bool,!*File,!*f)
/* Opens a file for the first time in a certain mode (read, write or append, text or data).
The boolean output parameter reports success or failure. */
/**
* Closes a file.
* @param The {{`File`}}
* @param The {{`FileSystem`}}
* @result A boolean indicating success
* @result The new {{`FileSystem`}}
*/
fclose :: !*File !*f -> (!Bool,!*f)
/* Closes a file */
//* Open the 'Console' for reading and writing.
stdio :: !*f -> (!*File,!*f)
/* Open the 'Console' for reading and writing. */
/**
* With `sfopen` a file can be opened for reading more than once. On a file
* opened by `sfopen` only the operations beginning with `sf` can be used.
* The `sf...` operations work just like the corresponding `f...`
* operations. They can't be used for files opened with {{`fopen`} or
* {{`freopen`}}.
*
* @param The filename
* @param The mode (read; text / data)
* @param The {{`FileSystem`}} (usually {{`World`}})
* @result A boolean indicating success
* @result The new {{`File`}}
* @result The new {{`FileSystem`}}
*/
sfopen :: !{#Char} !Int !*f -> (!Bool,!File,!*f)
/* With sfopen a file can be opened for reading more than once.
On a file opened by sfopen only the operations beginning with sf can be used.
The sf... operations work just like the corresponding f... operations.
They can't be used for files opened with fopen or freopen. */
instance FileSystem Files
instance FileSystem World
/**
* An environment in which files can be dealt with.
*
* @var The unique type that is used to ensure purity.
*/
class FileEnv env where
accFiles :: !.(*Files -> (.x,*Files)) !*env -> (!.x,!*env)
appFiles :: !.(*Files -> *Files) !*env -> *env
instance FileEnv World
// openfiles :: !*World -> (!*Files,!*World) // no longer supported
// closefiles :: !*Files !*World -> *World // no longer supported
/**
* Re-opens an open file in a possibly different mode.
* @param The file
* @param The new mode
* @result A boolean indicating successful closing before reopening
* @result The new file
*/
freopen :: !*File !Int -> (!Bool,!*File) :== code { .d 0 3 f i ; jsr reopenF ; .o 0 3 b f }
/* Re-opens an open file in a possibly different mode.
The boolean indicates whether the file was successfully closed before reopening. */
// Reading from a File:
/**
* Reads a character from a text file or a byte from a datafile.
* @result A boolean indicating success
* @result The read character
*/
freadc :: !*File -> (!Bool,!Char,!*File) :== code { .d 0 2 f ; jsr readFC ; .o 0 4 b c f }
/* Reads a character from a text file or a byte from a datafile.
The boolean indicates succes or failure */
/**
* Reads an Integer from a textfile by skipping spaces, tabs and newlines and
* then reading digits, which may be preceeded by a plus or minus sign.
* From a datafile `freadi` will just read four bytes (a Clean Int).
* @result A boolean indicating success
* @result The read integer
*/
freadi :: !*File -> (!Bool,!Int,!*File) :== code { .d 0 2 f ; jsr readFI ; .o 0 4 b i f }
/* Reads an Integer from a textfile by skipping spaces, tabs and newlines and
then reading digits, which may be preceeded by a plus or minus sign.
From a datafile freadi will just read four bytes (a Clean Int). */
/**
* Reads a Real from a textfile by skipping spaces, tabs and newlines and then
* reading a character representation of a Real number.
* From a datafile `freadr` will just read eight bytes (a Clean Real).
* @result A boolean indicating success
* @result The read real
*/
freadr :: !*File -> (!Bool,!Real,!*File) :== code { .d 0 2 f ; jsr readFR ; .o 0 5 b r f }
/* Reads a Real from a textfile by skipping spaces, tabs and newlines and then
reading a character representation of a Real number.
From a datafile freadr will just read eight bytes (a Clean Real). */
/**
* Reads n characters from a text or data file, which are returned as a String.
* If the file doesn't contain n characters the file will be read to the end
* of the file. An empty String is returned if no characters can be read.
* @param The file
* @param The amount of characters to read
* @result The read string
* @result The file
*/
freads :: ! *File !Int -> (!*{#Char},!*File) :== code { .d 0 3 f i ; jsr readFS ; .o 1 2 f }
/* Reads n characters from a text or data file, which are returned as a String.
If the file doesn't contain n characters the file will be read to the end
of the file. An empty String is returned if no characters can be read. */
/**
* Reads `n` characters from a text or data file, which are returned in the
* string `arg3` at positions `arg1`..`arg1+arg2-1`. If the file doesn't
* contain `arg2` characters the file will be read to the end of the file, and
* the part of the string `arg3` that could not be read will not be changed.
*
* @param The start of the substring to modify
* @param The length of the substring
* @param The string to modify
* @result The number of characters read
* @result The modified string
*/
freadsubstring :: !Int !Int !*{#Char} !*File -> (!Int,!*{#Char},!*File) :== code { .d 1 4 i i f ; jsr readFString ; .o 1 3 i f }
/*
Reads n characters from a text or data file, which are returned in the string
arg3 at positions arg1..arg1+arg2-1. If the file doesn't contain arg2 characters
the file will be read to the end of the file, and the part of the string arg3 that
could not be read will not be changed. The number of characters read, the modified
string and the file are returned.