This is the maxpc Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:02:57 2024 GMT+0.
maxpc/maxpc.asd
maxpc/packages.lisp
maxpc/input.lisp
maxpc/input/index.lisp
maxpc/input/list.lisp
maxpc/input/vector.lisp
maxpc/input/stream.lisp
maxpc/interface.lisp
maxpc/primitives.lisp
maxpc/more.lisp
maxpc/char.lisp
maxpc/digit.lisp
The main system appears first, followed by any subsystem dependency.
maxpc
Max’s Parser Combinators: a simple and pragmatic library for writing parsers and lexers based on combinatory parsing.
Max Rottenkolber <max@mr.gy>
GNU Affero General Public License
packages.lisp
(file).
input.lisp
(file).
input/index.lisp
(file).
input/list.lisp
(file).
input/vector.lisp
(file).
input/stream.lisp
(file).
interface.lisp
(file).
primitives.lisp
(file).
more.lisp
(file).
char.lisp
(file).
digit.lisp
(file).
Files are sorted by type and then listed depth-first from the systems components trees.
maxpc/maxpc.asd
maxpc/packages.lisp
maxpc/input.lisp
maxpc/input/index.lisp
maxpc/input/list.lisp
maxpc/input/vector.lisp
maxpc/input/stream.lisp
maxpc/interface.lisp
maxpc/primitives.lisp
maxpc/more.lisp
maxpc/char.lisp
maxpc/digit.lisp
maxpc/input.lisp
packages.lisp
(file).
maxpc
(system).
input-element-type
(generic function).
input-empty-p
(generic function).
input-first
(generic function).
input-position
(generic function).
input-rest
(generic function).
input-sequence
(generic function).
make-input
(generic function).
maxpc/input/index.lisp
packages.lisp
(file).
input.lisp
(file).
maxpc
(system).
index
(structure).
index-position
(reader).
index-position
(type).
input-position
(method).
copy-index
(function).
index-p
(function).
make-index
(function).
maxpc/input/list.lisp
packages.lisp
(file).
input.lisp
(file).
input/index.lisp
(file).
maxpc
(system).
input-empty-p
(method).
input-first
(method).
input-rest
(method).
input-sequence
(method).
make-input
(method).
copy-index-list
(function).
index-list
(structure).
index-list-list
(reader).
index-list-p
(function).
index-list-position
(function).
make-index-list
(function).
maxpc/input/vector.lisp
packages.lisp
(file).
input.lisp
(file).
input/index.lisp
(file).
maxpc
(system).
input-element-type
(method).
input-empty-p
(method).
input-first
(method).
input-first
(method).
input-first
(method).
input-rest
(method).
input-rest
(method).
input-rest
(method).
input-sequence
(method).
make-input
(method).
copy-index-simple-string
(function).
copy-index-simple-vector
(function).
copy-index-vector
(function).
index-simple-string
(structure).
index-simple-string-p
(function).
index-simple-string-position
(function).
index-simple-string-vector
(function).
index-simple-vector
(structure).
index-simple-vector-p
(function).
index-simple-vector-position
(function).
index-simple-vector-vector
(function).
index-vector
(structure).
index-vector-p
(function).
index-vector-position
(function).
index-vector-vector
(reader).
make-index-simple-string
(function).
make-index-simple-vector
(function).
make-index-vector
(function).
maxpc/input/stream.lisp
packages.lisp
(file).
input.lisp
(file).
input/index.lisp
(file).
maxpc
(system).
*bound*
(special variable).
*chunk-size*
(special variable).
*element-type*
(special variable).
input-element-type
(method).
input-empty-p
(method).
input-first
(method).
input-rest
(method).
input-sequence
(method).
make-input
(method).
copy-index-stream
(function).
element-type
(function).
fill-buffer
(generic function).
index-stream
(structure).
index-stream-buffer
(reader).
index-stream-p
(function).
index-stream-position
(function).
index-stream-stream
(reader).
make-index-stream
(function).
maybe-fill-buffer
(function).
maxpc/interface.lisp
packages.lisp
(file).
input.lisp
(file).
maxpc
(system).
%handler-case
(macro).
%restart-case
(macro).
get-input-position
(function).
parse
(function).
*input-fail*
(special variable).
*input-start*
(special variable).
cases-to-parser-cases
(function).
parse-line-position
(function).
maxpc/primitives.lisp
packages.lisp
(file).
input.lisp
(file).
maxpc
(system).
maxpc/more.lisp
packages.lisp
(file).
primitives.lisp
(file).
maxpc
(system).
maxpc/char.lisp
packages.lisp
(file).
primitives.lisp
(file).
more.lisp
(file).
maxpc
(system).
*whitespace*
(special variable).
=line
(function).
?char
(function).
?newline
(function).
?string
(function).
?whitespace
(function).
maxpc/digit.lisp
packages.lisp
(file).
primitives.lisp
(file).
more.lisp
(file).
maxpc
(system).
=integer-number
(function).
=natural-number
(function).
?digit
(function).
Packages are listed by definition order.
maxpc.char
maxpc.input.index
maxpc.input.vector
maxpc.input.list
maxpc.input.stream
maxpc.input
maxpc
maxpc.digit
maxpc.char
Utility parsers for character inputs.
common-lisp
.
maxpc
.
*whitespace*
(special variable).
=line
(function).
?char
(function).
?newline
(function).
?string
(function).
?whitespace
(function).
maxpc.input.index
common-lisp
.
maxpc.input
.
index
(structure).
index-position
(reader).
index-position
(type).
copy-index
(function).
index-p
(function).
make-index
(function).
maxpc.input.vector
common-lisp
.
maxpc.input
.
maxpc.input.index
.
copy-index-simple-string
(function).
copy-index-simple-vector
(function).
copy-index-vector
(function).
index-simple-string
(structure).
index-simple-string-p
(function).
index-simple-string-position
(function).
index-simple-string-vector
(function).
index-simple-vector
(structure).
index-simple-vector-p
(function).
index-simple-vector-position
(function).
index-simple-vector-vector
(function).
index-vector
(structure).
index-vector-p
(function).
index-vector-position
(function).
index-vector-vector
(reader).
make-index-simple-string
(function).
make-index-simple-vector
(function).
make-index-vector
(function).
maxpc.input.list
common-lisp
.
maxpc.input
.
maxpc.input.index
.
copy-index-list
(function).
index-list
(structure).
index-list-list
(reader).
index-list-p
(function).
index-list-position
(function).
make-index-list
(function).
maxpc.input.stream
Implements support for _input sources_ of _type_ {stream}. Input from _streams_ is copied into a temporary buffer lazily as required by the parser. _Streams_ of _type_ {file-stream} are read in as chunks of customizable size.
common-lisp
.
maxpc.input
.
maxpc.input.index
.
*bound*
(special variable).
*chunk-size*
(special variable).
*element-type*
(special variable).
copy-index-stream
(function).
element-type
(function).
fill-buffer
(generic function).
index-stream
(structure).
index-stream-buffer
(reader).
index-stream-p
(function).
index-stream-position
(function).
index-stream-stream
(reader).
make-index-stream
(function).
maybe-fill-buffer
(function).
maxpc.input
The generic _input_ interface allows extensions to parse other _types_ of
_input sources_. To add a new _input source type_, {make-input} has to be
specialized on that _type_. The following methods have to be defined for
_inputs_:
+ {input-empty-p}
+ {input-first}
+ {input-rest}
The following methods can optionally be defined for _inputs_:
+ {input-position}
+ {input-element-type}
+ {input-sequence}
common-lisp
.
input-element-type
(generic function).
input-empty-p
(generic function).
input-first
(generic function).
input-position
(generic function).
input-rest
(generic function).
input-sequence
(generic function).
make-input
(generic function).
maxpc
_Max’s Parser Combinators_¹ is a simple and pragmatic library for writing
parsers and lexers based on combinatory parsing. MaxPC is capable of
parsing deterministic, context-free languages, provides powerful tools for
parse tree transformation and error handling, and can operate on
_sequences_ and _streams_. It supports unlimited backtracking, but does not
implement [Packrat Parsing](http://pdos.csail.mit.edu/~baford/packrat/thesis/).
Instead, MaxPC achieves good performance through its optimized primitives,
and explicit separation of matching and capturing input. In practice, MaxPC
parsers perform better on typical computer languages—when compared to
Packrat parsers—at the expense of not producing linear-time parsers.²
+ 1. MaxPC is a complete rewrite of [MPC](https://github.com/eugeneia/mpc)
with was in turn a fork of Drew Crampsie’s
[Smug](http://smug.drewc.ca/).
+ 2. See [MaxPC: Why? How? / Packrat Parsing](http://mr.gy/blog/maxpc.html#section-3-1)
on why the book keeping costs of Packrat parsing diminish the gain in
execution time for typical grammars and workloads.
< Basic Concepts
MaxPC _parsers_ are _functions_ that accept an [input](#section-4) as
their only argument and return three values: the remaining _input_ or
{nil}, a _result value_ or {nil}, and a _generalized boolean_ that
indicates if a _result value_ is present. The _type_ of a parser is:
{(function (}_input_{) (or} _input_ {null) * boolean)}
A parser can either succeed or fail when applied to an input at a given
position. A succeeding parser is said to _match_. When a parser matches it
can optionally produce a _result value_, which may be processed by its
parent parsers. New parsers can be created by composing existing parsers
using built-in or user defined _parser combinators_. A parser combinator
is a higher-order _function_ that includes one or more parsers as its
arguments and returns a parser.
By convention, all parsers are defined as higher-order _functions_ that
return the respective parser, even if they are nullary. For instance, the
{?end} parser is obtained using the form “{(?end)}”.
A lexical convention is used to make three different types of parsers
easily distinguishable:
+ Parsers whose names start with a question mark ({?}) never produce a
result value.
+ Parsers whose names start with an equals sign ({=}) always produce a
result value.
+ Parsers whose names start with a percent symbol ({%}) may produce a
result value depending on their arguments.
>
< Example
We will define a parser for a simplistic grammar for Email addresses of
the form:
_email‑address_ := _user_ {@} _host_
First we define a parser for the valid characters in the _user_ and _host_
parts of an address. Just for this example, we choose these to be
alphanumeric characters and then some. {?address-character} uses the {%or}
combinator to form the union of two instances of {?satisfies} that match
different sets of characters.
#code#
(defun ?address-character ()
(%or (?satisfies ’alphanumericp)
(?satisfies (lambda (c)
(member c ’(#\- #\_ #\. #\+))))))
#
Then we use {?address-character} to implement our address parser which
matches two sequences of “address characters” separated by an {@}
character, and produces a list of user and host components as its result
value. We match {?address-character} one or more times using {%some}, and
produce the matched subsequence as the result value using {=subseq}. Both
parts of the address separated by an _@_ character are matched in sequence
using {=list}, whose result value is finally transformed by
{=destructure}.
#code#
(defun =email-address ()
(=destructure (user _ host)
(=list (=subseq (%some (?address-character)))
(?eq #\@)
(=subseq (%some (?address-character))))
(list user host)))
#
We can now apply {=email-address} using {parse}:
#code#
(parse "foo_bar@example.com" (=email-address))
⇒ ("foo_bar" "example.com"), T, T
(parse "!!!@@@.com" (=email-address))
⇒ NIL, NIL, NIL
(parse "foo_bar@example.com@baz" (=email-address))
⇒ ("foo_bar" "example.com"), T, NIL
#
>
< Overview
{parse} is the entry point of {MaxPC}. It applies a parser to an input and
returns the parser’s result value, and two _boolean_ values indicating if
the parser matched and if there is unmatched input remaining,
respectively.
< Basic Parsers
+ {?end} matches only when there is no further input.
+ {=element} unconditionally matches the next element of the input
_sequence_.
+ {=subseq} produces the subsequence matched by its argument as its
result value.
+ {?satisfies}, {?test}, and {?eq} match input conditionally.
+ {%maybe} matches, even if its argument fails to match.
>
< Logical Combinators
+ {%or} forms the union of its arguments.
+ {%and} forms the intersection of its arguments.
+ {%diff} forms the difference of its arguments.
+ {?not} negates its argument.
>
< Sequence Combinators
+ {?seq} matches its arguments in sequence.
+ {=list} matches its arguments in sequence and produces a list of their
results as its result value.
+ {%any} matches its argument repeatedly any number of times.
+ {%some} matches its argument repeatedly one or more times.
>
< Transformation
+ {=transform} produces the result of applying a _function_ to its
argument’s result value as its result value.
+ {=destructure} is a convenient destructuring _macro_ on top of
{=transform}.
>
< Error Handling
+ {?fail} never matches and evaluates its body when it is called.
+ {%handler-case} and {%restart-case} allow you to set up _handlers_ and
_restarts_ across parsers.
+ {get-input-position} can be called in error situations to retrieve the
current position in the input.
>
>
< Caveat: Recursive Parsers
A recursive parser can not refer to itself by its constructor, but must
instead call itself by _symbol_—calling its constructor would otherwise
result in unbounded recursion. In order to do so the parser _function_
needs to be _bound_ in the _function namespace_ using {setf}. The example
below implements a parser for balanced parentheses, and illustrates how to
avoid this common caveat.
#code#
(defun ?parens ()
(?seq (?eq #\() (%maybe ’?parens/parser) (?eq #\))))
(setf (fdefinition ’?parens/parser) (?parens))
(parse "((()))" (?parens)) ⇒ NIL, T, T
#
>
common-lisp
.
maxpc.input
.
%and
(function).
%any
(function).
%diff
(function).
%handler-case
(macro).
%maybe
(function).
%or
(function).
%restart-case
(macro).
%some
(function).
=destructure
(macro).
=element
(function).
=list
(function).
=subseq
(function).
=transform
(function).
?end
(function).
?eq
(function).
?fail
(macro).
?not
(function).
?satisfies
(function).
?seq
(function).
?test
(macro).
get-input-position
(function).
parse
(function).
*input-fail*
(special variable).
*input-start*
(special variable).
cases-to-parser-cases
(function).
parse-line-position
(function).
maxpc.digit
Parsers for digit numerals in character inputs.
common-lisp
.
maxpc
.
=integer-number
(function).
=natural-number
(function).
?digit
(function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
*Description:*
{*bound*} can be set to limit the number of elements read from _stream inputs_ in a single call to to {parse}.
*Description:*
{*chunk-size*} controls the size by which the buffer used for _stream inputs_ grows, and the number of elements read at a time when parsing from _streams_ of _type_ {file-stream}.
*Description:*
{*element-type*} can be set to enforce a specific stream element type when reading from _stream inputs_. This can be useful when dealing with bivalent streams.
*Value Type:*
a _list_ of _characters_.
*Description:*
The _value_ of {*whitespace*} is a _list_ of _characters_ considered to be _whitespace characters_.
_clauses_::= {{}↓_error‑clause_{\}}\*
_error‑clause_::=
{(}_typespec_ {([}_var_{])}
{{}_declaration_{\}}\* {{}_form_{\}}\* _parser‑form_{)}
*Arguments and Values:*
_parser_—a _parser_.
_typespec_—a _type specifier_.
_var_—a _variable name_.
_declaration_—a {declare} _expression_; not evaluated.
_form_—a _form_.
_parser‑form_—a _form_ that evaluates to a _parser_.
*Description:*
{%handler-case} executes _parser_ in a _dynamic environment_ where handlers
are active as if by {handler-case}. If a _condition_ is handled by
{%handler-case}, _parser‑form_ is evaluated and the resulting _parser_ is
applied.
*Examples:*
#code#
(defun assert-digit (c)
(or (digit-char-p c)
(error "Not a digit: ~c" c)))
(parse "01x2"
(%any (%handler-case (%and (?satisfies ’assert-digit)
(=element))
(error (e)
(format t "Error at position ~a: ~a~%"
(get-input-position) e)
(?seq (=element))))))
▷ Error at position 2: Not a digit: x
→ (#\0 #\1 #\2), T, T
#
*See Also:*
{handler-case}.
_clauses_::= {{}↓_restart‑clause_{\}}\*
_restart‑clause_::=
{(}_case‑name_ {([}_lambda‑list_{])}
〚{:interactive} _interactive‑expression_ |
{:report} _report‑expression_ |
{:test} _test‑expression_〛
{{}_declaration_{\}}\* {{}_form_{\}}\* _parser‑form_{)}
*Arguments and Values:*
_parser_—a _parser_.
_case‑name_—a _symbol_ or {nil}.
_lambda‑list_—an _ordinary lambda list_.
_interactive‑expression_—a _symbol_ or a _lambda expression_.
_report‑expression_—a _string_, a _symbol_, or a _lambda expression_.
_test‑expression_—a _symbol_ or a _lambda expression_.
_declaration_—a {declare} _expression_; not evaluated.
_form_—a _form_.
_parser‑form_—a _form_ that evaluates to a _parser_.
*Description:*
{%restart-case} executes _parser_ in a _dynamic environment_ where restarts
are active as if by {restart-case}. If control is transferred to a
_restart‑clause_, _parser‑form_ is evaluated and the resulting _parser_ is
applied.
*Examples:*
#code#
(parse "012x3"
(%any (%restart-case
(=transform
(=element)
(lambda (c)
(if (digit-char-p c)
c
(error "Not a digit: ~c" c))))
(skip-element ()
:report "Skip character."
(?seq (=element))))))
▷ Error: Not a digit: x
▷ To continue, type :CONTINUE followed by an option number:
▷ 1: Skip non-digit character.
▷ 2: Return to Lisp Toplevel.
▷ Debug> :continue 1
▷ Invoking restart: Skip character.
→ (#\0 #\1 #\2), T, T
#
*See Also:*
{restart-case}.
*Arguments and Values:*
_lambda‑list_—a _destructuring lambda list_.
_parser_—a _parser_.
_forms_—an _implicit progn_.
*Description:*
{=destructure} matches _parser_ and destructures its result value as if by
{destructuring-bind}. The {_} (underscore) symbol can occur in _lambda‑list_
any number of times, and is substituted with a _fresh_, _uninterned symbol_
and declared {ignorable}. If _parser_ matches {=destructure} evaluates
_forms_ and produces the value of the last _form_ as its result value. If no
_forms_ are supplied the value of the last, _interned_ variable defined in
_lambda‑list_ is produced as the result value instead.
*Examples:*
#code#
(parse ’(10 % 3) (=destructure (x _ y)
(=list (=element) (?eq ’%) (=element))
(mod x y)))
→ 1, T, T
(parse "a," (=destructure (x _)
(=list (=element) (?eq #\,))))
→ #\a, T, T
(parse ’(a b c) (=destructure (x &rest xs)
(%some (=element))))
→ ’(B C), T, T
#
*Exceptional Situations:*
If the result value of _parser_ does not match the destructuring pattern, an
_error_ of _type_ {program-error} is signaled.
*See Also:*
{destructuring-bind}
*Arguments and Values:*
_forms_—_forms_.
*Description:*
{?fail} always fails to match, and evaluates _forms_ when it is applied.
*Examples:*
#code#
(parse ’(a b c) (?fail (format t "Position: ~a~%"
(get-input-position))))
▷ Position: 0
→ NIL, NIL, NIL
#
*Arguments and Values:*
_test_—a _designator_ for a _function_ that returns a _generalized boolean_.
_arguments_—_objects_.
_parser_—a _parser_. The default is {(=element)}.
*Description:*
{?test} matches _parser_ if its result value _satisfies the test_ with
_arguments_ as additional arguments to _test_.
*Examples:*
#code#
(parse ’(a) (?test (’member ’(a b)))) ⇒ NIL, T, T
(flet ((power-of-p (n e) (= (mod n e) 0)))
(parse ’(42) (?test (#’power-of-p 2)))) ⇒ NIL, T, T
#
*Notes:*
#code#
(?test ({fun} {args}*}))
≡ (?satisfies (lambda (x)
(funcall {fun} x {args}*)))
#
*Exceptional Situations:*
If _test_ accepts less arguments than the number of _arguments_ plus one an
_error_ of _type_ {program-error} is signaled.
*See also:*
{?satisfies}
*Arguments and Values:*
_parsers_—_parsers_.
*Description:*
{%and} applies _parsers_, and matches the last _parser_ only if all previous
_parsers_ succeed. If the last _parser_ produces a result value then {%and}
produces that value as its result value. It can be said that {%and} forms
the set intersection of _parsers_.
*Examples:*
#code#
(parse ’(:foo) (%and (?satisfies ’symbolp)
(?satisfies ’keywordp)))
→ NIL, T, T
(parse ’(foo) (%and (?satisfies ’symbolp)
(?satisfies ’keywordp)))
→ NIL, NIL, NIL
(parse ’(foo) (%and))
→ NIL, NIL, NIL
(parse ’(foo) (%and (?satisfies ’symbolp)
(=element)))
→ FOO, T, T
(parse ’() (%and (%maybe (?fail (princ ’foo)))
(%maybe (?fail (princ ’bar)))
(%maybe (?fail (princ ’baz)))))
▷ FOOBARBAZ
→ NIL, T, T
#
*Arguments and Values:*
_parser_—a _parser_.
*Description:*
{%any} matches _parser_ in sequence any number of times. If _parser_
produces a result value and matches at least once then {%any} produces a
_list_ of the values as its result value.
*Examples:*
#code#
(parse ’(a b c) (%any (=element))) → (A B C), T, T
(parse ’() (%any (=element))) → NIL, T, T
#
*Arguments and Values:*
_parser_—a _parser_.
_not‑parsers_—_parsers_.
*Description:*
{%diff} matches _parser_ only if applying _not‑parsers_ fails. If _parser_
produces a result value then {%diff} produces that value as its result
value. It can be said that {%diff} forms the set difference of _parser_ and
the union of _not‑parsers_.
*Examples:*
#code#
(parse ’(foo) (%diff (?satisfies ’symbolp)
(?satisfies ’keywordp)))
→ NIL, T, T
(parse ’(:foo) (%diff (?satisfies ’symbolp)
(?satisfies ’keywordp)))
→ NIL, NIL, NIL
(parse ’(foo) (%diff (?satisfies ’symbolp)))
→ NIL, T, T
(parse ’(:foo) (%diff (?satisfies ’symbolp)))
→ NIL, T, T
#
*Arguments and Values:*
_parser_—a _parser_.
*Description:*
{%maybe} matches _parser_ or nothing all, but always succeeds. If _parser_
matches and produces a result value then {%maybe} produces that value as its
result value.
*Examples:*
#code#
(parse ’(a) (%maybe (=element))) → A, T, T
(parse ’() (%maybe (=element))) → NIL, T, T
(parse ’(42) (%maybe (?satisfies ’evenp))) → NIL, T, T
#
*Arguments and Values:*
_parsers_—_parsers_.
*Description:*
{%or} attempts to successfully apply _parsers_, and matches the first
succeeding _parser_, if any. If that _parser_ produces a result value then
{%or} produces that value as its result value. It can be said that {%or}
forms the set union of _parsers_.
*Examples:*
#code#
(parse ’(a) (%or (?eq ’a) (?eq ’b))) → NIL, T, T
(parse ’(b) (%or (?eq ’a) (?eq ’b))) → NIL, T, T
(parse ’(a) (%or)) → NIL, NIL, NIL
(parse ’(a) (%or (=element)
(?fail (format t "No element.~%"))))
→ A, T, T
(parse ’() (%or (?fail (princ ’foo))
(?fail (princ ’bar))
(?fail (princ ’baz))))
▷ FOOBARBAZ
→ NIL, NIL, T
#
*Arguments and Values:*
_parser_—a _parser_.
*Description:*
{%some} matches _parser_ in sequence one or more times. If _parser_ produces
a result value then {%some} produces a _list_ of the values as its result
value.
*Examples:*
#code#
(parse ’(a b c) (%some (=element))) → (A B C), T, T
(parse ’() (%some (=element))) → NIL, NIL, T
#
*Description:*
{=element} matches the next element and produces that element it as its
result value.
*Examples:*
#code#
(parse ’(a) (=element)) → A, T, T
(parse ’() (=element)) → NIL, NIL, T
#
*Arguments and Values:*
_radix_—a _number_ of _type_ {(integer 2 36)}. The default is {10}.
*Description:*
{=integer-number} matches one or more digit _characters_ in the specified
_radix_, optionally lead by a sign character, in sequence, and produces the
_integer_ represented by that sequence as its result value. The leading sign
can be {#\\+} and {#\\-} for positive and negative values respectively.
The default is a positive value.
*Examples:*
#code#
(parse "101010" (=integer-number 2)) → 42, T, T
(parse "+101010" (=integer-number 2)) → 42, T, T
(parse "-101010" (=integer-number 2)) → -42, T, T
(parse "x101010" (=integer-number 2)) → NIL, NIL, NIL
#
*Exceptional Situations:*
If an element attempted to be matched is not a _character_ an _error_ of _type_ {type-error} is signaled.
*Arguments and Values:*
_keep‑newline‑p_—a _generalized boolean_. The default is _false_.
*Description:*
{=line} matches zero or more _characters_ in sequence followed by a
{#\\Newline} _character_ or the end of input, and produces the _string_ of
_characters_ as its result value. The terminating {#\\Newline} _character_
is not included in _string_ unless _keep‑newline‑p_ is _true_.
*Examples:*
#code#
(parse (format nil "foo~%bar~%baz") (%any (=line)))
→ ("foo" "bar" "baz"), T, T
#
*Exceptional Situations:*
If an element attempted to be matched is not a _character_ an _error_ of _type_ {type-error} is signaled.
*Arguments and Values:*
_parsers_—_parsers_.
*Description:*
{=list} matches _parsers_ in sequence, and produces a _list_ of the result
values of _parsers_ as its result value.
*Examples:*
#code#
(parse ’(a) (=list (=element) (?end)))
→ (A NIL), T, T
(parse ’(a b) (=list (=element) (?end)))
→ NIL, NIL, NIL
(parse ’(a) (=list))
→ NIL, T, NIL
#
*Arguments and Values:*
_radix_—a _number_ of _type_ {(integer 2 36)}. The default is {10}.
*Description:*
{=natural-number} matches one or more digit _characters_ in the specified
_radix_ in sequence, and produces the natural _number_ represented by that
digit sequence as its result value.
*Examples:*
#code#
(parse "234" (=natural-number 2)) → NIL, NIL, NIL
(parse "101010" (=natural-number 2)) → 42, T, T
#
*Exceptional Situations:*
If an element attempted to be matched is not a _character_ an _error_ of _type_ {type-error} is signaled.
*Arguments and Values:*
_parser_—a _parser_.
*Description:*
{=subseq} matches _parser_, and produces the subsequence matched by _parser_
as its result value.
*Examples:*
#code#
(parse ’(1 2 3) (=subseq (%any (?satisfies ’numberp))))
→ (1 2 3), T, T
(parse "123" (=subseq (%any (?satisfies ’digit-char-p))))
→ "123" T, T
#
*Arguments and Values:*
_parser_—a _parser_.
_function_—a _designator_ for a _function_ of one argument.
*Description:*
{=transform} matches _parser_ and produces the result of applying _function_
to the result value of _parser_ as its result value.
*Examples:*
#code#
(parse ’(41) (=transform (=element) ’1+)) → 42, T, T
(parse ’() (=transform (=element) ’1+)) → NIL, NIL, T
#
*Arguments and Values:*
_char_—a _character_.
_case‑sensitive‑p_—a _generalized boolean_. The default is _true_.
*Description:*
{?char} matches _char_. {?char} is case sensitive unless _case‑sensitive‑p_
is _false_.
*Exceptional Situations:*
If the next element is not a _character_ an _error_ of _type_ {type-error} is signaled.
*Arguments and Values:*
_radix_—a _number_ of _type_ {(integer 2 36)}. The default is {10}.
*Description:*
{?digit} matches a single digit _character_ in the specified _radix_.
*Exceptional Situations:*
If the next element is not a _character_ an _error_ of _type_ {type-error} is signaled.
*Description:*
{?end} matches the end of input.
*Examples:*
#code#
(parse ’() (?end)) → NIL, T, T
(parse ’(a) (?end)) → NIL, NIL, NIL
#
*Arguments and Values:*
_x_—an _object_.
_parser_—a _parser_. The default is {(=element)}.
*Description:*
{?eq} matches _parser_ if its result value is {eq} to _x_.
*Examples:*
#code#
(parse ’(a) (?eq ’a)) ⇒ NIL, T, T
(parse ’(b) (?eq ’a)) ⇒ NIL, NIL, NIL
#
*See also:*
{?satisfies}
*Description:*
{?newline} matches the {#\\Newline} _character_.
*Arguments and Values:*
_parser_—a _parser_.
*Description:*
{?not} matches the next element unless _parser_ matches.
*Examples:*
#code#
(parse ’(:foo :baz) (?not (?seq (?eq :foo) (?eq :bar))))
→ NIL, T, NIL
(parse ’() (?not (?eq :baz))
→ NIL, NIL, NIL
#
*Arguments and Values:*
_test_—a _designator_ for a _function_ of one argument that returns a
_generalized boolean_.
_parser_—a _parser_. The default is {(=element)}.
*Description:*
{?satisfies} matches _parser_ if its result value _satisfies the test_.
*Examples:*
#code#
(parse ’(1) (?satisfies ’numberp)) → NIL, T, T
(parse ’(a) (?satisfies ’numberp)) → NIL, NIL, NIL
(parse ’(a b c)
(?satisfies (lambda (s)
(intersection s ’(b c d)))
(%any (=element))))
⇒ NIL, T, T
#
*Arguments and Values:*
_parsers_—_parsers_.
*Description:*
{?seq} matches _parsers_ in sequence.
*Examples:*
#code#
(parse ’(a) (?seq (=element) (?end)))
→ NIL, T, T
(parse ’(a b) (?seq (=element) (?end)))
→ NIL, NIL, NIL
(parse ’(a) (?seq))
→ NIL, T, NIL
#
*Arguments and Values:*
_string_—a _string_.
_case‑sensitive‑p_—a _generalized boolean_. The default is _true_.
*Description:*
{?string} matches the _characters_ in _string_ in sequence. {?string} is
case sensitive unless _case‑sensitive‑p_ is _false_.
*Exceptional Situations:*
If an element attempted to be matched is not a _character_ an _error_ of _type_ {type-error} is signaled.
*Description:*
{?whitespace} matches an element that is a member of {*whitespace*}.
*Exceptional Situations:*
If the next element is not a _character_ an _error_ of _type_ {type-error} is signaled.
→ _position_
→ _position_, _line_, _column_
*Arguments and Values:*
_position_, _column_—non-negative _integers_.
_line_—a positive _integer_.
*Description:*
{get-input-position} returns the number of elements read from the input so
far. Additionally, _line_ and _column_ positions are returned if the input’s
_element type_ is {character}. Lines are counted starting at one while
columns are counted starting from zero.
{get-input-position} may only be called from within the body of {?fail}, the
handlers of {%handler-case} or the restarts of {%restart-case}.
*Exceptional Situations:*
If {get-input-position} is not evaluated within the dynamic context of {?fail}, {%handler-case} or {%restart-case} an _error_ of _type_ {simple-error} is signaled.
→ _result_, _match‑p_, _end‑p_
*Arguments and Values:*
_input-source_—an _input source_.
_parser_—a parser.
_result_—an _object_.
_match‑p_, _end‑p_—_generalized booleans_.
*Description:*
{parse} applies _parser_ to the _input_ and returns the parser’s _result
value_ or {nil}. _Match‑p_ is _true_ if _parser_ _matched_ the
_input-source_. _End‑p_ is _true_ if _parser_ _matched_ the complete
_input-source_. _Input_ is derived from _input-source_ by using
{maxpc.input:make-input}.
{parse} accepts _input sources_ of _type_ {sequence} and {stream} out of the
box.
*See Also:*
[input](#section-4), [maxpc.input.stream](#section-5)
→ _typespec_
*Arguments and Values:*
_input_—an _input_.
_typespec_—a _type specifier_.
*Description:*
{input-element-type} returns a _type specifier_ that designates the _type_ of the elements in _input_.
index-stream
)) ¶index-vector
)) ¶→ _empty-p_
*Arguments and Values:*
_input_—an _input_.
_empty-p_—a _generalized boolean_.
*Description:*
{input-empty-p} returns _true_ if _input_ is empty.
index-stream
)) ¶index-vector
)) ¶index-list
)) ¶→ _element_
*Arguments and Values:*
_input_—a non-empty _input_.
_element_—an _object_ of the _type_ designated by the _type specifier_
returned by {input-element-type} when called on _input_.
*Description:*
{input-first} returns the first element in _input_.
*Exceptional Situations:*
If _input_ is empty the behavior of {input-first} is unspecified.
index-stream
)) ¶index-simple-string
)) ¶index-simple-vector
)) ¶index-vector
)) ¶index-list
)) ¶→ _position_
*Arguments and Values:*
_input_—an _input_.
_position_—an _integer_ between 0 and {array-dimension-limit} inclusively.
*Description:*
{input-position} returns the _position_ of _input_.
→ _rest_
*Arguments and Values:*
_input_—a non-empty _input_.
_rest_—the remaining _input_.
*Description:*
{input-rest} returns the remaining _input_ without the first element.
*Exceptional Situations:*
If _input_ is empty the behavior of {input-rest} is unspecified.
index-stream
)) ¶index-simple-string
)) ¶index-simple-vector
)) ¶index-vector
)) ¶index-list
)) ¶→ _sequence_
*Arguments and Values:*
_input_—an _input_.
_length_—an _integer_ between 0 and {array-dimension-limit} inclusively.
_sequence_—a _sequence_.
*Description:*
{input-sequence} returns a _sequence_ of the next _length_ elements in
_input_.
*Exceptional Situations:*
If the number of elements in _input_ are less than _length_ the behavior of {input-sequence} is unspecified.
index-stream
) (length integer
)) ¶index-vector
) (length integer
)) ¶index-list
) (length integer
)) ¶integer
)) ¶*Arguments and Values:*
_input-source_—an _object_.
*Description:*
{make-input} returns an _input_ for _input-source_.
Generic index.
structure-object
.
common-lisp
.
maxpc.input.index:index-position
0
This slot is read-only.
Utility macro function for %HANDLER-CASE and %RESTART-CASE.
Parses line position of POSITION in INPUT.
Index list.
common-lisp
.
list
(error "must supply list.")
This slot is read-only.
Index simple string.
Index simple vector.
Index vector.
common-lisp
.
vector
(error "must supply vector.")
This slot is read-only.
Jump to: | %
=
?
C E F G I M P |
---|
Jump to: | %
=
?
C E F G I M P |
---|
Jump to: | *
B L P S V |
---|
Jump to: | *
B L P S V |
---|
Jump to: | C D F I M P S T |
---|
Jump to: | C D F I M P S T |
---|