piping

Table of Contents

What is Piping?

Piping is a small library providing mechanisms to create message passing pipeline constructs.

How To

Load Piping through Quicklisp or ASDF:

(ql:quickload :piping)

Create a pipeline and add some pipe segments:

(defvar *pipeline* (make-instance 'pipeline))
(add-segment *pipeline* (make-instance 'predicate-filter :predicate #'evenp))
(add-segment *pipeline* (make-instance 'printer))

Using pass you can then pass items down the pipeline:

(pass *pipeline* 7)
(pass *pipeline* 6)

Often times you'll want to create pipe branches so to speak, to split off passing and to filter for different things:

(add-segment *pipeline* (make-pipe))
(add-segment *pipeline* (make-instance 'predicate-filter :predicate #'zerop) '(2))
(add-segment *pipeline* (make-instance 'printer) '(2))

The last argument to add-segment is a place indicator. A place is always a list of indexes, each index specifying the index within the current pipe. add-segment then adds the segment to the end of the pipe, in this case the pipe we added.

In order to have easier access to places, you can use set-name to create names for certain places. Do note that modifying the pipeline might change or destroy names. See the each function's docstring for more information.

Creating custom pipe segments is just a question of subclassing segment and defining the pass method. If your segment should act like a pipe, you'll have to define methods for find-place, find-parent, insert and withdraw as well.

Visualizing the pipeline can be done relatively well by simply printing the main pipe:

(pipeline *pipeline*)
; ==> #(:FILTER: >>FAUCET #(:FILTER: >>FAUCET)

System Information

Definition Index

• PIPING

  • ORG.TYMOONNEXT.RADIANCE.LIB.PIPING
  • ORG.TYMOONNEXT.PIPING

  No documentation provided.

  • EXTERNAL CLASS

    FAUCET

    Source

    Base faucet class.

  • EXTERNAL CLASS

    FILTER

    Source

    Base filter class.

  • EXTERNAL CLASS

    PIPELINE

    Source

    Base pipeline object that is necessary to orchestrate piping systems.

  • EXTERNAL CLASS

    PREDICATE-FILTER

    Source

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

  • EXTERNAL CLASS

    PRINTER

    Source

    Segment that prints each message it receives.

  • EXTERNAL CLASS

    SEGMENT

    Source

    Base segment class.

  • EXTERNAL CLASS

    SWITCH

    Source

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

  • EXTERNAL CONDITION

    UNKNOWN-NAME-ERROR

    Source

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

  • EXTERNAL FUNCTION

    MAKE-PIPE

    Source

    Creates a new splitter array.

  • EXTERNAL GENERIC-FUNCTION

    ADD-SEGMENT

    • PIPELINE
    • SEGMENT
    • &OPTIONAL
    • PLACE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    FIND-PARENT

    • SEGMENT
    • PLACE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    FIND-PLACE

    • SEGMENT
    • PLACE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    INSERT

    • SEGMENT
    • PLACE
    • &OPTIONAL
    • POSITION
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    INSERT-SEGMENT

    • PIPELINE
    • SEGMENT
    • PLACE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    MOVE-SEGMENT

    • PIPELINE
    • PLACE
    • NEW-PLACE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    NAMES

    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    (SETF NAMES)

    • NEW-VALUE
    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    PASS

    • SEGMENT
    • MESSAGE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    PIPE

    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    (SETF PIPE)

    • NEW-VALUE
    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    PIPELINE

    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    (SETF PIPELINE)

    • NEW-VALUE
    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    PREDICATE

    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    (SETF PREDICATE)

    • NEW-VALUE
    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    PRINT-STREAM

    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    (SETF PRINT-STREAM)

    • NEW-VALUE
    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    REMOVE-SEGMENT

    • PIPELINE
    • PLACE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    REPLACE-SEGMENT

    • PIPELINE
    • PLACE
    • PIPE
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    RESOLVE-PLACE

    • PIPELINE
    • PLACE
    • &KEY
    • IF-DOES-NOT-EXIST
    • &ALLOW-OTHER-KEYS
    • &REST

    Source

    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.

  • EXTERNAL GENERIC-FUNCTION

    SET-NAME

    • PIPELINE
    • PLACE
    • NAME
    • &REST

    Source

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

  • EXTERNAL GENERIC-FUNCTION

    VALUE

    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    (SETF VALUE)

    • NEW-VALUE
    • OBJECT
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    WITHDRAW

    • PLACE
    • &OPTIONAL
    • POSITION
    • &REST

    Source

    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.