source: project/chicken/trunk/manual/Unit utils @ 15262

Last change on this file since 15262 was 15262, checked in by felix winkelmann, 11 years ago

bumped version to 4.1.1; improvements and corrections for compile-file

File size: 3.7 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Unit utils
6
7This unit contains a "grab bag" of procedures without a good home, and which
8don't have to be available by default (as compared to the [[Unit
9extras|extras]] unit).
10
11This unit uses the {{extras}} and {{srfi-13}} units.
12
13
14=== Executing shell commands with formatstring and error checking
15
16==== system*
17
18 [procedure] (system* FORMATSTRING ARGUMENT1 ...)
19
20Similar to {{(system (sprintf FORMATSTRING ARGUMENT1 ...))}},
21but signals an error if the invoked program should return a nonzero
22exit status.
23
24=== Iterating over input lines and files
25
26==== for-each-line
27
28 [procedure] (for-each-line PROCEDURE [PORT])
29
30Calls {{PROCEDURE}} for each line read from {{PORT}} (which defaults to the
31value of {{(current-input-port)}}. The argument passed to {{PROCEDURE}}
32is a string with the contents of the line, excluding any line-terminators.
33When all input has been read from the port, {{for-each-line}} returns some unspecified value.
34
35==== for-each-argv-line
36
37 [procedure] (for-each-argv-line PROCEDURE)
38
39Opens each file listed on the command line in order, passing one line
40at a time into {{PROCEDURE}}.  The filename {{-}} is interpreted as
41{{(current-input-port)}}.  If no arguments are given on the command line
42it again uses the value of {{(current-input-port)}}. During execution of
43{{PROCEDURE}}, the current input port will be correctly bound to
44the current input source.
45
46This code will act as a simple Unix cat(1) command:
47
48<enscript highlight=scheme>
49(for-each-argv-line print)
50</enscript>
51
52
53=== Reading a file's contents
54
55==== read-all
56
57 [procedure] (read-all [FILE-OR-PORT])
58
59If {{FILE-OR-PORT}} is a string, then this procedure returns the contents of the file
60as a string. If {{FILE-OR-PORT}} is a port, all remaining input is read and returned as
61a string. The port is not closed. If no argument is provided, input will be read from the
62port that is the current value of {{(current-input-port)}}.
63
64
65=== Shell argument quoting
66
67==== qs
68
69 [procedure] (qs STRING [PLATFORM])
70
71Escapes {{STRING}} suitably for passing to a shell command on {{PLATFORM}}.
72{{PLATFORM}} defaults to the value of {{(build-platform)}} and indicates in
73which style the argument should be quoted. On Windows systems, the string
74is simply enclosed in double-quote ({{"}}) characters, on UNIXish systems,
75characters that would have a special meaning to the shell are escaped
76using backslash ({{\}}).
77
78
79=== Dynamic compilation
80
81==== compile-file
82
83 [procedure] (compile-file FILENAME #!key options output-file)
84
85Compiles the Scheme source file {{FILENAME}} into a dynamically
86loadable library by invoking the {{csc}} compiler driver. If the
87library can be successfully created, it is loaded into the current
88Scheme process. {{options}} may be a list of strings which are passed
89as additional command line options to {{csc}}. If {{output-file}} is
90not given, then the compiled file is stored in a temporary location
91and will be deleted when the process exits successfully.
92When compilation and loading succeeds, the name of the compiled file
93is returned.
94
95Notes:
96
97* loading the same compiled file multiple times is only supported on Linux
98  in the moment and should be considered unreliable. For this reason, a new temporary
99  file is created for every invocation of {{compile-file}}, unless an explicit
100  output file name is given.
101
102* this procedure is compatible to the {{scheme-compile-file}} command in {{emacs}}' {{scheme-mode}}.
103
104==== compile-file-options
105
106 [parameter] compile-file-options
107
108A parameter that holds a list of default options that should be given
109to {{csc}} after invocation of the {{compile-file}} procedure.
110The initial default options are {{-scrutinize -O2 -d2}}.
111
112
113---
114Previous: [[Unit posix]]
115
116Next: [[Unit tcp]]
Note: See TracBrowser for help on using the repository browser.