The piping Reference Manual

This is the piping Reference Manual, version 2.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:11:29 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 piping

A library to enable simple message pipelines.

Author

Yukari Hafner <>

Home Page

https://shinmera.github.io/piping/

Source Control

(GIT https://github.com/Shinmera/piping.git)

Bug Tracker

https://github.com/Shinmera/piping/issues

License

zlib

Version

2.0.0

Source

piping.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 piping/piping.asd

Source

piping.asd.

Parent Component

piping (system).

ASDF Systems

piping.


3.1.2 piping/package.lisp

Source

piping.asd.

Parent Component

piping (system).

Packages

piping.


3.1.3 piping/array.lisp

Dependency

package.lisp (file).

Source

piping.asd.

Parent Component

piping (system).

Internals

3.1.4 piping/pipe.lisp

Dependency

array.lisp (file).

Source

piping.asd.

Parent Component

piping (system).

Public Interface

3.1.5 piping/pipeline.lisp

Dependency

pipe.lisp (file).

Source

piping.asd.

Parent Component

piping (system).

Public Interface
Internals

name (reader method).


3.1.6 piping/extra.lisp

Dependency

pipeline.lisp (file).

Source

piping.asd.

Parent Component

piping (system).

Public Interface

4 Packages

Packages are listed by definition order.


4.1 piping

Source

package.lisp.

Nicknames
  • org.tymoonnext.radiance.lib.piping
  • org.tymoonnext.piping
Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: make-pipe ()

Creates a new splitter array.

Package

piping.

Source

pipeline.lisp.


5.1.2 Generic functions

Generic Function: add-segment (pipeline segment &optional place)

Add a new segment to the pipeline.
If place is set, the pipe is added to the specified place as per INSERT. The place specified is expected to be a splitter or similar to append the pipe to. Returns the segment. PLACE can be a name, as in FIND-PLACE.

Package

piping.

Source

pipeline.lisp.

Methods
Method: add-segment ((pipeline pipeline) (segment segment) &optional place)
Method: add-segment ((pipeline pipeline) (array array) &optional place)
Method: add-segment ((pipeline pipeline) (array (eql :pipe)) &optional place)
Method: add-segment ((pipeline pipeline) segment &optional place)
Generic Function: find-parent (segment place)

Same as FIND-PLACE, except it returns the parent of the matched item.
As secondary value it returns the position of the matched item within the parent.

Package

piping.

Source

pipeline.lisp.

Methods
Method: find-parent ((switch switch) place)
Source

extra.lisp.

Method: find-parent ((segment segment) place)
Method: find-parent ((array array) (place list))
Method: find-parent ((pipeline pipeline) (place list))
Method: find-parent ((pipeline pipeline) (name symbol))
Generic Function: find-place (segment place)

Searches and returns the segment as designated by PLACE.
A place can be a path (a list of signed integers), each denoting the position of the item within the current splitter or segment. Subsequent numbers descend into the item matched by the previous number.

As such, (1 4) matches the following:
([] () [] [])
- ([] [] [] [] [] [])
^^

A place can also be a name denoting a path within a pipeline, set by SET-NAME. In this case, the name is looked up first, and resolved to a path by RESOLVE-PLACE. If the name given was not previously set in PIPELINE, UNKNOWN-NAME-ERROR is signalled.

Package

piping.

Source

pipeline.lisp.

Methods
Method: find-place ((switch switch) place)
Source

extra.lisp.

Method: find-place ((segment segment) place)
Method: find-place ((array array) (place list))
Method: find-place ((pipeline pipeline) (place list))
Method: find-place ((pipeline pipeline) (name symbol))
Generic Function: insert (segment place &optional position)

Appends the item to the given place unless a specific position is given.
If position is set, the item is expected to be inserted at the specified position, without replacing or disturbing any other items.

Returns the segment.

Do note that using insert directly can affect names and make them invalid or point to unexpected segments. You should always use add-segment or insert-segment instead if possible.

Package

piping.

Source

pipeline.lisp.

Methods
Method: insert (item (switch switch) &optional position)
Source

extra.lisp.

Method: insert (segment (array array) &optional position)
Generic Function: insert-segment (pipeline segment place)

Insert the segment at the given place.
Note that the segment is always inserted into the parent as specified by the place and found by FIND-PARENT and inserted into the position as per INSERT. PLACE can be a name, as in FIND-PLACE.

Returns the segment.

Package

piping.

Source

pipeline.lisp.

Methods
Method: insert-segment ((pipeline pipeline) (segment segment) place)
Method: insert-segment ((pipeline pipeline) (array array) place)
Method: insert-segment ((pipeline pipeline) (array (eql :pipe)) place)
Method: insert-segment ((pipeline pipeline) segment (place symbol))
Generic Function: move-segment (pipeline place new-place)

Moves a segment to another while preserving names.
This attempts to fix names associated with the place or deeper places
by changing their place as well. Either place can be a name, as in FIND-PLACE.

Returns the segment.

Package

piping.

Source

pipeline.lisp.

Methods
Method: move-segment ((pipeline pipeline) place new-place)
Method: move-segment ((pipeline pipeline) (place symbol) new-place)
Method: move-segment ((pipeline pipeline) place (new-place symbol))
Generic Reader: names (object)
Package

piping.

Methods
Reader Method: names ((pipeline pipeline))

automatically generated reader method

Source

pipeline.lisp.

Target Slot

%names.

Generic Writer: (setf names) (object)
Package

piping.

Methods
Writer Method: (setf names) ((pipeline pipeline))

automatically generated writer method

Source

pipeline.lisp.

Target Slot

%names.

Generic Function: pass (segment message)

Pass a message through a segment.

Note for implementors of this method for custom segments: You are expected to return a message object, which will be used for subsequent passing down the current segment. If you return NIL, passing stops. This does not affect passing in segments on other splitters. Do note that changing the object itself directly will of course als be reflected at any other point in the pipeline passing, so muting the passed object should be avoided wherever possible.

Returns the message.

Package

piping.

Source

pipeline.lisp.

Methods
Method: pass ((switch switch) message)
Source

extra.lisp.

Method: pass ((printer printer) message)
Source

extra.lisp.

Method: pass ((filter predicate-filter) message)
Source

extra.lisp.

Method: pass ((pipeline pipeline) message)
Method: pass ((vector vector) message)
Method: pass ((segment segment) message)
Generic Reader: pipe (object)
Package

piping.

Methods
Reader Method: pipe ((switch switch))

automatically generated reader method

Source

extra.lisp.

Target Slot

%pipe.

Generic Writer: (setf pipe) (object)
Package

piping.

Methods
Writer Method: (setf pipe) ((switch switch))

automatically generated writer method

Source

extra.lisp.

Target Slot

%pipe.

Generic Reader: pipeline (object)
Package

piping.

Methods
Reader Method: pipeline ((condition unknown-name-error))
Source

pipeline.lisp.

Target Slot

%pipeline.

Reader Method: pipeline ((pipeline pipeline))

automatically generated reader method

Source

pipeline.lisp.

Target Slot

%pipeline.

Generic Writer: (setf pipeline) (object)
Package

piping.

Methods
Writer Method: (setf pipeline) ((pipeline pipeline))

automatically generated writer method

Source

pipeline.lisp.

Target Slot

%pipeline.

Generic Reader: predicate (object)
Package

piping.

Methods
Reader Method: predicate ((predicate-filter predicate-filter))

automatically generated reader method

Source

extra.lisp.

Target Slot

%predicate.

Generic Writer: (setf predicate) (object)
Package

piping.

Methods
Writer Method: (setf predicate) ((predicate-filter predicate-filter))

automatically generated writer method

Source

extra.lisp.

Target Slot

%predicate.

Generic Reader: print-stream (object)
Package

piping.

Methods
Reader Method: print-stream ((printer printer))

automatically generated reader method

Source

extra.lisp.

Target Slot

%stream.

Generic Writer: (setf print-stream) (object)
Package

piping.

Methods
Writer Method: (setf print-stream) ((printer printer))

automatically generated writer method

Source

extra.lisp.

Target Slot

%stream.

Generic Function: remove-segment (pipeline place)

Removes the given segment (as well as its children, if any).
This also removes any names that either match or go through the specified place and adapts names that would be affected by a place shift. PLACE can be a name, as in FIND-PLACE.

Returns the segment.

Package

piping.

Source

pipeline.lisp.

Methods
Method: remove-segment ((pipeline pipeline) place)
Method: remove-segment ((pipeline pipeline) (place symbol))
Generic Function: replace-segment (pipeline place pipe)

Replace a place with a pipe.
This happens simply through REMOVE-PLACE and INSERT-PIPE. PLACE can be a name, as in FIND-PLACE.

Note that this will destroy names due to REMOVE-PLACE.

Returns the segment.

Package

piping.

Source

pipeline.lisp.

Methods
Method: replace-segment ((pipeline pipeline) place (segment segment))
Method: replace-segment ((pipeline pipeline) place (array array))
Method: replace-segment ((pipeline pipeline) place (array (eql :pipe)))
Method: replace-segment ((pipeline pipeline) (place symbol) pipe)
Generic Function: resolve-place (pipeline place &key if-does-not-exist &allow-other-keys)

Resolve PLACE to a path (ie. list of integers).

If PLACE is already a path, return it unchanged. If it’s a name (as set by SET-NAME), return its corresponding path. IF-DOES-NOT-EXIST determines handling of unknown names: if it’s :ERROR, signal UNKNOWN-NAME-ERROR; if it’s NIL, NIL is silently returned.

Returns a secondary value which is T if the place was successfully resolved, and NIL if it was an unknown name and IF-DOES-NOT-EXIST is NIL.

Package

piping.

Source

pipeline.lisp.

Methods
Method: resolve-place ((pipeline pipeline) (place list) &key &allow-other-keys)
Method: resolve-place ((pipeline pipeline) (place null) &key &allow-other-keys)
Method: resolve-place ((pipeline pipeline) (place symbol) &key if-does-not-exist)
Generic Function: set-name (pipeline place name)

Associates a place with a name so it can be accessed more easily.

Returns the name.

Package

piping.

Source

pipeline.lisp.

Methods
Method: set-name ((pipeline pipeline) (place list) (name symbol))
Generic Reader: value (object)
Package

piping.

Methods
Reader Method: value ((switch switch))

automatically generated reader method

Source

extra.lisp.

Target Slot

%value.

Generic Writer: (setf value) (object)
Package

piping.

Methods
Writer Method: (setf value) ((switch switch))

automatically generated writer method

Source

extra.lisp.

Target Slot

%value.

Generic Function: withdraw (place &optional position)

Removes an item from the place, by default from the end unless position is set.
If position is given, it is expected that the specified item is removed without disturbing any other items and without leaving any empty spaces within the parent.

Returns the segment.

Do note that using withdraw directly can affect names and make them invalid or point to unexpected segments. You should always use remove-segment instead if possible.

Package

piping.

Source

pipeline.lisp.

Methods
Method: withdraw ((switch switch) &optional position)
Source

extra.lisp.

Method: withdraw ((array array) &optional position)

5.1.3 Standalone methods

Method: print-object ((faucet faucet) stream)
Source

pipe.lisp.

Method: print-object ((segment segment) stream)
Source

pipe.lisp.

Method: print-object ((filter filter) stream)
Source

pipe.lisp.


5.1.4 Conditions

Condition: unknown-name-error

Signalled if a name which was not previously set in the pipeline is looked up

Package

piping.

Source

pipeline.lisp.

Direct superclasses

condition.

Direct methods
Direct slots
Slot: %name
Initargs

:name

Readers

name.

Writers

This slot is read-only.

Slot: %pipeline
Initargs

:pipeline

Readers

pipeline.

Writers

This slot is read-only.


5.1.5 Classes

Class: faucet

Base faucet class.

Package

piping.

Source

pipe.lisp.

Direct superclasses

segment.

Direct subclasses

printer.

Direct methods

print-object.

Class: filter

Base filter class.

Package

piping.

Source

pipe.lisp.

Direct superclasses

segment.

Direct subclasses

predicate-filter.

Direct methods

print-object.

Class: pipeline

Base pipeline object that is necessary to orchestrate piping systems.

Package

piping.

Source

pipeline.lisp.

Direct methods
Direct slots
Slot: %pipeline
Initform

(piping:make-pipe)

Initargs

:pipeline

Readers

pipeline.

Writers

(setf pipeline).

Slot: %names
Initform

(make-hash-table :test (quote equal))

Initargs

:names

Readers

names.

Writers

(setf names).

Class: predicate-filter

Segment that predicate-filters messages according to a predicate function.

Package

piping.

Source

extra.lisp.

Direct superclasses

filter.

Direct methods
Direct slots
Slot: %predicate
Initform

(error "predicate function required.")

Initargs

:predicate

Readers

predicate.

Writers

(setf predicate).

Class: printer

Segment that prints each message it receives.

Package

piping.

Source

extra.lisp.

Direct superclasses

faucet.

Direct methods
Direct slots
Slot: %stream
Initform

*standard-output*

Initargs

:stream

Readers

print-stream.

Writers

(setf print-stream).

Class: segment

Base segment class.

Package

piping.

Source

pipe.lisp.

Direct subclasses
Direct methods
Class: switch

A switch that only passes to the pipe as set by its current value.

Package

piping.

Source

extra.lisp.

Direct superclasses

segment.

Direct methods
Direct slots
Slot: %value
Initform

0

Initargs

:value

Readers

value.

Writers

(setf value).

Slot: %pipe
Initform

(piping:make-pipe)

Initargs

:pipe

Readers

pipe.

Writers

(setf pipe).


5.2 Internals


5.2.1 Ordinary functions

Function: array-shift (array &key n from to adjust fill)

Helper function that shifts a subset of array elements in either direction for a specified amount. Optionally also extends the array and fills empty space with a given element.

N — The amount to be moved. Can either be positive or negative.
FROM — Move region start point.
TO — Move region end point.
ADJUST — Whether to adjust the fill pointer and the array bounds.
FILL — If provided, empty spaces created by the move will be filled with this element.

Package

piping.

Source

array.lisp.

Function: vector-pop-position (vector position)

Pops the element at the given position off the vector and returns it. This is potentially very costly as all elements after the given position need to be shifted back as per ARRAY-SHIFT.

Package

piping.

Source

array.lisp.

Function: vector-push-extend-position (element vector position)

Pushes the element into the specified position and shifts everything to the right to make space. This is potentially very costly as all elements after the given position need to be shifted as per ARRAY-SHIFT.

Package

piping.

Source

array.lisp.


5.2.2 Generic functions

Generic Reader: name (condition)
Package

piping.

Methods
Reader Method: name ((condition unknown-name-error))
Source

pipeline.lisp.

Target Slot

%name.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   F   G   I   M   N   P   R   S   V   W  
Index Entry  Section

(
(setf names): Public generic functions
(setf names): Public generic functions
(setf pipe): Public generic functions
(setf pipe): Public generic functions
(setf pipeline): Public generic functions
(setf pipeline): Public generic functions
(setf predicate): Public generic functions
(setf predicate): Public generic functions
(setf print-stream): Public generic functions
(setf print-stream): Public generic functions
(setf value): Public generic functions
(setf value): Public generic functions

A
add-segment: Public generic functions
add-segment: Public generic functions
add-segment: Public generic functions
add-segment: Public generic functions
add-segment: Public generic functions
array-shift: Private ordinary functions

F
find-parent: Public generic functions
find-parent: Public generic functions
find-parent: Public generic functions
find-parent: Public generic functions
find-parent: Public generic functions
find-parent: Public generic functions
find-place: Public generic functions
find-place: Public generic functions
find-place: Public generic functions
find-place: Public generic functions
find-place: Public generic functions
find-place: Public generic functions
Function, array-shift: Private ordinary functions
Function, make-pipe: Public ordinary functions
Function, vector-pop-position: Private ordinary functions
Function, vector-push-extend-position: Private ordinary functions

G
Generic Function, (setf names): Public generic functions
Generic Function, (setf pipe): Public generic functions
Generic Function, (setf pipeline): Public generic functions
Generic Function, (setf predicate): Public generic functions
Generic Function, (setf print-stream): Public generic functions
Generic Function, (setf value): Public generic functions
Generic Function, add-segment: Public generic functions
Generic Function, find-parent: Public generic functions
Generic Function, find-place: Public generic functions
Generic Function, insert: Public generic functions
Generic Function, insert-segment: Public generic functions
Generic Function, move-segment: Public generic functions
Generic Function, name: Private generic functions
Generic Function, names: Public generic functions
Generic Function, pass: Public generic functions
Generic Function, pipe: Public generic functions
Generic Function, pipeline: Public generic functions
Generic Function, predicate: Public generic functions
Generic Function, print-stream: Public generic functions
Generic Function, remove-segment: Public generic functions
Generic Function, replace-segment: Public generic functions
Generic Function, resolve-place: Public generic functions
Generic Function, set-name: Public generic functions
Generic Function, value: Public generic functions
Generic Function, withdraw: Public generic functions

I
insert: Public generic functions
insert: Public generic functions
insert: Public generic functions
insert-segment: Public generic functions
insert-segment: Public generic functions
insert-segment: Public generic functions
insert-segment: Public generic functions
insert-segment: Public generic functions

M
make-pipe: Public ordinary functions
Method, (setf names): Public generic functions
Method, (setf pipe): Public generic functions
Method, (setf pipeline): Public generic functions
Method, (setf predicate): Public generic functions
Method, (setf print-stream): Public generic functions
Method, (setf value): Public generic functions
Method, add-segment: Public generic functions
Method, add-segment: Public generic functions
Method, add-segment: Public generic functions
Method, add-segment: Public generic functions
Method, find-parent: Public generic functions
Method, find-parent: Public generic functions
Method, find-parent: Public generic functions
Method, find-parent: Public generic functions
Method, find-parent: Public generic functions
Method, find-place: Public generic functions
Method, find-place: Public generic functions
Method, find-place: Public generic functions
Method, find-place: Public generic functions
Method, find-place: Public generic functions
Method, insert: Public generic functions
Method, insert: Public generic functions
Method, insert-segment: Public generic functions
Method, insert-segment: Public generic functions
Method, insert-segment: Public generic functions
Method, insert-segment: Public generic functions
Method, move-segment: Public generic functions
Method, move-segment: Public generic functions
Method, move-segment: Public generic functions
Method, name: Private generic functions
Method, names: Public generic functions
Method, pass: Public generic functions
Method, pass: Public generic functions
Method, pass: Public generic functions
Method, pass: Public generic functions
Method, pass: Public generic functions
Method, pass: Public generic functions
Method, pipe: Public generic functions
Method, pipeline: Public generic functions
Method, pipeline: Public generic functions
Method, predicate: Public generic functions
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, print-stream: Public generic functions
Method, remove-segment: Public generic functions
Method, remove-segment: Public generic functions
Method, replace-segment: Public generic functions
Method, replace-segment: Public generic functions
Method, replace-segment: Public generic functions
Method, replace-segment: Public generic functions
Method, resolve-place: Public generic functions
Method, resolve-place: Public generic functions
Method, resolve-place: Public generic functions
Method, set-name: Public generic functions
Method, value: Public generic functions
Method, withdraw: Public generic functions
Method, withdraw: Public generic functions
move-segment: Public generic functions
move-segment: Public generic functions
move-segment: Public generic functions
move-segment: Public generic functions

N
name: Private generic functions
name: Private generic functions
names: Public generic functions
names: Public generic functions

P
pass: Public generic functions
pass: Public generic functions
pass: Public generic functions
pass: Public generic functions
pass: Public generic functions
pass: Public generic functions
pass: Public generic functions
pipe: Public generic functions
pipe: Public generic functions
pipeline: Public generic functions
pipeline: Public generic functions
pipeline: Public generic functions
predicate: Public generic functions
predicate: Public generic functions
print-object: Public standalone methods
print-object: Public standalone methods
print-object: Public standalone methods
print-stream: Public generic functions
print-stream: Public generic functions

R
remove-segment: Public generic functions
remove-segment: Public generic functions
remove-segment: Public generic functions
replace-segment: Public generic functions
replace-segment: Public generic functions
replace-segment: Public generic functions
replace-segment: Public generic functions
replace-segment: Public generic functions
resolve-place: Public generic functions
resolve-place: Public generic functions
resolve-place: Public generic functions
resolve-place: Public generic functions

S
set-name: Public generic functions
set-name: Public generic functions

V
value: Public generic functions
value: Public generic functions
vector-pop-position: Private ordinary functions
vector-push-extend-position: Private ordinary functions

W
withdraw: Public generic functions
withdraw: Public generic functions
withdraw: Public generic functions