chickadee » extras

Outdated CHICKEN release

This is a manual page for an old and unsupported version of CHICKEN. If you are still using it, please consider migrating to the latest version. You can find the manual for the latest release here.

Unit extras

This unit contains a collection of useful utility definitions. The unit is used in csi by default.

Random numbers


randomize #!optional SEEDprocedure

Set random-number seed. If SEED (an exact integer) is not supplied, the current time is used. On startup (when Unit extras is initialized), the random number generator is initialized with the current time.


random Nprocedure

Returns a pseudo-random integer in [0, N-1]. N is an integer.

On Windows, N and the random value are exact integer.

Warning: This procedure uses rand(3) internally and exhibits its deficiencies, including low quality pseudo-randomness:

  • On Windows and Solaris, only 32768 unique random values can be generated in the range [0, N-1]. If N >= 32768, there will be gaps in the result set.
  • On Mac OS X, Windows and some other platforms, little variance in output is seen with nearby seeds. Since the random generator is seeded with current-seconds at startup, new processes may see similar or identical random sequences for up to a minute.
  • On Linux, rand(3) is an alias to random(3), which provides output of reasonable quality.

Formatted output




fprintf PORT FORMATSTRING #!optional ARG...procedure
printf FORMATSTRING #!optional ARG...procedure
sprintf FORMATSTRING #!optional ARG...procedure

Simple formatted output to a given port (fprintf), the value of (current-output-port) (printf), or a string (sprintf). The FORMATSTRING can contain any sequence of characters. There must be at least as many ARG arguments given as there are format directives that require an argument in FORMATSTRING. Extra ARG arguments are ignored. The character `~' prefixes special formatting directives:

~% write newline character
~N the same as ~%
~S write the next argument
~A display the next argument
~\n skip all whitespace in the format-string until the next non-whitespace character
~B write the next argument as a binary number
~O write the next argument as an octal number
~X write the next argument as a hexadecimal number
~C write the next argument as a character
~~ display `~'
~! flush all pending output
~? invoke formatted output routine recursively with the next two arguments as format-string and list of parameters


(format [DESTINATION] FORMATSTRING [ARG...])procedure

The parameters FORMATSTRING and ARG... are as for printf.

The optional DESTINATION, when supplied, performs:




pretty-print EXP #!optional PORTprocedure
pp EXP #!optional PORTprocedure

Print expression nicely formatted. PORT defaults to the value of (current-output-port).



Specifies the maximal line-width for pretty printing, after which line wrap will occur.

Input/Output extensions



read-byte #!optional PORTprocedure
write-byte BYTE #!optional PORTprocedure

Read/write a byte to the port given in PORT, which default to the values of (current-input-port) and (current-output-port), respectively.


read-file #!optional FILE-OR-PORT READER MAXCOUNTprocedure

Returns a list containing all toplevel expressions read from the file or port FILE-OR-PORT. If no argument is given, input is read from the port that is the current value of (current-input-port). After all expressions are read, and if the argument is a port, then the port will not be closed. The READER argument specifies the procedure used to read expressions from the given file or port and defaults to read. The reader procedure will be called with a single argument (an input port). If MAXCOUNT is given then only up to MAXCOUNT expressions will be read in.



read-line #!optional PORT LIMITprocedure
write-line STRING #!optional PORTprocedure

Line-input and -output. PORT defaults to the value of (current-input-port) and (current-output-port), respectively. If the optional argument LIMIT is given and not #f, then read-line reads at most LIMIT characters per line. read-line returns a string without the terminating newline and write-line adds a terminating newline before outputting.


read-lines #!optional PORT MAXprocedure

Read MAX or fewer lines from PORT. PORT defaults to the value of (current-input-port). PORT may optionally be a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).




read-string #!optional NUM PORTprocedure
read-string! NUM STRING #!optional PORT STARTprocedure
write-string STRING #!optional NUM PORTprocedure

Read or write NUM characters from/to PORT, which defaults to the value of (current-input-port) or (current-output-port), respectively. If NUM is #f or not given, then all data up to the end-of-file is read, or, in the case of write-string the whole string is written. If no more input is available, read-string returns the empty string. read-string! reads destructively into the given STRING argument, but never more characters than would fit into STRING. If START is given, then the read characters are stored starting at that position. read-string! returns the actual number of characters read.


read-token PREDICATE #!optional PORTprocedure

Reads characters from PORT (which defaults to the value of (current-input-port)) and calls the procedure PREDICATE with each character until PREDICATE returns false. Returns a string with the accumulated characters.

Previous: Unit files

Next: Unit irregex

Contents »