diff --git a/StdBool.dcl b/StdBool.dcl index b3cb726e9eb747f493340d53b6f02787dc5a904e..cc610f7d9c6619df382aaa90632004afdb4d8bb9 100644 --- a/StdBool.dcl +++ b/StdBool.dcl @@ -1,5 +1,9 @@ system module StdBool +/** + * Class instances and basic functions for the Bool type. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -16,7 +20,30 @@ instance fromBool {#Char} // Additional Logical Operators: -not :: !Bool -> Bool // 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 negation. + * + * @param The boolean to negate + * @result True if the parameter was False; False if True + */ +not :: !Bool -> Bool + +/** + * 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 diff --git a/StdChar.dcl b/StdChar.dcl index 242bda76eff4cfea300798aeb7300287722b58fa..df105ec0b7be138e054f0428414a31df8d631ae6 100644 --- a/StdChar.dcl +++ b/StdChar.dcl @@ -1,5 +1,9 @@ system module StdChar +/** + * Class instances and basic functions for the Char type. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -24,20 +28,116 @@ instance fromChar {#Char} // 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 diff --git a/StdCharList.dcl b/StdCharList.dcl index 977d0270e20e9d7f672e88e8f09d7e83b64d7164..f155bdc97a2e453e5ad5464f1a4d84ceafa19f9a 100644 --- a/StdCharList.dcl +++ b/StdCharList.dcl @@ -1,15 +1,62 @@ 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] diff --git a/StdDebug.dcl b/StdDebug.dcl index 877fdbe72d4712ba3c155eaafb4d3ffc52090782..9829f58990d3a537e0d2e32b650dd96bb9f2fa0e 100644 --- a/StdDebug.dcl +++ b/StdDebug.dcl @@ -1,5 +1,9 @@ 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 diff --git a/StdEnv.dcl b/StdEnv.dcl index b18635127e053a0ca82769d4e28805fe41be0234..81eff79d44481c7ff9943820324968c6ae79a733 100644 --- a/StdEnv.dcl +++ b/StdEnv.dcl @@ -1,5 +1,9 @@ definition module StdEnv +/** + * Clean's official Standard Environment library. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen diff --git a/StdFunc.dcl b/StdFunc.dcl index 354a6516ac20fa962c385391c47a909ae623b2cd..1121895ea01f5ad18f38b7fdc6a2b364fad29c8a 100644 --- a/StdFunc.dcl +++ b/StdFunc.dcl @@ -5,19 +5,83 @@ definition module StdFunc // Copyright 1998 University of Nijmegen // **************************************************************************************** -id :: !.a -> .a // identity function -const :: !.a .b -> .a // constant function +/** + * The identity function. + * + * @param A value + * @result The same value + */ +id :: !.a -> .a -//flip :: !.(.a -> .(.b -> .c)) .b .a -> .c // Flip arguments +/** + * The constant function. + * + * @param A value + * @param Another value + * @result The first value + */ +const :: !.a .b -> .a + +/** + * Flip the arguments of a function. This is useful in function compositions. + * + * @type !.(.a -> .(.b -> .c)) .b .a -> .c + * @param A function + * @param The second argument to the function + * @param The first argument to the function + * @result The function, applied to its arguments + */ flip f a b :== f b a -(o) infixr 9 // :: u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b) // Function composition +/** + * Function composition. + * + * @type u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b) + * @param A function f + * @param A function g + * @result The function f o g, that is, f applied after g + */ +(o) infixr 9 (o) f g :== \ x -> f (g x) -twice :: !(.a -> .a) .a -> .a // f (f x) -while :: !(a -> .Bool) (a -> a) a -> a // while (p x) f (f x) -until :: !(a -> .Bool) (a -> a) a -> a // f (f x) until (p x) -iter :: !Int (.a -> .a) .a -> .a // f (f..(f x)..) +/** + * Apply a function twice. + * + * @param A function f + * @param A value x + * @result f (f x) + */ +twice :: !(.a -> .a) .a -> .a + +/** + * Apply a function as long as a property holds. + * + * @param A property p + * @param A function f + * @param An initial value x + * @result x if not p x, otherwise while p f (f x) + */ +while :: !(a -> .Bool) (a -> a) a -> a + +/** + * Apply a function until a property holds. + * + * @param A property p + * @param A function f + * @param An initial value x + * @result x if p x, otherwise until p f (f x) + */ +until :: !(a -> .Bool) (a -> a) a -> a + +/** + * Apply a function a number of times. + * + * @param The number of iterations n + * @param The function + * @param The initial value + * @result The result of applying the function n times to the initial value + */ +iter :: !Int (.a -> .a) .a -> .a // Some handy functions for transforming unique states: diff --git a/StdInt.dcl b/StdInt.dcl index fa2cb7c09edc7d2566fe45bc60eb2d88a4c005bb..a8ef324e94d0eda1e33308e6b33c5169cc8d7324 100644 --- a/StdInt.dcl +++ b/StdInt.dcl @@ -1,5 +1,9 @@ system module StdInt +/** + * Class instances and basic functions for the Int type. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -48,11 +52,64 @@ instance lcm Int // Least common multiple // Operators on Bits: -(bitor) infixl 6 :: !Int !Int -> Int // Bitwise Or of arg1 and arg2 -(bitand) infixl 6 :: !Int !Int -> Int // Bitwise And of arg1 and arg2 -(bitxor) infixl 6 :: !Int !Int -> Int // Exclusive-Or arg1 with mask arg2 -(<<) infix 7 :: !Int !Int -> Int // Shift arg1 to the left arg2 bit places -(>>) infix 7 :: !Int !Int -> Int // Shift arg1 to the right arg2 bit places -bitnot :: !Int -> Int // One's complement of arg1 - +/** + * Bitwise disjunction. + * + * @param The first integer + * @param The second integer + * @result An integer with exactly those bits set that at least one of the parameters has set + */ +(bitor) infixl 6 :: !Int !Int -> Int + +/** + * Bitwise conjunction. + * + * @param The first integer + * @param The second integer + * @result An integer with exactly those bits set that both of the parameters have set + */ +(bitand) infixl 6 :: !Int !Int -> Int + +/** + * Bitwise exclusive disjunction. + * + * @param The first integer + * @param The second integer + * @result An integer with exactly those bits set that exactly one of the parameters has set + */ +(bitxor) infixl 6 :: !Int !Int -> Int + +/** + * Shift an integer to the left. + * + * @param The integer to shift + * @param The number of places to shift + * @result The result of the bitshift + */ +(<<) infix 7 :: !Int !Int -> Int + +/** + * Shift an integer to the right. + * + * @param The integer to shift + * @param The number of places to shift + * @result The result of the bitshift + */ +(>>) infix 7 :: !Int !Int -> Int + +/** + * Bitwise logical negation. + * + * @param An integer + * @param The one's complement of the parameter + */ +bitnot :: !Int -> Int + +/** + * Compile-time macro to check for the integer length of the system. + * + * @param The value if the platform is 64-bit + * @param The value if the platform is 32-bit + * @result Either of the parameters, depending on the platform + */ IF_INT_64_OR_32 int64 int32 :== int32; diff --git a/StdMisc.dcl b/StdMisc.dcl index eb0d943d938f121d9e44ec8f54516fe7347a6d5e..492cfe0c7b6b651c70bb9e283ea59fb110c9a3f1 100644 --- a/StdMisc.dcl +++ b/StdMisc.dcl @@ -1,9 +1,25 @@ system module StdMisc +/** + * Miscellaneous functions. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen // **************************************************************************************** -abort :: !{#Char} -> .a // stop reduction and print argument -undef :: .a // fatal error, stop reduction. +/** + * Print a message and abort the program. + * + * @param The message to print + * @result There is no result; the program will terminate + */ +abort :: !{#Char} -> .a + +/** + * The undefined value. + * + * @result An attempt to evaluate the result will yield a runtime error. + */ +undef :: .a diff --git a/StdReal.dcl b/StdReal.dcl index 640a1451696452270d631fa6b222d6f51f888f32..02409bf6449a1b7cd4a58f6a3e675152a8dbbf6a 100644 --- a/StdReal.dcl +++ b/StdReal.dcl @@ -1,5 +1,9 @@ system module StdReal +/** + * Class instances and basic functions for the Real type. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -56,4 +60,10 @@ instance atanh Real // Arc Hyperbolic Tangent, partial function, only defined i // Additional conversion: -entier :: !Real -> Int // Convert Real into Int by taking entier +/** + * Imprecise conversion from Real to Int. + * + * @param A Real + * @result The largest integer smaller than the parameter + */ +entier :: !Real -> Int diff --git a/StdString.dcl b/StdString.dcl index 7a3821df52843e16e77b87a2da4911ec73ecd78d..95de472a0edcb397ed68c2406a42816add467a03 100644 --- a/StdString.dcl +++ b/StdString.dcl @@ -1,5 +1,9 @@ system module StdString +/** + * Class instances and basic functions for the String type. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -26,6 +30,21 @@ instance % {#Char} instance +++ {#Char} // string concatenation -(+++.) infixr 5 :: !{#Char} !{#Char} -> .{#Char} // string concatenation with unique result - -(:=) infixl 9 :: !{#Char} !(!Int,!Char) -> {#Char} // update i-th element with char +/** + * Concatenate two strings with a unique result. This is similar to +++, except + * that the result type is unique. + * + * @param A string + * @param A string + * @result The concatenation of the two strings + */ +(+++.) infixr 5 :: !{#Char} !{#Char} -> .{#Char} + +/** + * Update a character in a string. + * + * @param The string + * @param A tuple of the index and the new character + * @result The new string, with the new character on the specified position + */ +(:=) infixl 9 :: !{#Char} !(!Int,!Char) -> {#Char} diff --git a/StdTuple.dcl b/StdTuple.dcl index d92bbb9c0ccb178b9842d7b7ea4dee6eb62f7231..1e87608f69ec91d101b07ffed7a078c20f4baef3 100644 --- a/StdTuple.dcl +++ b/StdTuple.dcl @@ -1,5 +1,9 @@ definition module StdTuple +/** + * Class instances and basic functions for tuples. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -7,16 +11,49 @@ definition module StdTuple import StdClass -// fst :: !(!.a,.b) -> .a // t1 of (t1,t2) +/** + * The first element of a two-tuple. + * + * @type :: !(!.a,.b) -> .a + * @param The tuple + * @result The first element + */ fst tuple :== t1 where (t1, _) = tuple -// snd :: !(.a,!.b) -> .b // t2 of (t1,t2) + +/** + * The second element of a two-tuple. + * + * @type :: !(.a,!.b) -> .b + * @param The tuple + * @result The second element + */ snd tuple :== t2 where (_, t2) = tuple -// fst3 :: !(!.a,.b,.c) -> .a // t1 of (t1,t2,t3) +/** + * The first element of a three-tuple. + * + * @type :: !(!.a,.b,.c) -> .a + * @param The tuple + * @result The first element + */ fst3 tuple :== t1 where (t1, _, _) = tuple -// snd3 :: !(.a,!.b,.c) -> .b // t2 of (t1,t2,t3) + +/** + * The second element of a three-tuple. + * + * @type :: !(.a,!.b,.c) -> .b + * @param The tuple + * @result The second element + */ snd3 tuple :== t2 where (_, t2, _) = tuple -// thd3 :: !(.a,.b,!.c) -> .c // t3 of (t1,t2,t3) + +/** + * The third element of a three-tuple. + * + * @type :: !(.a,.b,!.c) -> .c + * @param The tuple + * @result The third element + */ thd3 tuple :== t3 where (_, _, t3) = tuple instance == (a,b) | Eq a & Eq b @@ -25,9 +62,39 @@ instance == (a,b,c) | Eq a & Eq b & Eq c instance < (a,b) | Ord a & Ord b instance < (a,b,c) | Ord a & Ord b & Ord c -app2 :: !(.(.a -> .b),.(.c -> .d)) !(.a,.c) -> (.b,.d) // app2 (f,g) (a,b) = (f a,g b) +/** + * Apply functions to both elements of a two-tuple. + * + * @param A tuple of functions (f,g) + * @param A tuple of values (x,y) + * @result The tuple of the result of the applications (f x,g y) + */ +app2 :: !(.(.a -> .b),.(.c -> .d)) !(.a,.c) -> (.b,.d) + +/** + * Apply functions to all elements of a three-tuple. + * + * @param A tuple of functions (f,g,h) + * @param A tuple of values (x,y,z) + * @result The tuple of the result of the applications (f x,g y,h z) + */ app3 :: !(.(.a -> .b),.(.c -> .d),.(.e -> .f)) !(.a,.c,.e) -> (.b,.d,.f) - // app3 (f,g,h) (a,b,c) = (f a,g b,h c) -curry :: !.((.a,.b) -> .c) .a .b -> .c // curry f a b = f (a,b) -uncurry :: !.(.a -> .(.b -> .c)) !(.a,.b) -> .c // uncurry f (a,b) = f a b +/** + * Apply a function that takes a two-tuple to two separate values. + * + * @param A function f + * @param The first element of the parameter tuple x + * @param The second element of the parameter tuple y + * @result f applied to (x,y) + */ +curry :: !.((.a,.b) -> .c) .a .b -> .c + +/** + * Apply a function for two separate values to a two-tuple. + * + * @param A function f + * @param A tuple of parameters (x,y) + * @result The application f x y. + */ +uncurry :: !.(.a -> .(.b -> .c)) !(.a,.b) -> .c diff --git a/_SystemEnum.dcl b/_SystemEnum.dcl index a186e80acb2c4c12cec52e6c55623bc702a28095..2c110391149b11fbf27b2f1be1220e597815ccfd 100644 --- a/_SystemEnum.dcl +++ b/_SystemEnum.dcl @@ -1,5 +1,9 @@ definition module _SystemEnum +/** + * The underlying functions for dotdot expressions. + */ + // **************************************************************************************** // Concurrent Clean Standard Library Module Version 2.0 // Copyright 1998 University of Nijmegen @@ -18,7 +22,43 @@ from StdClass import class Enum (..), class IncDec (..), class Ord (..),<=,inc,d from StdBool import not import StdInt,StdChar +/** + * Generate a list of all values from a starting point. + * Instead of `_from x`, you can use `[x..]`. + * + * @param The starting point + * @result [x, x + one, x + one + one, x + one + one + one, ...] + */ _from :: a -> .[a] | IncDec , Ord a special a=Int; a=Char + +/** + * Generate a list of all values from a starting point to an endpoint. + * Instead of `_from_to x y`, you can use `[x..y]`. + * + * @param The starting point + * @param The endpoint + * @result [x, inc x, inc (inc x), inc (inc (inc x)), ..., E] where E <= y + */ _from_to :: !a !a -> .[a] | Enum a special a=Int; a=Char + +/** + * Generate a list of all values from a starting point with a certain interval. + * Instead of `_from_then x y`, you can use `[x,y..]`. + * + * @param The starting point + * @param The next point + * @result [x, y, x + (y - x) + (y - x), ...] + */ _from_then :: a a -> .[a] | Enum a special a=Int; a=Char + +/** + * Generate a list of all values from a starting point to an endpoint with a + * certain interval. + * Instead of `_from_then_to x y z`, you can use `[x,y..z]`. + * + * @param The starting point + * @param The next point + * @param The endpoint + * @result [x, y, x + (y - x) + (y - x), ..., E] where E <= z + */ _from_then_to :: !a !a !a -> .[a] | Enum a special a=Int; a=Char