1. Moritz Heidkamp
  2. plan

Commits

Moritz Heidkamp  committed 3c5561a

Add generated and slightly modifeid documentation

  • Participants
  • Parent commits 1e804d3
  • Branches master

Comments (0)

Files changed (1)

File plan.wiki

View file
+== plan
+
+A data structure for representing process plans.
+[[toc:]]
+=== Overview
+''A plan is typically any diagram or list of steps with timing
+and resources, used to achieve an objective.'' ― [[http://en.wikipedia.org/wiki/Plan]]
+
+This extension provides a {{plan}} data structure which is inspired by
+[[http://blog.getprismatic.com/blog/2012/10/1/prismatics-graph-at-strange-loop.html|Prismatic's
+"Graph"]]. It represents processes and their
+interdependencies. Plans can be inspected, augmented, or realized. The
+source code can be found on
+[[https://bitbucket.org/DerGuteMoritz/plan|Bitbucket]].
+
+
+=== API
+==== {{make-plan}}
+<procedure>(make-plan steps) → plan</procedure>
+Constructs a plan record with the given list of {{steps}} of the following form:
+
+  steps          = (<step> ...)
+  step           = <constant-step> | <dependent-step>
+  constant-step  = (<name> #f . <value>)
+  dependent-step = (<name> (<dependency> ...) . proc)
+  dependency     = <name>
+  value          = datum
+  name           = datum
+
+Semantically, a step is a description of how to realize a (sub-)result
+of a plan. It consist of the following components:
+
+* A {{name}}, which may be any kind of datum comparable with
+  {{equal?}}, usually a symbol or a string. However, pairs as step
+  names should be avoided.
+
+* Zero or more dependencies which are specified as a list of step
+  names. Upon realization (see [[#realize-plan|{{realize-plan}}]]),
+  dependencies will be realized before a dependent step is
+  realized. Alternatively, {{#f}} can be used to signify that this step
+  has a constant result without any dependencies.
+
+* A realization result which can either be a constant {{value}} or
+  procedure {{proc}} which produces a result from the given
+  dependencies. In the latter case, dependencies are realized
+  before their results are passed as arguments to {{proc}} in the
+  order they are specified.
+
+==== {{plan-steps}}
+<procedure>(plan-steps plan) → (<step> ...)</procedure>
+Returns a {{plan}}'s list of steps as passed to [[#make-plan|{{make-plan}}]].
+
+==== {{plan?}}
+<procedure>(plan? datum) → boolean</procedure>
+Checks whether {{datum}} is a plan.
+
+==== {{plan}}
+<syntax>(plan step...) → plan</syntax>
+Convenience syntax for constructing plans. Its
+body has the following structure:
+
+  step           = <constant-step> | <dependent-step>
+  constant-step  = (<name> value)
+  dependent-step = (<name> (<dependency> ...) expression ...)
+  dependency     = <name>
+  name           = symbol
+
+See [[#make-plan|{{make-plan}}]] for explanation of steps and
+dependencies. Note that with this form, step names must be
+symbols. For dependent steps, those names are then lexically bound
+when {{expression ...}} is evaluated upon realization.
+
+==== {{make-plan-realization}}
+<procedure>(make-plan-realization realize-step step-result) → plan-realization</procedure>
+Constructs a record to be used for [[#plan-realization|{{plan-realization}}]].
+; realize-step : A procedure that accepts a {{promise}} which, when forced, produces a step's result. During realization by [[#realize-plan|{{realize-plan}}]] it is applied to each step to be realized exactly once. Its return value is then passed to {{step-result}}.
+; step-result : A procedure that accepts one argument which is whatever is returned by this realization's {{realize-step}}. It is expected to return the step's result value and may be called multiple times.
+==== {{plan-realization-sequential}}
+<constant>plan-realization-sequential → (make-plan-realization force force)</constant>
+A sequential plan realization which realizes a plan one step after another.
+==== {{plan-realization}}
+<parameter>plan-realization → plan-realization-sequential</parameter>
+The current plan realization strategy to be used by
+[[#realize-plan|realize-plan]]. The default value is
+[[#plan-realization-sequential|{{plan-realization-sequential}}]]. See
+[[#make-plan-realization|make-plan-realization]] on how to construct a
+custom plan realization.
+==== {{realize-plan}}
+<procedure>(realize-plan plan . args) → result</procedure>
+Realizes the given plan using the current [[#plan-realization|{{plan-realization}}]].
+
+; plan : The plan to realize
+; args : Optional arguments of the following structure:
+
+  (<to-realize> [<return-all-realized-results?>] <input> ... [keyword value] ...)
+
+; to-realize : A step name or a list of step names to be realized. When given, only those steps and their dependencies will be realized.
+; return-all-realized-results? : If the second optional argument is {{#t}} then, no matter what is passed as {{to-realize}}, the whole result map will be returned.
+; input ... : Zero or more alists with keys being step names and values being constant results. Later alists override previous ones.
+; keyword value : Zero or more keyword/value pairs. The keyword will be turned in to symbols and used as step names with their respective values as results.
+
+==== {{merge-plans}}
+<procedure>(merge-plans . plans) → plan</procedure>
+Merges the given {{plans}} from right to left.
+
+==== {{plan-let}}
+<syntax>(plan-let steps body...) → value of last body expression</syntax>
+A form for defining and immediately realizing a plan,
+binding local variables for each step result.
+; steps : A list of steps in the same format as accepted by the [[#plan|{{plan}}]] form.
+; body... : The body in which the results of realized steps are bound.
+==== {{write-plan-dot}}
+<procedure>(write-plan-dot plan #!optional (out (current-output-port)) (name plan)) → unspecified</procedure>
+Writes a Graphviz {{DOT}} representation of {{plan}} to the given {{out}} port.
+
+=== About this egg
+
+==== Author
+
+[[/users/syn|Moritz Heidkamp]]
+==== Colophon
+
+Documented by [[/egg/cock|cock]].