source: project/wiki/eggref/5/shell @ 36666

Last change on this file since 36666 was 36666, checked in by felix winkelmann, 21 months ago

Added documentation for C5 shell egg

File size: 2.2 KB
Line 
1[[tags:eggs]]
2[[toc:]]
3
4== shell
5
6=== Introduction
7
8Invoke shell commands
9
10=== run
11
12<syntax>(run COMMAND ...)</syntax>
13
14Invokes each {{COMMAND}} as a shell command. {{COMMAND}} may be of any
15data type and is flattened and converted to a string.  {{COMMAND}} is
16also implicitly quasiquoted so subexpressions may be computed at
17run-time by unquoting them. Returns an unspecified value.
18
19Note that expressions and subforms are not automatically escaped, so
20
21  (run (ls a "b c"))
22
23will pass 3 arguments to the {{ls}} command.
24
25=== run*
26
27<syntax>(run* COMMAND ...)</syntax>
28
29Similar to {{run}} but returns the return status of each command
30as multiple result values.
31
32=== capture
33
34<syntax>(capture COMMAND ...)</syntax>
35
36Similar to {{run}} but captures everything written by the subprocess
37to stdout and returns the output as a string. In case the command fails,
38an empty string is returned (there is currently no way to distinguish
39between a failed command and one that produces no output).
40
41=== shell
42
43<syntax>(shell COMMAND ...)</syntax>
44
45Returns a procedure that, when invoked will run the given shell
46commands. The procedure accepts the same keyword arguments as
47{{execute}}. Note that unquoted subexpressions in the command-list are
48evaluated when the procedure is invoked, not when it is created.
49
50=== execute
51
52<procedure>(execute COMMANDLIST #!key status verbose)</procedure>
53
54Converts {{COMMANDLIST}} to a string by flattening the list-structure
55of each command and interspersing it with whitespace ({{" "}}) and
56invokes it as a shell command. If {{status}} is given and true, then
57{{execute}} returns the exit status, with one result value for each
58element in {{COMMANDLIST}}. If {{verbose}} is given and true, it
59overrides the current setting of {{shell-verbose}}.
60
61This is the underlying primitive used by {{run[*]}} and {{shell}}.
62
63=== shell-verbose
64
65<parameter>shell-verbose</parameter>
66
67When true, shell commands invoked via {{run}}, {{run*}} and {{shell}}
68are displayed on the port given by {{(current-output-port)}}.
69
70=== Authors
71
72Felix Winkelmann
73
74=== License
75
76  This code is in the public domain
77
78=== Version History
79
80; 0.4 : ported to CHICKEN 5
81; 0.3 : added {{capture}}
82; 0.1 : initial version
83
Note: See TracBrowser for help on using the repository browser.