This is the org.melusina.rashell Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:36:46 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
org.melusina.rashellResilient replicant Shell Programming Library for Common Lisp
Michaël Le Barbier
MIT
alexandria (system).
cl-ppcre (system).
parse-float (system).
sb-posix (system).
src (module).
Modules are listed depth-first from the system components tree.
org.melusina.rashell/srcorg.melusina.rashell (system).
package.lisp (file).
util.lisp (file).
rashell.lisp (file).
posix.lisp (file).
mktemp.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
org.melusina.rashell/org.melusina.rashell.asdorg.melusina.rashell/src/package.lisporg.melusina.rashell/src/util.lisporg.melusina.rashell/src/rashell.lisporg.melusina.rashell/src/posix.lisporg.melusina.rashell/src/mktemp.lisporg.melusina.rashell/org.melusina.rashell.asdorg.melusina.rashell (system).
org.melusina.rashell/src/util.lispsrc (module).
ensure-list (function).
string-match (function).
org.melusina.rashell/src/rashell.lispsrc (module).
*query-output-line-number* (special variable).
arranged-conversation (function).
close-command (generic function).
command (class).
command-error (generic function).
command-error (condition).
command-input (generic function).
command-output (generic function).
command-p (function).
command-status (generic function).
define-command (macro).
define-filter (macro).
define-query (macro).
define-test (macro).
define-utility (macro).
describe-object (method).
do-filter (macro).
do-query (macro).
kill-command (generic function).
make-command (function).
print-object (method).
run-command (generic function).
run-filter (function).
run-query (function).
run-test (function).
run-utility (function).
wait-command (generic function).
*signal-table* (special variable).
command-error-code (reader method).
command-error-command (reader method).
command-error-error (reader method).
command-error-output (reader method).
command-error-status (reader method).
define-command/defun-argv (function).
define-command/prepare-argv (function).
define-command/to-string (function).
do-filter/loop (function).
do-query/loop (function).
org.melusina.rashell/src/posix.lispsrc (module).
awk (function).
cat (function).
command-awk (function).
command-cat (function).
command-cp (function).
command-df (function).
command-du (function).
command-find (function).
command-ln (function).
command-mkdir (function).
command-mv (function).
command-rm (function).
command-sed (function).
cp (function).
df (function).
do-awk (macro).
do-cat (macro).
do-find (macro).
do-sed (macro).
du (function).
find* (function).
free-disk-space (structure).
free-disk-space-blocks (reader).
(setf free-disk-space-blocks) (writer).
free-disk-space-capacity (reader).
(setf free-disk-space-capacity) (writer).
free-disk-space-device (reader).
(setf free-disk-space-device) (writer).
free-disk-space-free (reader).
(setf free-disk-space-free) (writer).
free-disk-space-mounted-on (reader).
(setf free-disk-space-mounted-on) (writer).
free-disk-space-used (reader).
(setf free-disk-space-used) (writer).
ln (function).
mkdir (function).
mv (function).
rm (function).
sed (function).
test (function).
*consumed-disk-space-scanner* (special variable).
*find-predicate-grammar-table* (special variable).
*free-disk-space-scanner* (special variable).
consumed-disk-space-of-string (function).
copy-free-disk-space (function).
do-df (macro).
do-du (macro).
find-predicate-to-argv (function).
free-disk-space-of-string (function).
free-disk-space-p (function).
make-free-disk-space (function).
org.melusina.rashell/src/mktemp.lispsrc (module).
*mktemp-designator* (special variable).
*mktemp-keep* (special variable).
command-make-temporary-directory (function).
command-make-temporary-file (function).
make-temporary-directory (function).
make-temporary-file (function).
with-temporary-directory (macro).
with-temporary-file (macro).
mktemp-template (function).
Packages are listed by definition order.
org.melusina.rashellcommon-lisp.
*mktemp-designator* (special variable).
*mktemp-keep* (special variable).
*query-output-line-number* (special variable).
arranged-conversation (function).
awk (function).
cat (function).
close-command (generic function).
command (class).
command-awk (function).
command-cat (function).
command-cp (function).
command-df (function).
command-du (function).
command-error (generic function).
command-error (condition).
command-find (function).
command-input (generic function).
command-ln (function).
command-make-temporary-directory (function).
command-make-temporary-file (function).
command-mkdir (function).
command-mv (function).
command-output (generic function).
command-p (function).
command-rm (function).
command-sed (function).
command-status (generic function).
cp (function).
define-command (macro).
define-filter (macro).
define-query (macro).
define-test (macro).
define-utility (macro).
df (function).
do-awk (macro).
do-cat (macro).
do-filter (macro).
do-find (macro).
do-query (macro).
do-sed (macro).
du (function).
find* (function).
free-disk-space (structure).
free-disk-space-blocks (reader).
(setf free-disk-space-blocks) (writer).
free-disk-space-capacity (reader).
(setf free-disk-space-capacity) (writer).
free-disk-space-device (reader).
(setf free-disk-space-device) (writer).
free-disk-space-free (reader).
(setf free-disk-space-free) (writer).
free-disk-space-mounted-on (reader).
(setf free-disk-space-mounted-on) (writer).
free-disk-space-used (reader).
(setf free-disk-space-used) (writer).
kill-command (generic function).
ln (function).
make-command (function).
make-temporary-directory (function).
make-temporary-file (function).
mkdir (function).
mv (function).
rm (function).
run-command (generic function).
run-filter (function).
run-query (function).
run-test (function).
run-utility (function).
sed (function).
test (function).
wait-command (generic function).
with-temporary-directory (macro).
with-temporary-file (macro).
*consumed-disk-space-scanner* (special variable).
*find-predicate-grammar-table* (special variable).
*free-disk-space-scanner* (special variable).
*signal-table* (special variable).
command-error-code (generic reader).
command-error-command (generic reader).
command-error-error (generic reader).
command-error-output (generic reader).
command-error-status (generic reader).
consumed-disk-space-of-string (function).
copy-free-disk-space (function).
define-command/defun-argv (function).
define-command/prepare-argv (function).
define-command/to-string (function).
do-df (macro).
do-du (macro).
do-filter/loop (function).
do-query/loop (function).
ensure-list (function).
find-predicate-to-argv (function).
free-disk-space-of-string (function).
free-disk-space-p (function).
make-free-disk-space (function).
mktemp-template (function).
string-match (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
If set, this parameter is a prefix used when generating temporary file templates.
This can be used to distinguish temporary filenames with a prefix mentioning the application that generated them or an issue number.
If set, temporary files and directories are not deleted.
This variable is bound in the main loop of DO-QUERY and exposes the output line number.
Define a function NAME that makes a command according to SPEC.
The function NAME accepts arguments ARGV and optional arguments as specified by the OPTIONS
parameter, see below. The SPEC parameter is a property list specifiying various aspects
of how the command is run.
The OPTIONS parameter is a list of option specifications. An option specification is a list
starting with a symbol, the OPTION-NAME, which is used to label the optional parameter of
the function NAME. The allowed forms for option specifications are:
(OPTION-NAME :flag FLAG-STRING)
The parameter OPTION-NAME is interpreted as a generalised boolean. When it is set, the
FLAG-STRING is added to the command-lin of the external program being run.
(OPTION-NAME :option OPTION-STRING [:to-string CONVERT] [:multiple MULTIPLE-FLAG])
The parameter OPTION-NAME is interpreted as an arbitrary value is a string, or
is converted to a string either by applying the function passed as the :TO-STRING
property, or by using ‘WRITE-TO-STRING’ if none of the preceeding rules apply.
When set, the MULTIPLE-FLAG makes the OPTION-NAME accept a list or a single value.
The elements of this list are converted to strings as described above and each of
the resulting string is added to the command line, preceded by OPTION-STRING.
The SPEC is a property list where the following properties are allowed:
:PROGRAM PATH-TO-PROGRAM
The path to the program run by the function NAME.
:SUBCOMMAND SUBCOMMAND
A SUBCOMMAND is a word or a list of words written after the PATH-TO-PROGRAM
and before other options in the argument vector. Some programs, like ‘git’,
‘svn’, ‘pkg’, ‘port’, ‘docker’ for instance use this calling convention and
some refer to this part of the command line as a subcommand.
:REFERENCE
A reference to be added to the documentation.
:DOCUMENTATION
A documentation string for NAME.
:REST
A form to evalute in order to produce remaining arguments on the command line.
(The arguments are sometimes denoted as “rest arguments.”
:OBJECT-OF-OUTPUT-LINE
When provided, a function to interpret output of the program as an object stream.
The provided function should convert a trimmed output line to the desired value. The
conversion is only used when operating the command as a query.
When this function returns a second value equal to :DROP, the returned value should be
dropped from the stream.
See ‘DO-QUERY’, ‘RUN-QUERY’ and ‘DEFINE-QUERY’.
Define a function NAME that runs filter according to SPEC.
An intermediary function creating the corresponding command (without running it) is also defined. The name of this intermediary function is construced by prefixing COMMAND- to the provided NAME.
Define a function NAME that runs query according to SPEC.
An intermediary function creating the corresponding command (without
running it) is also defined. The name of this intermediary function
is construced by prefixing COMMAND- to the provided NAME.
Define a function NAME that runs test according to SPEC.
An intermediary function creating the corresponding command (without
running it) is also defined. The name of this intermediary function
is construced by prefixing COMMAND- to the provided NAME.
Define a function NAME that runs utility according to SPEC.
An intermediary function creating the corresponding command (without
running it) is also defined. The name of this intermediary function
is constructed by prefixing COMMAND- to the provided NAME.
Run a query process running the given COMMAND and filter INPUT lines.
The VAR is successfully bound to each available line produced by COMMAND, after reading from INPUT stream and BODY is executed for each of these lines.
In the particular case where the COMMAND defines an OBJECT-OF-OUTPUT-LINE,
the VAR is bound to the return value applied to the current line, instead
of the actual line.
The returning form is RESULT.
Run a query process running the given COMMAND and process output lines.
The VAR is successfully bound to each available line produced by COMMAND,
and BODY is executed for each of these lines. In the particular case where
the COMMAND defines an OBJECT-OF-OUTPUT-LINE, the VAR is bound to the return
value applied to the current line, instead of the actual line.
The returning form is RESULT.
Run BODY commands in a context where FILESPEC is bound to the path of a temporary directory.
Run BODY commands in a context where FILESPEC is bound to the path of a temporary file.
Prepare a command providing an arranged in advance conversation according to CLAUSES.
The command evaluates each clause in CLAUSES in sequence. Each of these clauses
can be one of the following forms:
(:SLEEP DURATION-IN-SECONDS)
Put process to sleep for DURATION-IN-SECONDS
(:WRITE-OUTPUT-LINE STRING)
Write STRING on process standard output. The output is not buffered.
(:WRITE-ERROR-LINE STRING)
Write STRING on process standard error. The output is not buffered.
(:READ-INPUT-LINE STRING)
Read a line from process standard input. If the input is different from string,
then an explanatory error message is printed on standard error and the command
terminates with exit code 1.
Bugs:
- The implementation does not validate the clauses.
- The implementation generates a shell script transfered
as an argument to /bin/sh -c which limits the number of clauses
that can constitute an arranged conversation.
- The implementation pass all strings to shell as-is in single quotes, which
is extremly brittle.
The intended use of ARRANGED-CONVERSATION is for testing and debugging.
Run awk(1) with the given AWKSCRIPT on INPUT.
Run cat(1) on PATHNAME-LIST.
Run cp(1) on PATHNAME-LIST and DESTINATION.
Return the available free disk space on the devices for
the given PATHS, or for all devices if the empty list is given. The
free disk space is computed with ‘df -k -P‘ as described in df(1).
Query the consumed disk space for the file hierarchies
rooted at the given PATHNAME.
The output is an alist mapping PATHS to consumed disk space in kilobytes.
Prepare a find(1) command on PATHNAME with the given PREDICATE-EXPR.
The options are
FOLLOW
If set, symbolic links are followed.
DIRECTORY
A pathname to a working doirectory to use when running the command.
Run ln(1) on PATHNAME and DESINATION.
Run mktemp(1).
Run mktemp(1).
Run mkdir(1) on PATHNAME.
Run mv(1) on PATHNAME-LIST and DESINATION.
T if object is a command, NIL otherwise.
Run rm(1) on PATHNAME-LIST.
Run sed(1) with the given SEDSCRIPT on INPUT.
free.
used.
Make a command.
Run a query process running the given COMMAND on INPUT.
When INPUT is a stream, the returned value is a string holding the result
of processing INPUT through the filter.
When INPUT is a pathname, the returned value is a string holding the result
of processing the contents of the file designated by this pathname through
the filter.
When INPUT is or a string, the returned value is a string holding the result
of processing the contents of the string through the filter.
When INPUT is a string list the returned value is a string list.
When INPUT is an array, the returned value is an array of strings.
Run a query process running the given COMMAND and return the list of output lines.
Run COMMAND and return exit status as a generalised boolean.
When the external process running COMMAND exits with a return code of 0, the value T is returned, a code 1 is associated to NIL and other exit status are interpreted as errors. The accumulated standard output and standard error of the command are returned as second and third value.
Run COMMAND as a utility.
Start an external process running COMMAND, without standard input. Return
the accumulated standard output and standard error as multiple values.
When TRIM is set to T, trailing whitespace is removed from the program standard output.
Test the meta-data of file PATHNAME against PREDICATE-EXPRESSION. If the file does not exist, the test evaluates to NIL.
Close the COMMAND.
This closes all streams connected to the process running the COMMAND and also
stops maintaining the status slot.
Returns COMMAND.
TODO:
- Clarify when to use this method – after or before the process exited?
The standard error of the external process running the command or NIL.
The standard input of the external process running the command or NIL.
The standard output of the external process running the command or NIL.
Return a keyword denoting the status of the external process running
the command:
The status can be one of
:PENDING
When the command has not been started, so that no external process
actually runs it.
:RUNNING
When the command has been started and an external process currently runs it.
:STOPPED
When the operating system stopped the process and the process can be restarted.
:EXITED
When the process terminated after exiting. The exit code
of the process is returned as a second value.
:SIGNALED
When the process terminated after receiving a signal. The signal number
that terminated the process is returned as a second value.
Sends the given UNIX SIGNAL to the external process running COMMAND.
The SIGNAL can be either an integer or one of the keyword in ‘*SIGNAL-TABLE*’.
When the PROCESS for command is in :PENDING state, no action is taken
and NIL is returned.
Start a process executing the specified command in an external (UNIX) process.
Parameters INPUT, OUTPUT, and ERROR all behave similarly. They accept one of
the following values:
NIL
When a null stream should be used,
T
The standard input (resp. output, error) from the process runinng the Lisp
is inherited by the created external process.
A-STREAM
The A-STREAM is attached to the standard input (resp. output, error) of
the created external process.
A-PATHNAME-DESIGNATOR
The corresponding file is open and attached to the standard input
(resp. output, error) of the created external process.
:STREAM
A new stream opened for character input or output is created and
attached to the created external process. This stream can
be manipulated by one of the COMMAND-*-STREAM functions.
:OUTPUT
This value is only valid for the :ERROR parameter and directs the
standard error of the created process output to the same destination
as the standard output.
When :INPUT is the name of a file, the IF-INPUT-DOES-NOT-EXIST parameter
defines the behaviour of the start command when it would attach standard
input for the process to a non existing file. This parameter can take
the following values:
NIL (default)
The start command does not create an external process and returns NIL.
:ERROR
The start command does not create an external process and signals
an error condition.
:CREATE
The start command creates an empty file.
When :OUTPUT is the name of a file, the IF-OUTPUT-EXISTS parameter
defines the behaviour of the start command when it would attach standard
output for the process to an already existing file. This parameter can take
the following values:
NIL (default)
The start command does not create an external process and returns NIL.
:ERROR
The start command does not create an external process and signals
an error condition.
:SUPERSEDE
The content of the file will be superseded by the output of the
external process.
:APPEND
The output of the external process will be appended to the content
of the file.
When :ERROR is the name of a file, the IF-ERROR-EXISTS parameter
defines the behaviour of the start command when it would attach standard
error to an existing file. It takes the exact same values as IF-OUTPUT-EXISTS.
STATUS-HOOK is a function the system calls whenever the status of
the process changes. The function takes the command as an argument.
Wait for the external process running COMMAND to quit running. When CHECK-FOR-STOPPED is T, also returns when process is stopped. When the command is still :PENDING it returns immediately. Returns COMMAND.
This condition is signaled when an external process executing a command meets an error condition.
error.
:command
This slot is read-only.
:status
This slot is read-only.
:code
This slot is read-only.
:output
This slot is read-only.
:error
This slot is read-only.
structure-object.
string
number
0
number
0
number
0
float
0.0
string
The COMMAND structure captures the parameters and state of an external program.
The current state of the external program can be examined with the methods
COMMAND-STATUS, COMMAND-INPUT, COMMAND-OUTPUT and COMMAND-ERROR.
A path to the program to run.
#p"/usr/bin/false"
:program
A sequence to be used as the argument vector for the program.
:argv
The working directory of the program to run.
If not provided, the current working directory is used.
common-lisp.
:directory
Environment variable bindings for the program to run.
The ENVIRONMENT must be a sequence whose terms are:
- maybe the keywords :APPEND at the first position,
meaning the environment definitions should be appended to
the environment of the current process.
- maybe the keyword :SUPERSEDE at the first position, meaning
that the environment definitions describe the entire environment
definitions available for the external process.
- either a string of the form "VARIABLE=VALUE";
- or a cons cell of the form (VARIABLE . VALUE).
When the ENVIRONMENT is NIL, then the environment of the calling process is inherited.
:environment
When provided, a function to interpret output of the program as an object stream. The provided function should convert a trimmed output line to the desired value. The conversion is only used when operation the command as a query.
:object-of-output-line
The external process running the program.
The documentation of the command instance.
common-lisp.
:documentation
The PPCRE scanner used to scan consumed space records.
The grammar table for find(1) predicates.
The PPCRE scanner used to scan disk free space records.
The table mapping symbolic signal names to numeric signal names.
Read FREE-DISK-SPACE from the output of DF.
Prepare argument vector interpreation fragment for ARGUMENT interpreted according to SPEC.
Convert ARGUMENT to a string.
Convert PREDICATE-FORM to a sequence of arguments for the find(1) utility.
The PREDICATE-FORM expression is a list matching one of the following examples.
(:PRINT)
(:PRUNE)
(:HAS-KIND FILE-KIND)
(:HAS-SUFFIX SUFFIX)
(:IS-OWNED-BY-USER USER-NAME-OR-USER-ID)
(:IS-OWNED-BY-GROUP GROUP-NAME-OR-GROUP-ID)
(:IS-NEWER-THAN PATH)
(:HAS-EXACT-PERMISSION MODE)
(:HAS-AT-LEAST-PERMISSION MODE)
(:NAME GLOBBING-PATTERN)
(:PATH GLOBBING-PATTERN)
(:AND PREDICATE-FORM*)
(:OR PREDICATE-FORM*)
(:NOT PREDICATE-FORM)
Valid FILE-KIND paramters are
:BLOCK-SPECIAL
:CHARACTER-SPECIAL
:DIRECTORY
:SYMBOLIC-LINK
:FIFO
:REGULAR
:SOCKET
Read FREE-DISK-SPACE from the output of DF.
A template for temporary files in our application.
Predicate recognising TEXT matching a globbing PATTERN.
command-error)) ¶code.
command-error)) ¶command-error)) ¶command-error)) ¶command-error)) ¶| Jump to: | (
A C D E F G K L M P R S T W |
|---|
| Jump to: | (
A C D E F G K L M P R S T W |
|---|
| Jump to: | *
A B C D E F M O P S U |
|---|
| Jump to: | *
A B C D E F M O P S U |
|---|
| Jump to: | C F M O P R S U |
|---|
| Jump to: | C F M O P R S U |
|---|