The parsnip Reference Manual

This is the parsnip Reference Manual, version 0.0.7, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:31:30 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 parsnip

Parser combinator library

Author

Samuel Hunter

Contact

Home Page

https://sr.ht/~shunter/parsnip/

Source Control

(GIT https://git.sr.ht/~shunter/parsnip)

Bug Tracker

https://todo.sr.ht/~shunter/parsnip

License

BSD 3-Clause

Version

0.0.7

Dependency

alexandria (system).

Source

parsnip.asd.

Child Component

parsnip.lisp (file).


3 Files

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


3.1 Lisp


3.1.1 parsnip/parsnip.asd

Source

parsnip.asd.

Parent Component

parsnip (system).

ASDF Systems

parsnip.


3.1.2 parsnip/parsnip.lisp

Source

parsnip.asd.

Parent Component

parsnip (system).

Packages

xyz.shunter.parsnip.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 xyz.shunter.parsnip

Monadic parser combinator library

Source

parsnip.lisp.

Nickname

parsnip

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Macros

Macro: defparser (name () &body form)

Define a parser as a function. It can then be referenced as a function designator.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Macro: let! ((&rest bindings) &body body)

Return ap arser that runs all given parsers, binds them all to their variables, evaluates the body, and then runs the parser the body returns.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.


5.1.2 Ordinary functions

Function: char-if (predicate &optional message)

Return a parser that consumes a character that satisfies the given predicate.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: char-in (charbag &optional message)

Return a parser that consumes a character that’s only in the given charbag.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: char-of (char &optional message)

Return a parser that consumes the given character.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: collect (parser)

Return a parser that runs the given parser until failure, and collects all results into a list.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: collect-into-string (char-parser)

Return a parser that runs the given character parser until failure, and collects all characters into a string.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: collect1 (parser)

Return a parser that runs the given parser once, keeps parsing until failure, and then collects all results into a list.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: digit (&optional radix)

Consume and return the number value of a digit.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: eof (&optional value)

Return a parser that consumes nothing and returns the given value (or nil) if the input stream is exhausted.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: fail (expected &optional trace)

Return a parser that consumes nothing and fails, reporting the expected value.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: flatmap (function parser)

Return a new parser that applies the given function to the parser’s result, and then runs the parser the function returns. This function forms the basis of stringing multiple parsers together.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: handle (parser handler)

Return a new parser that, on failure, applies the handler function to the parser’s expected value and parse trace (as a list), and then runs the parser the handler returns. HANDLE does not handle partial-parse failures, which can be recovered from via HANDLE-REWIND.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: handle-rewind (parser handler)

Return a new parser that saves the stream’s current position and, on failure, rewinds the stream, applies the handler function to the parser’s expected value and parse trace (as a list), and then runs the parser the handler returns. HANDLE-REWIND only works when the parser is given a seekable stream.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: natural (&optional radix)

Consume and return a natural number.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: ok (value)

Return a parser that consumes nothing and returns the given value.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: or! (&rest parsers)

Return a parser that tries each given parser in order (until a partial-parse failure) and returns the result of the first successful parse.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: parse (parser stream)

Run a parser through a given stream and raise any failures as a PARSER-ERROR.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: prog1! (first &rest parsers)

Return a parser that strings together all given parsers and returns the first parser’s result.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: prog2! (first second &rest parsers)

Return a parser that strings together all given parsers and returns the second parser’s result.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: progn! (&rest parsers)

Return a parser that strings together all given parsers and returns the last parser’s result.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: reduce! (function parser &key initial-parser)

Return a parser that keeps running until failure, and reduces its results into one value.
If INITIAL-PARSER is supplied, the parser may succeed without calling FUNCTION by returning INITIAL-PARSER’s response.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: sep (value-parser sep-parser)

Return a parser that accepts a sequence of VALUE-PARSER input separated by SEP-PARSER input; such as values separated by commas.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: skip (parser)

Parse and pretend no input was consumed.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: skip-many (parser)

Keep parsing until failure and pretend no input was consumed.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: string-of (string &optional message)

Return a parser that consumes the given simple string. This parser may have consumed input on a failure.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: try! (parser)

Return a new parser that saves the stream’s current position and, on failure, rewinds the stream before passing the failure down. TRY! only works when the parser is given a seekable stream.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.


5.1.3 Generic functions

Generic Reader: parser-error-column (condition)
Package

xyz.shunter.parsnip.

Methods
Reader Method: parser-error-column ((condition parser-error))
Source

parsnip.lisp.

Target Slot

column.

Generic Reader: parser-error-expected (condition)
Package

xyz.shunter.parsnip.

Methods
Reader Method: parser-error-expected ((condition parser-error))
Source

parsnip.lisp.

Target Slot

expected.

Generic Reader: parser-error-line (condition)
Package

xyz.shunter.parsnip.

Methods
Reader Method: parser-error-line ((condition parser-error))
Source

parsnip.lisp.

Target Slot

line.

Generic Reader: parser-error-return-trace (condition)
Package

xyz.shunter.parsnip.

Methods
Reader Method: parser-error-return-trace ((condition parser-error))
Source

parsnip.lisp.

Target Slot

return-trace.


5.1.4 Conditions

Condition: parser-error

If a parser fails to read text, it signals a parser-error, containing a stream, its expected value, and a return trace of parsers.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Direct superclasses

stream-error.

Direct methods
Direct slots
Slot: line

The (1-based) line number at which the parser failed

Initargs

:line

Readers

parser-error-line.

Writers

This slot is read-only.

Slot: column

The (0-based) column number at which the parser failed

Initargs

:column

Readers

parser-error-column.

Writers

This slot is read-only.

Slot: expected

An object describing what the parser expected to read

Initargs

:expected

Readers

parser-error-expected.

Writers

This slot is read-only.

Slot: return-trace

A list of (name line column) objects detailing the state of the parser when it failed

Initargs

:return-trace

Readers

parser-error-return-trace.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Macros

Macro: let@ ((&rest bindings) &body body)

Anaphoric self-callable LET.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.


5.2.2 Ordinary functions

Function: advance-pstream (pstream c)

Update the line and column of PSTREAM given the accepted char C and return PSTREAM.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: consume (pstream)
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: parse-stream (stream)
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: peek (pstream)
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Reader: pstream-column (instance)
Writer: (setf pstream-column) (instance)
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Target Slot

column.

Reader: pstream-line (instance)
Writer: (setf pstream-line) (instance)
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Target Slot

line.

Reader: pstream-stream (instance)
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Target Slot

stream.

Function: rewind (pstream snapshot)

Set the (stream) position, line, and column of PSTREAM with the SNAPSHOT received from SAVE.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: save (pstream)

Return the position, line, and column of PSTREAM.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Function: signal-failure (pstream expected return-trace)

Signal an error depending on the given fail.

Package

xyz.shunter.parsnip.

Source

parsnip.lisp.


5.2.3 Structures

Structure: parse-stream
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: stream
Package

common-lisp.

Readers

pstream-stream.

Writers

This slot is read-only.

Slot: line
Initform

1

Readers

pstream-line.

Writers

(setf pstream-line).

Slot: column
Initform

0

Readers

pstream-column.

Writers

(setf pstream-column).


5.2.4 Types

Type: function-designator ()
Package

xyz.shunter.parsnip.

Source

parsnip.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   D   E   F   G   H   L   M   N   O   P   R   S   T  
Index Entry  Section

(
(setf pstream-column): Private ordinary functions
(setf pstream-line): Private ordinary functions

A
advance-pstream: Private ordinary functions

C
char-if: Public ordinary functions
char-in: Public ordinary functions
char-of: Public ordinary functions
collect: Public ordinary functions
collect-into-string: Public ordinary functions
collect1: Public ordinary functions
consume: Private ordinary functions

D
defparser: Public macros
digit: Public ordinary functions

E
eof: Public ordinary functions

F
fail: Public ordinary functions
flatmap: Public ordinary functions
Function, (setf pstream-column): Private ordinary functions
Function, (setf pstream-line): Private ordinary functions
Function, advance-pstream: Private ordinary functions
Function, char-if: Public ordinary functions
Function, char-in: Public ordinary functions
Function, char-of: Public ordinary functions
Function, collect: Public ordinary functions
Function, collect-into-string: Public ordinary functions
Function, collect1: Public ordinary functions
Function, consume: Private ordinary functions
Function, digit: Public ordinary functions
Function, eof: Public ordinary functions
Function, fail: Public ordinary functions
Function, flatmap: Public ordinary functions
Function, handle: Public ordinary functions
Function, handle-rewind: Public ordinary functions
Function, natural: Public ordinary functions
Function, ok: Public ordinary functions
Function, or!: Public ordinary functions
Function, parse: Public ordinary functions
Function, parse-stream: Private ordinary functions
Function, peek: Private ordinary functions
Function, prog1!: Public ordinary functions
Function, prog2!: Public ordinary functions
Function, progn!: Public ordinary functions
Function, pstream-column: Private ordinary functions
Function, pstream-line: Private ordinary functions
Function, pstream-stream: Private ordinary functions
Function, reduce!: Public ordinary functions
Function, rewind: Private ordinary functions
Function, save: Private ordinary functions
Function, sep: Public ordinary functions
Function, signal-failure: Private ordinary functions
Function, skip: Public ordinary functions
Function, skip-many: Public ordinary functions
Function, string-of: Public ordinary functions
Function, try!: Public ordinary functions

G
Generic Function, parser-error-column: Public generic functions
Generic Function, parser-error-expected: Public generic functions
Generic Function, parser-error-line: Public generic functions
Generic Function, parser-error-return-trace: Public generic functions

H
handle: Public ordinary functions
handle-rewind: Public ordinary functions

L
let!: Public macros
let@: Private macros

M
Macro, defparser: Public macros
Macro, let!: Public macros
Macro, let@: Private macros
Method, parser-error-column: Public generic functions
Method, parser-error-expected: Public generic functions
Method, parser-error-line: Public generic functions
Method, parser-error-return-trace: Public generic functions

N
natural: Public ordinary functions

O
ok: Public ordinary functions
or!: Public ordinary functions

P
parse: Public ordinary functions
parse-stream: Private ordinary functions
parser-error-column: Public generic functions
parser-error-column: Public generic functions
parser-error-expected: Public generic functions
parser-error-expected: Public generic functions
parser-error-line: Public generic functions
parser-error-line: Public generic functions
parser-error-return-trace: Public generic functions
parser-error-return-trace: Public generic functions
peek: Private ordinary functions
prog1!: Public ordinary functions
prog2!: Public ordinary functions
progn!: Public ordinary functions
pstream-column: Private ordinary functions
pstream-line: Private ordinary functions
pstream-stream: Private ordinary functions

R
reduce!: Public ordinary functions
rewind: Private ordinary functions

S
save: Private ordinary functions
sep: Public ordinary functions
signal-failure: Private ordinary functions
skip: Public ordinary functions
skip-many: Public ordinary functions
string-of: Public ordinary functions

T
try!: Public ordinary functions