The bubble-operator-upwards Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The bubble-operator-upwards Reference Manual

This is the bubble-operator-upwards Reference Manual, version 1.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:00:17 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Project's home: http://www.hexstreamsoft.com/projects/bubble-operator-upwards/


bubble-operator-upwards is a function that "bubbles an operator
upwards" in a form, demultiplexing all alternative branches by way of
cartesian product. This operation is notably useful for easy
implementation of certain kinds of shorthand notations in macros. A
cartesian-product function is also exported, as it's inherently needed
to implement the main function.


Examples
--------

(bubble-operator-upwards 'and '(plate (and ham eggs) beans))
=>
(AND (PLATE HAM BEANS)
     (PLATE EGGS BEANS))


(bubble-operator-upwards 'alt '(section (alt 1 2 3) - (alt "a" "b"))
                         :result-kind :branches)
=>
((SECTION 1 - "a") (SECTION 1 - "b")
 (SECTION 2 - "a") (SECTION 2 - "b")
 (SECTION 3 - "a") (SECTION 3 - "b"))


(bubble-operator-upwards 'or '(>> (or ul ol)
                                  (or (:class (or "important" "urgent"))
                                      (id "first-priority"))))
=>
(OR (>> UL (:CLASS "important"))
    (>> UL (:CLASS "urgent"))
    (>> UL (ID "first-priority"))
    (>> OL (:CLASS "important"))
    (>> OL (:CLASS "urgent"))
    (>> OL (ID "first-priority")))


API
---

First of all, in the way of packages there's the
BUBBLE-OPERATOR-UPWARDS package, which is also nicknamed BUBBLE-OP-UP.
It exports the functions BUBBLE-OPERATOR-UPWARDS and
CARTESIAN-PRODUCT. Explicitly (:import-from) only those you need or
explicitly package-qualify the symbols. Don't (:use)!


Function BUBBLE-OPERATOR-UPWARDS operator form
  &key (result-kind :abridged)
       (if-collapsed nil)
       (collapsed-identity (ecase result-kind
                             ((:full :abridged)
                              (list operator))
                             (:branches nil)))

  Bubbles OPERATOR upwards in FORM, demultiplexing all alternative
  branches by way of cartesian product. Hard to describe formally, but
  the examples above should give some inspiration for the basic
  effect, and some experimentation in the REPL is recommended.

  RESULT-KIND is one of :branches, :full or :abridged.

  - :branches simply returns the demultiplexed branches.

  - :full returns the same result as :branches would,
    except wrapped in a cons whose CAR is OPERATOR.

  - :abridged returns the same result as :full would,
    except if there's only one branch, only that branch
    is returned, without the wrapping.

  IF-COLLAPSED and COLLAPSED-IDENTITY determine what to do if the
  number of branches "collapses" to zero. IF-COLLAPSED is :error or
  NIL. If it's NIL and the result is indeed collapsed, then the value
  of COLLAPSED-IDENTITY will be returned.


Function CARTESIAN-PRODUCT &rest possibility-groups

Returns the cartesian-product of all possible combinations from
POSSIBILITY-GROUPS, as a list.

This function is inherently needed to implement
BUBBLE-OPERATOR-UPWARDS, so might as well export it...

(cartesian-product '(1 2) '(a b c))
=>
((1 A) (1 B) (1 C)
 (2 A) (2 B) (2 C))


This library is in the Public Domain.
See the UNLICENSE file for details.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 bubble-operator-upwards

Author

Jean-Philippe Paradis <hexstream@gmail.com>

License

Public Domain

Description

bubble-operator-upwards is a function that "bubbles an operator upwards" in a form, demultiplexing all alternative branches by way of cartesian product. This operation is notably useful for easy implementation of certain kinds of shorthand notations in macros. A cartesian-product function is also exported, as it’s needed to implement the main function.

Version

1.0

Source

bubble-operator-upwards.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 bubble-operator-upwards.asd

Location

bubble-operator-upwards.asd

Systems

bubble-operator-upwards (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 bubble-operator-upwards/package.lisp

Parent

bubble-operator-upwards (system)

Location

package.lisp

Packages

bubble-operator-upwards


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 bubble-operator-upwards/main.lisp

Dependency

package.lisp (file)

Parent

bubble-operator-upwards (system)

Location

main.lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 bubble-operator-upwards

Source

package.lisp (file)

Nickname

bubble-op-up

Use List

common-lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: bubble-operator-upwards OPERATOR FORM &key RESULT-KIND IF-COLLAPSED COLLAPSED-IDENTITY
Package

bubble-operator-upwards

Source

main.lisp (file)

Function: cartesian-product &rest POSSIBILITY-GROUPS
Package

bubble-operator-upwards

Source

main.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   B   F   L  
Index Entry  Section

B
bubble-operator-upwards.asd: The bubble-operator-upwards<dot>asd file
bubble-operator-upwards/main.lisp: The bubble-operator-upwards/main<dot>lisp file
bubble-operator-upwards/package.lisp: The bubble-operator-upwards/package<dot>lisp file

F
File, Lisp, bubble-operator-upwards.asd: The bubble-operator-upwards<dot>asd file
File, Lisp, bubble-operator-upwards/main.lisp: The bubble-operator-upwards/main<dot>lisp file
File, Lisp, bubble-operator-upwards/package.lisp: The bubble-operator-upwards/package<dot>lisp file

L
Lisp File, bubble-operator-upwards.asd: The bubble-operator-upwards<dot>asd file
Lisp File, bubble-operator-upwards/main.lisp: The bubble-operator-upwards/main<dot>lisp file
Lisp File, bubble-operator-upwards/package.lisp: The bubble-operator-upwards/package<dot>lisp file

Jump to:   B   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   C   F  
Index Entry  Section

B
bubble-operator-upwards: Exported functions

C
cartesian-product: Exported functions

F
Function, bubble-operator-upwards: Exported functions
Function, cartesian-product: Exported functions

Jump to:   B   C   F  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   P   S  
Index Entry  Section

B
bubble-operator-upwards: The bubble-operator-upwards system
bubble-operator-upwards: The bubble-operator-upwards package

P
Package, bubble-operator-upwards: The bubble-operator-upwards package

S
System, bubble-operator-upwards: The bubble-operator-upwards system

Jump to:   B   P   S