Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the doplus Reference Manual, version 1.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:27:40 2022 GMT+0.
Next: Systems, Previous: The doplus Reference Manual, Up: The doplus Reference Manual [Contents][Index]
doplus (written DO+) is an iteration macro for Common Lisp. I wrote it because:
We can think of doplus as a higher-level DSL over CL:DO [*]. In spirit it's similar to iterate, but having implementation simplicity as a core goal, its syntax is necessarily a bit different to accomodate the lack of a code walker that can freely move pieces of code around. Also, doplus generally requires the user to be a bit more explicit than both LOOP and iterate.
doplus, like iterate, is meant to be extensible by simply writing macros. By contrast, LOOP is not portably extensible, and on those implementations where it is, it's not trivial to extend it. Most macros that extend doplus can be written combining built-in operators and producing code in doplus syntax, just like a user might have written it. This makes many possible doplus extensions very readable.
doplus is fully understood by SLIME, since it uses regular macros and defines dummy top-level macros for its body-local macrolets, to make symbol completion available for them as well.
doplus is, to my knowledge, the only advanced iteration construct in Lisp to support atomic initialization and stepping of iteration variables. Refer to the manual section Initialization and stepping for more information.
[*] doplus used to be actually written on top of cl:do*, but has been rewritten using lower-level constructs to have more control on the various steps of iteration.
You can find doplus on Quicklisp.
The manual is on a separate page.
doplus is distributed under the GPLv3 license; if you'd like a different license arrangement, please contact me. I'm very open about providing friendlier licenses to individuals and companies that I trust, but by default I won't allow complete strangers to profit from my code without giving anything back.
To run the test suite, load the system :doplus-tests after loading :doplus itself. To rerun the test suite after :doplus-tests has been loaded, evaluate the form (doplus-tests:run-all-tests).
The home of doplus is https://github.com/alessiostalla/doplus. There you can find in-depth documentation, access the code repository and checkout the latest version.
Next: Files, Previous: Introduction, Up: The doplus Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
DO+ (doplus) is a high-level, extensible iteration construct for Common Lisp with a reasonably simple implementation, which in particular does not use a code walker.
Alessio Stalla <alessiostalla@gmail.com>
GPLv3
1.1.0
parse-declarations-1.0 (system).
Next: Packages, Previous: Systems, Up: The doplus Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: doplus/packages.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
doplus (system).
Next: doplus/destructuring.lisp, Previous: doplus/doplus.asd, Up: Lisp [Contents][Index]
doplus (system).
Next: doplus/doplus.lisp, Previous: doplus/packages.lisp, Up: Lisp [Contents][Index]
packages.lisp (file).
doplus (system).
Previous: doplus/destructuring.lisp, Up: Lisp [Contents][Index]
destructuring.lisp (file).
doplus (system).
Next: Definitions, Previous: Files, Up: The doplus Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The doplus Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Specifies an accumulation clause. Refer to the manual for details.
Same as accumulating-into, but also returns the value of each <vars> at the end of the loop.
Synonym for in-vector.
Assigns to the iteration variable a value computed by evaluating FORM on each iteration, including the first. Optionally, the variable can be updated evaluating a differen form (the value of the ‘then’ parameter). Examples: (for x (being (random))), (for y (being ’quiet :then (if (> x 0.5) ’angry ’quiet))).
Collects a value into an accumulator. If no accumulator is provided, the default one for the current do+ loop is used.
Synonym for accumulating-to.
Same as collecting-into, but also returns the value of each <vars> at the end of the loop.
Counts the number of iterations, starting from 0.
Same as cl:defmacro, but additionally records <name> in *clauses* as a known clause macro.
High-level, extensible iteration construct. Refer to the manual for syntax and semantics.
Evaluates <form> after the last iteration, before returning a value.
Same as FOR, but perhaps nicer to read when used in conjunction with macros like MAXIMIZING.
General iteration clause. Its actual behaviour is controlled by ITERATION, a macro form that FOR expands with *ITERATION-VARIABLE* bound to VAR. Example: in (for x (in ’(1 2 3))), IN is a macro that expands into clauses that make use of *ITERATION-VARIABLE*, which is bound to the symbol X in the example. For certain iteration macros, VAR can be a lambda-list as well, in which case destructuring is applied. Example: (for (x &optional y) (in-list ’((1 2) (3)))).
Iterates from a given initial value to an optional maximum. Every iteration increments/decrements the value applying the <using> function (by default +) to the previous value and <by> (by default 1 or -1, depending on whether to >= from or not). Similarly, the <while> function is used to determine if <to> has been reached or surpassed. <while> is a function of two arguments, the current value and the value of <to>, and as soon as it returns false, the loop is terminated. <while> defaults to a function that returns true only if <to> has been specified and, letting cur be the current value, (<= (min to from) cur (max to from)).
Lazy version of FOR. The user must call UPDATE or TRY-UPDATE in the body of the DO+ form in order to compute new values for the variable(s). Initialization, instead, is *always* performed eagerly.
Iterates over the entries of a hash table. The iteration variables must be specified as (key value), for example: (for (lemma definitions) (hash-entries-of the-english-vocabulary)).
Iterates over a sequence. IN must be used in combination with FOR, GENERATING and similar macros (those that bind *ITERATION-VARIABLE*). In implementations with extensible sequences (currently ABCL and SBCL), native sequence iterators are used, and all sequence types are supported, not just lists and vectors. In other implementations, an iterator specialized for lists or vectors is used depending on the type of sequence. All ‘args‘ are passed down to make-sequence-iterator (see the extensible sequences API paper for details [Rhodes2007]). IN can perform destructuring.
Like IN, but specialized for lists. Successive lists are obtained by calling the function BY (which by default is #’CDR) on the previous list. REST, if specified, is the variable holding the remaining elements to be processed; REST initially is bound to the entire list, then to successive lists obtained by funcalling BY.
Loops across a vector. INDEX is bound to the index of the current element in the vector. The vector is traversed starting from index START (0 by default) to index END (the end of the vector if not specified); the index is incremented by BY (1 by default) on each iteration.
Evaluates <form> before the first iteration.
Loops over the successive tails of a list, checking for the end of the list as if by ATOM. Can perform destructuring.
Synonym for optimizing.
Same as optimizing but with < as the default test.
Finds the optimum value of an expression across the iteration. Refer to the manual for details.
On every iteration, the for-variable is set to the value <expr> had at the end of the previous iteration (initially NIL).
Returns each form in <forms> as the value of the do+ form when the loop ends. If multiple forms are specified, by one or more RETURNING clauses, multiple values are returned, in the order the corresponding forms appear lexically. If one of the <forms> is (cl:values ...), then each value will be returned as if the values were spelled as direct arguments of the RETURNING form.
Skips the current iteration. Refers to the current loop or, if loop-name is specified, to the closest surrounding loop with that name.
Synonym for until.
Syntactic sugar for collect, intended to be used when the accumulator computes a sum.
Specifies an accumulation strategy with 0 as the default value and + as the accumulator function.
Same as summing-to, but also returns the value of each <vars> at the end of the loop.
Iterates over the symbols in one or more packages. Symbol-types follows the specification of cl:with-package-iterator.
Immediately terminates the loop. Refers to the current loop or, if loop-name is specified and non-NIL, to the closest surrounding loop with that name. Can optionally specify a return value for the loop, which, if provided, will override the loop’s ordinary return value.
Variation over from.
Tries to update the generator named <var> as by UPDATE. If the loop would be terminated as a result of the update operation, it is not terminated.
Any errors occurring during the update are ignored by default; however, it is possible to provide a function to be invoked in case of error to determine what to do. This is the value of the <on-error> parameter, which, if provided, must be a function of two arguments: the first is the value to be returned as the result of the try-update form if the error is suppressed; the second is the condition object itself, which can be resignaled. Calling TERMINATE inside the function, if it is defined lexically inside the DO+ body, will regularly terminate the loop.
Updates the generator named <var>, calculating new value(s) for its variable(s) and evaluating its pre and post conditions, terminating the loop if they fail. If successful, the update returns the value of <var>.
Establishes bindings which are in effect for the whole loop.
Next: Structures, Previous: Macros, Up: Public Interface [Contents][Index]
General iteration clause generator.
Specialized iteration clause generator, where the iteration clause refers to a single variable, possibly with an initial value, step form, precondition, or postcondition.
Previous: Ordinary functions, Up: Public Interface [Contents][Index]
structure-object.
common-lisp.
Previous: Public Interface, Up: Definitions [Contents][Index]
A list of known symbols that name clause macros, useful for introspection and documentation purposes.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Causes the emission of a (declare <thing>) form in the declaration section of the loop.
Specifies a termination clause for the loop. When, at the beginning of an iteration, the clause evaluates to true, the loop stops.
Same as (until (not <condition>)).
Next: Structures, Previous: Macros, Up: Internals [Contents][Index]
var.
var.
form.
(if (listp obj) obj (list obj))
form.
Expand ‘form’ in ‘env’ as an iteration form that assigns to ‘*iteration-variable*’ destructuring as by ‘destructuring-bind’.
form.
name.
form.
map.
form.
form.
form.
Previous: Ordinary functions, Up: Internals [Contents][Index]
structure-object.
structure-object.
structure-object.
structure-object.
structure-object.
structure-object.
structure-object.
structure-object.
structure-object.
common-lisp.
structure-object.
common-lisp.
Previous: Definitions, Up: The doplus Reference Manual [Contents][Index]
| Jump to: | %
(
A B C D E F G H I L M O P R S T U W |
|---|
| Jump to: | %
(
A B C D E F G H I L M O P R S T U W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
A C D F G L M N P S T V |
|---|
| Jump to: | *
A C D F G L M N P S T V |
|---|
| Jump to: | A B D E F G I O P R S T W |
|---|
| Jump to: | A B D E F G I O P R S T W |
|---|