The trivial-shell Reference Manual

Table of Contents

The trivial-shell Reference Manual

This is the trivial-shell Reference Manual, version 0.2.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 18:07:12 2021 GMT+0.

1 Systems

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

1.1 trivial-shell

Maintainer

Gary Warren King <gwking@metabang.com>

Author

Gary Warren King <gwking@metabang.com>

License

MIT Style License

Description

OS and Implementation independent access to the shell

Version

0.2.0

Source

trivial-shell.asd (file)

Components

• notes (module)
• timeout (module)
• setup (module)
• dev (module)
• port (module)
• website (module)

2 Modules

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

2.1 trivial-shell/notes

Parent

trivial-shell (system)

Location

dev/

Component

notes.text (file)

2.2 trivial-shell/timeout

Parent

trivial-shell (system)

Location

timeout/

Components

• package.lisp (file)
• with-timeout.lisp (file)

2.3 trivial-shell/setup

Dependency

timeout (module)

Parent

trivial-shell (system)

Location

dev/

Component

package.lisp (file)

2.4 trivial-shell/dev

Dependency

setup (module)

Parent

trivial-shell (system)

Location

dev/

Components

• definitions.lisp (file)
• macros.lisp (file)
• utilities.lisp (file)
• shell.lisp (file)

2.5 trivial-shell/port

Dependency

dev (module)

Parent

trivial-shell (system)

Location

dev/

Component

sbcl.lisp (file)

2.6 trivial-shell/website

Parent

trivial-shell (system)

Location

website/

Component

source (module)

2.7 trivial-shell/website/source

Parent

website (module)

Location

website/source/

Component

index.md (file)

3 Files

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

3.1 Lisp

3.1.1 trivial-shell.asd

Location

trivial-shell.asd

Systems

trivial-shell (system)

3.1.2 trivial-shell/timeout/package.lisp

Parent

timeout (module)

Location

timeout/package.lisp

Packages

com.metabang.trivial-timeout

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

Dependency

package.lisp (file)

Parent

timeout (module)

Location

timeout/with-timeout.lisp

Exported Definitions

• timeout-error (condition)
• with-timeout (macro)

Internal Definitions

• build-with-timeout (function)
• generate-platform-specific-code (function)

3.1.4 trivial-shell/setup/package.lisp

Parent

setup (module)

Location

dev/package.lisp

Packages

trivial-shell

3.1.5 trivial-shell/dev/definitions.lisp

Parent

dev (module)

Location

dev/definitions.lisp

Exported Definitions

• *bourne-compatible-shell* (special variable)
• *shell-search-paths* (special variable)

3.1.6 trivial-shell/dev/macros.lisp

Parent

dev (module)

Location

dev/macros.lisp

Internal Definitions

• close-stream-specifier (generic function)
• close-stream-specifier (method)
• close-stream-specifier (method)
• make-stream-from-specifier (generic function)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• with-gensyms (macro)
• with-input (macro)
• with-output (macro)
• with-stream-from-specifier (macro)

3.1.7 trivial-shell/dev/utilities.lisp

Parent

dev (module)

Location

dev/utilities.lisp

Internal Definitions

• *os-alist* (special variable)
• directory-pathname-p (function)
• host-os (function)

3.1.8 trivial-shell/dev/shell.lisp

Dependencies

• definitions.lisp (file)
• macros.lisp (file)

Parent

dev (module)

Location

dev/shell.lisp

Exported Definitions

• exit (function)
• get-env-var (function)
• shell-command (method)
• shell-command (method)

Internal Definitions

• file-to-string-as-lines (generic function)
• file-to-string-as-lines (method)
• file-to-string-as-lines (method)
• find-command-ending-in-string (function)
• os-process-id (function)

3.1.9 trivial-shell/port/sbcl.lisp

Parent

port (module)

Location

dev/sbcl.lisp

Internal Definitions

• %exit (function)
• %get-env-var (function)
• %os-process-id (function)
• %shell-command (function)
• %shell-command-using-temporary-file (function)
• create-shell-process (function)
• open-temporary-file (function)
• process-alive-p (function)
• process-exit-code (function)
• read-temporary-file (function)
• symbol-if-external (function)

3.2 Static

3.2.1 trivial-shell/notes/notes.text

Parent

notes (module)

Location

dev/notes.text

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

Parent

source (module)

Location

/home/quickref/quicklisp/dists/quicklisp/software/trivial-shell-20180228-git/website/source/index.md (not found)

4 Packages

Packages are listed by definition order.

4.1 com.metabang.trivial-timeout

Source

package.lisp (file)

Nickname

trivial-timeout

Use List

common-lisp

Used By List

trivial-shell

Exported Definitions

• timeout-error (condition)
• with-timeout (macro)

Internal Definitions

• build-with-timeout (function)
• generate-platform-specific-code (function)

4.2 trivial-shell

Source

package.lisp (file)

Nicknames

• metashell
• com.metabang.trivial-shell

Use List

• com.metabang.trivial-timeout
• common-lisp

Exported Definitions

• *bourne-compatible-shell* (special variable)
• *shell-search-paths* (special variable)
• exit (function)
• get-env-var (function)
• shell-command (generic function)
• shell-command (method)
• shell-command (method)

Internal Definitions

• %exit (function)
• %get-env-var (function)
• %os-process-id (function)
• %shell-command (function)
• %shell-command-using-temporary-file (function)
• *os-alist* (special variable)
• close-stream-specifier (generic function)
• close-stream-specifier (method)
• close-stream-specifier (method)
• create-shell-process (function)
• directory-pathname-p (function)
• file-to-string-as-lines (generic function)
• file-to-string-as-lines (method)
• file-to-string-as-lines (method)
• find-command-ending-in-string (function)
• host-os (function)
• make-stream-from-specifier (generic function)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• make-stream-from-specifier (method)
• open-temporary-file (function)
• os-process-id (function)
• process-alive-p (function)
• process-exit-code (function)
• read-temporary-file (function)
• symbol-if-external (function)
• with-gensyms (macro)
• with-input (macro)
• with-output (macro)
• with-stream-from-specifier (macro)

5 Definitions

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

5.1 Exported definitions

5.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 (file)

Special Variable: *shell-search-paths*

Package

trivial-shell

Source

definitions.lisp (file)

5.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 (file)

5.1.3 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 (file)

Function: get-env-var NAME

Return the value of the environment variable ‘name‘.

Package

trivial-shell

Source

shell.lisp (file)

5.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 (file)

Method: shell-command (COMMAND pathname) &key INPUT

Source

shell.lisp (file)

5.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 (file)

Direct superclasses

error (condition)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *os-alist*

Package

trivial-shell

Source

utilities.lisp (file)

5.2.2 Macros

Macro: with-gensyms SYMS &body BODY

Package

trivial-shell

Source

macros.lisp (file)

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 (file)

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 (file)

Macro: with-stream-from-specifier (STREAM STREAM-SPECIFIER DIRECTION &rest ARGS) &body BODY

Package

trivial-shell

Source

macros.lisp (file)

5.2.3 Functions

Function: %exit CODE

Package

trivial-shell

Source

sbcl.lisp (file)

Function: %get-env-var NAME

Package

trivial-shell

Source

sbcl.lisp (file)

Function: %os-process-id ()

Package

trivial-shell

Source

sbcl.lisp (file)

Function: %shell-command COMMAND INPUT

Package

trivial-shell

Source

sbcl.lisp (file)

Function: %shell-command-using-temporary-file COMMAND INPUT

Package

trivial-shell

Source

sbcl.lisp (file)

Function: build-with-timeout SECONDS BODY

Package

com.metabang.trivial-timeout

Source

with-timeout.lisp (file)

Function: create-shell-process COMMAND WAIT

Package

trivial-shell

Source

sbcl.lisp (file)

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 (file)

Function: find-command-ending-in-string COMMAND

Package

trivial-shell

Source

shell.lisp (file)

Function: generate-platform-specific-code SECONDS-SYMBOL DOIT-SYMBOL

Package

com.metabang.trivial-timeout

Source

with-timeout.lisp (file)

Function: host-os ()

Package

trivial-shell

Source

utilities.lisp (file)

Function: open-temporary-file ()

Package

trivial-shell

Source

sbcl.lisp (file)

Function: os-process-id ()

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

Package

trivial-shell

Source

shell.lisp (file)

Function: process-alive-p PROCESS

Package

trivial-shell

Source

sbcl.lisp (file)

Function: process-exit-code PROCESS

Package

trivial-shell

Source

sbcl.lisp (file)

Function: read-temporary-file FILE-STREAM

Package

trivial-shell

Source

sbcl.lisp (file)

Function: symbol-if-external NAME PACKAGE

Package

trivial-shell

Source

sbcl.lisp (file)

5.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 (file)

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 (file)

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 (file)

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

A.3 Variables

A.4 Data types