The trivial-shell Reference Manual

This is the trivial-shell Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 18:08:51 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 trivial-shell

OS and Implementation independent access to the shell

Maintainer

Gary Warren King <>

Author

Gary Warren King <>

License

MIT Style License

Version

0.2.0

Source

trivial-shell.asd.

Child Components

3 Modules

Modules are listed depth-first from the system components tree.


3.1 trivial-shell/notes

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

Child Component

notes.text (file).


3.2 trivial-shell/timeout

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

Child Components

3.3 trivial-shell/setup

Dependency

timeout (module).

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

Child Component

package.lisp (file).


3.4 trivial-shell/dev

Dependency

setup (module).

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

Child Components

3.5 trivial-shell/port

Dependency

dev (module).

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

Child Component

sbcl.lisp (file).


3.6 trivial-shell/website

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

Child Component

source (module).


3.7 trivial-shell/website/source

Source

trivial-shell.asd.

Parent Component

website (module).

Child Component

index.md (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 trivial-shell/trivial-shell.asd

Source

trivial-shell.asd.

Parent Component

trivial-shell (system).

ASDF Systems

trivial-shell.


4.1.2 trivial-shell/timeout/package.lisp

Source

trivial-shell.asd.

Parent Component

timeout (module).

Packages

com.metabang.trivial-timeout.


4.1.3 trivial-shell/timeout/with-timeout.lisp

Dependency

package.lisp (file).

Source

trivial-shell.asd.

Parent Component

timeout (module).

Public Interface
Internals

4.1.4 trivial-shell/setup/package.lisp

Source

trivial-shell.asd.

Parent Component

setup (module).

Packages

trivial-shell.


4.1.5 trivial-shell/dev/definitions.lisp

Source

trivial-shell.asd.

Parent Component

dev (module).

Public Interface

4.1.6 trivial-shell/dev/macros.lisp

Source

trivial-shell.asd.

Parent Component

dev (module).

Internals

4.1.7 trivial-shell/dev/utilities.lisp

Source

trivial-shell.asd.

Parent Component

dev (module).

Internals

4.1.8 trivial-shell/dev/shell.lisp

Dependencies
Source

trivial-shell.asd.

Parent Component

dev (module).

Public Interface
Internals

4.1.9 trivial-shell/port/sbcl.lisp

Source

trivial-shell.asd.

Parent Component

port (module).

Internals

4.2 Static


4.2.1 trivial-shell/notes/notes.text

Source

trivial-shell.asd.

Parent Component

notes (module).


4.2.2 trivial-shell/website/source/index.md

Source

trivial-shell.asd.

Parent Component

source (module).


5 Packages

Packages are listed by definition order.


5.1 trivial-shell

Source

package.lisp.

Nicknames
  • com.metabang.trivial-shell
  • metashell
Use List
Public Interface
Internals

5.2 com.metabang.trivial-timeout

Source

package.lisp.

Nickname

trivial-timeout

Use List

common-lisp.

Used By List

trivial-shell.

Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Special variables

Special Variable: *bourne-compatible-shell*

The path to a Bourne compatible command shell in physical pathname notation.

Package

trivial-shell.

Source

definitions.lisp.

Special Variable: *shell-search-paths*
Package

trivial-shell.

Source

definitions.lisp.


6.1.2 Macros

Macro: with-timeout ((seconds) &body body)

Execute ‘body‘ for no more than ‘seconds‘ time.

If ‘seconds‘ is exceeded, then a [timeout-error][] will be signaled.

If ‘seconds‘ is nil, then the body will be run normally until it completes or is interrupted.

Package

com.metabang.trivial-timeout.

Source

with-timeout.lisp.


6.1.3 Ordinary functions

Function: exit (&optional code)

Exit the process. CODE is either a numeric exit code, or the special values :SUCCESS or :FAILURE, which maps to the appropriate exit codes for the operating system.

Package

trivial-shell.

Source

shell.lisp.

Function: get-env-var (name)

Return the value of the environment variable ‘name‘.

Package

trivial-shell.

Source

shell.lisp.


6.1.4 Generic functions

Generic Function: shell-command (command &key input)
Package

trivial-shell.

Methods
Method: shell-command (command &key input)

Synchronously execute ‘command‘ using a Bourne-compatible shell, returns (values output error-output exit-status).

The ‘command‘ can be a full path to a shell executable binary
or just its name. In the later case, the variable ‘*shell-search-paths*‘ will be used to find the executable.

Depending on the implementation, the variable ‘*bourne-compatible-shell*‘ may be used to find a shell to use in executing ‘command‘.

Source

shell.lisp.

Method: shell-command ((command pathname) &key input)
Source

shell.lisp.


6.1.5 Conditions

Condition: timeout-error

An error signaled when the duration specified in the [with-timeout][] is exceeded.

Package

com.metabang.trivial-timeout.

Source

with-timeout.lisp.

Direct superclasses

error.


6.2 Internals


6.2.1 Special variables

Special Variable: *os-alist*
Package

trivial-shell.

Source

utilities.lisp.


6.2.2 Macros

Macro: with-gensyms (syms &body body)
Package

trivial-shell.

Source

macros.lisp.

Macro: with-input ((var source &rest args) &body body)

Create an input stream from source and bind it to var within the body of the with-input form. The stream will be closed if necessary on exit.

Package

trivial-shell.

Source

macros.lisp.

Macro: with-output ((var destination &rest args) &body body)

Create an output stream from source and bind it to var within the body of the with-output form. The stream will be closed if necessary on exit.

Package

trivial-shell.

Source

macros.lisp.

Macro: with-stream-from-specifier ((stream stream-specifier direction &rest args) &body body)
Package

trivial-shell.

Source

macros.lisp.


6.2.3 Ordinary functions

Function: %exit (code)
Package

trivial-shell.

Source

sbcl.lisp.

Function: %get-env-var (name)
Package

trivial-shell.

Source

sbcl.lisp.

Function: %os-process-id ()
Package

trivial-shell.

Source

sbcl.lisp.

Function: %shell-command (command input)
Package

trivial-shell.

Source

sbcl.lisp.

Function: %shell-command-using-temporary-file (command input)
Package

trivial-shell.

Source

sbcl.lisp.

Function: build-with-timeout (seconds body)
Package

com.metabang.trivial-timeout.

Source

with-timeout.lisp.

Function: create-shell-process (command wait)
Package

trivial-shell.

Source

sbcl.lisp.

Function: directory-pathname-p (pathname)

Does ‘pathname‘ syntactically represent a directory?

A directory-pathname is a pathname _without_ a filename. The three ways that the filename components can be missing are for it to be ‘nil‘, ‘:unspecific‘ or the empty string.

Package

trivial-shell.

Source

utilities.lisp.

Function: find-command-ending-in-string (command)
Package

trivial-shell.

Source

shell.lisp.

Function: generate-platform-specific-code (seconds-symbol doit-symbol)
Package

com.metabang.trivial-timeout.

Source

with-timeout.lisp.

Function: host-os ()
Package

trivial-shell.

Source

utilities.lisp.

Function: open-temporary-file ()
Package

trivial-shell.

Source

sbcl.lisp.

Function: os-process-id ()

Return the process-id of the currently executing OS process.

Package

trivial-shell.

Source

shell.lisp.

Function: process-alive-p (process)
Package

trivial-shell.

Source

sbcl.lisp.

Function: process-exit-code (process)
Package

trivial-shell.

Source

sbcl.lisp.

Function: read-temporary-file (file-stream)
Package

trivial-shell.

Source

sbcl.lisp.

Function: symbol-if-external (name package)
Package

trivial-shell.

Source

sbcl.lisp.


6.2.4 Generic functions

Generic Function: close-stream-specifier (steam)

Close a stream and handle other bookkeeping as appropriate.

Package

trivial-shell.

Source

macros.lisp.

Methods
Method: close-stream-specifier ((s string-stream))
Method: close-stream-specifier (s)
Generic Function: file-to-string-as-lines (pathname)
Package

trivial-shell.

Source

shell.lisp.

Methods
Method: file-to-string-as-lines ((stream stream))
Method: file-to-string-as-lines ((pathname pathname))
Generic Function: make-stream-from-specifier (specifier direction &rest args)

Create and return a stream from specifier, direction and any other argsuments

Package

trivial-shell.

Source

macros.lisp.

Methods
Method: make-stream-from-specifier ((stream-specifier string) (direction (eql :output)) &rest args)
Method: make-stream-from-specifier ((stream-specifier string) (direction symbol) &rest args)
Method: make-stream-from-specifier ((stream-specifier pathname) (direction symbol) &rest args)
Method: make-stream-from-specifier ((stream-specifier (eql :none)) (direction symbol) &rest args)
Method: make-stream-from-specifier ((stream-specifier (eql nil)) (direction symbol) &rest args)
Method: make-stream-from-specifier ((stream-specifier (eql t)) (direction symbol) &rest args)
Method: make-stream-from-specifier ((stream-specifier stream) (direction symbol) &rest args)

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %  
B   C   D   E   F   G   H   M   O   P   R   S   W  
Index Entry  Section

%
%exit: Private ordinary functions
%get-env-var: Private ordinary functions
%os-process-id: Private ordinary functions
%shell-command: Private ordinary functions
%shell-command-using-temporary-file: Private ordinary functions

B
build-with-timeout: Private ordinary functions

C
close-stream-specifier: Private generic functions
close-stream-specifier: Private generic functions
close-stream-specifier: Private generic functions
create-shell-process: Private ordinary functions

D
directory-pathname-p: Private ordinary functions

E
exit: Public ordinary functions

F
file-to-string-as-lines: Private generic functions
file-to-string-as-lines: Private generic functions
file-to-string-as-lines: Private generic functions
find-command-ending-in-string: Private ordinary functions
Function, %exit: Private ordinary functions
Function, %get-env-var: Private ordinary functions
Function, %os-process-id: Private ordinary functions
Function, %shell-command: Private ordinary functions
Function, %shell-command-using-temporary-file: Private ordinary functions
Function, build-with-timeout: Private ordinary functions
Function, create-shell-process: Private ordinary functions
Function, directory-pathname-p: Private ordinary functions
Function, exit: Public ordinary functions
Function, find-command-ending-in-string: Private ordinary functions
Function, generate-platform-specific-code: Private ordinary functions
Function, get-env-var: Public ordinary functions
Function, host-os: Private ordinary functions
Function, open-temporary-file: Private ordinary functions
Function, os-process-id: Private ordinary functions
Function, process-alive-p: Private ordinary functions
Function, process-exit-code: Private ordinary functions
Function, read-temporary-file: Private ordinary functions
Function, symbol-if-external: Private ordinary functions

G
generate-platform-specific-code: Private ordinary functions
Generic Function, close-stream-specifier: Private generic functions
Generic Function, file-to-string-as-lines: Private generic functions
Generic Function, make-stream-from-specifier: Private generic functions
Generic Function, shell-command: Public generic functions
get-env-var: Public ordinary functions

H
host-os: Private ordinary functions

M
Macro, with-gensyms: Private macros
Macro, with-input: Private macros
Macro, with-output: Private macros
Macro, with-stream-from-specifier: Private macros
Macro, with-timeout: Public macros
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
make-stream-from-specifier: Private generic functions
Method, close-stream-specifier: Private generic functions
Method, close-stream-specifier: Private generic functions
Method, file-to-string-as-lines: Private generic functions
Method, file-to-string-as-lines: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, make-stream-from-specifier: Private generic functions
Method, shell-command: Public generic functions
Method, shell-command: Public generic functions

O
open-temporary-file: Private ordinary functions
os-process-id: Private ordinary functions

P
process-alive-p: Private ordinary functions
process-exit-code: Private ordinary functions

R
read-temporary-file: Private ordinary functions

S
shell-command: Public generic functions
shell-command: Public generic functions
shell-command: Public generic functions
symbol-if-external: Private ordinary functions

W
with-gensyms: Private macros
with-input: Private macros
with-output: Private macros
with-stream-from-specifier: Private macros
with-timeout: Public macros


A.4 Data types

Jump to:   C   D   F   I   M   N   P   S   T   U   W  
Index Entry  Section

C
com.metabang.trivial-timeout: The com․metabang․trivial-timeout package
Condition, timeout-error: Public conditions

D
definitions.lisp: The trivial-shell/dev/definitions․lisp file
dev: The trivial-shell/dev module

F
File, definitions.lisp: The trivial-shell/dev/definitions․lisp file
File, index.md: The trivial-shell/website/source/index․md file
File, macros.lisp: The trivial-shell/dev/macros․lisp file
File, notes.text: The trivial-shell/notes/notes․text file
File, package.lisp: The trivial-shell/timeout/package․lisp file
File, package.lisp: The trivial-shell/setup/package․lisp file
File, sbcl.lisp: The trivial-shell/port/sbcl․lisp file
File, shell.lisp: The trivial-shell/dev/shell․lisp file
File, trivial-shell.asd: The trivial-shell/trivial-shell․asd file
File, utilities.lisp: The trivial-shell/dev/utilities․lisp file
File, with-timeout.lisp: The trivial-shell/timeout/with-timeout․lisp file

I
index.md: The trivial-shell/website/source/index․md file

M
macros.lisp: The trivial-shell/dev/macros․lisp file
Module, dev: The trivial-shell/dev module
Module, notes: The trivial-shell/notes module
Module, port: The trivial-shell/port module
Module, setup: The trivial-shell/setup module
Module, source: The trivial-shell/website/source module
Module, timeout: The trivial-shell/timeout module
Module, website: The trivial-shell/website module

N
notes: The trivial-shell/notes module
notes.text: The trivial-shell/notes/notes․text file

P
Package, com.metabang.trivial-timeout: The com․metabang․trivial-timeout package
Package, trivial-shell: The trivial-shell package
package.lisp: The trivial-shell/timeout/package․lisp file
package.lisp: The trivial-shell/setup/package․lisp file
port: The trivial-shell/port module

S
sbcl.lisp: The trivial-shell/port/sbcl․lisp file
setup: The trivial-shell/setup module
shell.lisp: The trivial-shell/dev/shell․lisp file
source: The trivial-shell/website/source module
System, trivial-shell: The trivial-shell system

T
timeout: The trivial-shell/timeout module
timeout-error: Public conditions
trivial-shell: The trivial-shell system
trivial-shell: The trivial-shell package
trivial-shell.asd: The trivial-shell/trivial-shell․asd file

U
utilities.lisp: The trivial-shell/dev/utilities․lisp file

W
website: The trivial-shell/website module
with-timeout.lisp: The trivial-shell/timeout/with-timeout․lisp file