blancas.kern.core — org.blancas/kern 1.1.0

The core Kern library.

Kern is a library of parser combinators for Clojure. It is useful for implementing recursive-descent parsers based on predictive LL(1) grammars with on-demand, unlimited look-ahead LL(*).

The main inspiration for Kern comes from Parsec, a Haskell library written by Daan Leijen, as well as work by Graham Hutton, Erik Meijer, and William Burge. The name Kern is a token of appreciation to Brian Kernighan (now at Princeton) for his work on programming languages.

Daan Leijen Parsec, a fast combinator parser, 2001 http://legacy.cs.uu.nl/daan/download/parsec/parsec.pdf

Graham Hutton and Erik Meijer Monadic Parser Combinators, 1996 http://eprints.nottingham.ac.uk/237/1/monparsing.pdf

William H. Burge Recursive Programming Techniques Addison-Wesley, 1975

*tab-width* clj

The number of columns to advance for a tab character. By default, a tab takes four columns.

<$> clj

(<$> f p)

Parses p; if successful, it applies f to the value parsed by p.

<*> clj

(<*> p & more)

Applies one or more parsers; collects the results in a vector, including nil values. If any parser fails, it stops immediately and fails.

<+> clj

(<+> p & more)

Applies one or more parsers stopping at the first failure. Flattens the result and converts it to a string.

<:> clj

(<:> p)

Parses p; on failure it pretends it did not consume any input.

<< clj

(<< p q)

(<< p q & more)

Parses p followed by q; keeps p, skips q. If more parsers are given, it keeps the first result and skips the rest.

<?> clj

(<?> p msg)

If parser p fails consuming no input, it replaces any Expecting errors with a single Expecting with message msg. This helps to produce more abstract and accurate error messages.

<|> clj

(<|> p q)

(<|> p q & more)

Tries p; if it fails without consuming any input, it tries q. With more parsers, it will stop and succeed if a parser succeeds; it will stop and fail if a parser fails consuming input; or it will try the next one if a parser fails without consuming input.

>> clj

(>> p q)

(>> p q & more)

Parses p followed by q; skips p, keeps q. If more parsers are given, it skips all but last and keeps the result of the last.

>>= clj

(>>= p f)

Binds parser p to function f which gets p's value and returns a new parser. Function p must define a single parameter. The argument it receives is the value parsed by p, not ps' return value, which is a parser state record.

alpha-num clj

Parses a letter or digit.

any-char clj

Succeeds with any character.

between clj

(between delim p)

(between open close p)

Applies open, p, close; returns the value of p.

bind clj macro

(bind [& bindings] & body)

Expands into nested >>= forms and a function body. The pattern:

(>>= p1 (fn [v1] (>>= p2 (fn [v2] ... (return (f v1 v2 ...))))))

can be more conveniently be written as:

(bind [v1 p1 v2 p2 ...] (return (f v1 v2 ...)))

char-seq clj

(char-seq rdr)

Returns characters from rdr as a lazy sequence. rdr must implement java.io.Reader

clear-empty clj

(clear-empty s)

Sets the parser state as not empty. Needed in compound parsers where optional parsers at the end may leave an incorrect :empty state for the parser as a whole.

dec-num clj

Parses a decimal integer delimited by any character that is not a decimal digit.

def- clj macro

(def- name & more)

Same as def, yielding a private def.

defn* clj macro

(defn* name & more)

Same as def, yielding a dynamic def.

digit clj

Parses a digit.

end-by clj

(end-by sep p)

Parses p zero or more times, separated and ended by applications of sep; returns the results of p in a vector.

end-by1 clj

(end-by1 sep p)

Parses p one or more times, separated and ended by applications of sep; returns the results of p in a vector.

eof clj

Succeeds on end of input.

expect clj

(expect p msg)

Applies parser p; if it fails (regardless of input consumed) it replaces any expecting errors with expecting msg. This is similar to <?> but works even if some input was consumed.

expecting clj

(expecting msg s)

Sets s as expecting msg.

f->s clj

(f->s f)

(f->s f e)

Gets a character sequence from a file-like object.

fail clj

(fail msg)

Fails without consuming any input, having a single error record with the passed messge msg.

failed-empty? clj

(failed-empty? s)

Tests if s failed without consuming any input.

field* clj

(field* cs)

Parses an unquoted text field terminated by any character in cs.

float-num clj

Parses a simple fractional number without an exponent. It is delimited by any character that is not a decimal digit. It cannot start with a period; the first period found must be followed by at least one digit.

fwd clj macro

(fwd p)

Delays the evaluation of a parser that was forward (declare)d and it has not been defined yet. For use in (def)s of no-arg parsers, since the parser expression evaluates immediately.

get-input clj

(get-input s)

Gets the input stream from a parser state.

get-position clj

(get-position s)

Gets the position in the input stream of a parser state.

get-state clj

(get-state s)

Get the user state from the parser state record.

hex-digit clj

Parses a hexadecimal digit.

hex-num clj

Parses a hex integer delimited by any character that is not a hex digit.

letter clj

Parses a letter.

look-ahead clj

(look-ahead p)

Applies p and returns the result; it consumes no input.

lower clj

Parses a lower-case letter.

many clj

(many p)

Parses p zero or more times; returns the result(s) in a vector. It stops when p fails, but this parser succeeds.

many-till clj

(many-till p end)

Parses zero or more p while trying end, until end succeeds. Returns the results in a vector.

many0 clj

(many0 p)

Like (many) but it won't set the state to :empty. Use instead of (many) if it comes last to avoid overriding non-empty parsing.

many1 clj

(many1 p)

Parses p one or more times and returns the result(s) in a vector. It stops when p fails, but this parser succeeds.

mark clj

Succeeds with a punctuation mark.

member? clj

(member? x coll)

Tests if x is a member of coll.

modify-state clj

(modify-state f & more)

Modify the user state with the result of f, which takes the old user state plus any additional arguments.

new-line* clj

Succeeds on a new line.

none-of* clj

(none-of* cs)

Succeeds if the next character is not in the supplied string.

not-followed-by clj

(not-followed-by p)

Succeeds only if p fails; consumes no input.

oct-digit clj

Parses an octal digit.

oct-num clj

Parses an octal integer delimited by any character that is not an octal digit.

one-of* clj

(one-of* cs)

Succeeds if the next character is in the supplied string.

option clj

(option x p)

Applies p; if it fails without consuming input, it returns a parser state record with the :value x as default.

optional clj

(optional p)

Succeeds if p succeeds or if p fails without consuming input.

parse clj

(parse p cs)

(parse p cs src)

(parse p cs src us)

Parses a character sequence; takes an optional label and a user state initial value, which default to nil. Returns a PState record.

cs A seqable object; parse calls (seq) on this value. src Identifies the source of the text, e.g. a filename. us Initializes a field that is maintained by client code.

parse-data clj

(parse-data p cs)

(parse-data p cs src)

(parse-data p cs src us)

Works like (parse) but with error diagnostics disabled for better performance. It's intended for data that can be assumed to be correct or its diagnosis postponed.

parse-data-file clj

(parse-data-file p f)

(parse-data-file p f en)

(parse-data-file p f en us)

Works like (parse-file) but with error diagnostics disabled for better performance. It's intended for data files that can be assumed to be correct or its diagnosis postponed.

parse-file clj

(parse-file p f)

(parse-file p f en)

(parse-file p f en us)

Parses a file; takes an optional encoding and user state, which default to utf-8 and nil. Returns a PState record.

predict clj

(predict p)

Applies p; if it succeeds it consumes no input.

print-error clj

(print-error s)

Prints error messages in a PState record.

put-state clj

(put-state u)

Put u as the new value for user state in the parser state record.

reply clj

(reply v s)

Makes s succeed with value v.

return clj

(return v)

Succeeds without consuming any input. Any carried errors are removed.

run clj

(run p cs)

(run p cs src)

(run p cs src us)

For testing parsers, e.g. at the REPL. Calls (parse) on the arguments and prints the result. If p succeeds it prints the parsed value; if it fails it prints any error messages.

run* clj

(run* p cs)

(run* p cs src)

(run* p cs src us)

For testing parsers, e.g. at the REPL. Works like (run) but on success it pretty-prints the resulting parser state.

runf clj

(runf p f)

(runf p f en)

(runf p f en us)

For testing, e.g. at the REPL, with input from files. Prints the results.

runf* clj

(runf* p f)

(runf* p f en)

(runf* p f en us)

For testing, e.g. at the REPL, with input from files. Pretty-prints the results.

satisfy clj

(satisfy pred)

Succeeds if the next character satisfies the predicate pred, in which case advances the position of the input stream. It may fail on an unexpected end of input.

search clj

(search p)

Applies a parser p, traversing the input as necessary, until it succeeds or it reaches the end of input.

sep-by clj

(sep-by sep p)

Parses p zero or more times while parsing sep in between; collects the results of p in a vector.

sep-by1 clj

(sep-by1 sep p)

Parses p one or more times while parsing sep in between; collects the results of p in a vector.

sep-end-by clj

(sep-end-by sep p)

Parses p zero or more times separated, and optionally ended by sep; collects the results in a vector.

sep-end-by1 clj

(sep-end-by1 sep p)

Parses p one or more times separated, and optionally ended by sep; collects the results in a vector.

set-input clj

(set-input in)

Sets the input stream in a parser state.

set-position clj

(set-position pos)

Sets the position in the input stream of a parser state.

skip clj

(skip p)

(skip p q)

(skip p q & more)

Applies one or more parsers and skips the result. That is, it returns a parser state record with a :value nil.

skip-many clj

(skip-many p)

Parses p zero or more times and skips the results. This is like skip but it can apply p zero, one, or many times.

skip-many1 clj

(skip-many1 p)

Parses p one or more times and skips the results.

skip-ws clj

(skip-ws p)

Skips whitespaces before parsing p.

space clj

Parses the space character.

split clj

Splits a string on whitespace.

split-on clj

(split-on cs)

Splits a string on one of the given characters and whitespace. Removes empty strings from the result.

sym* clj

(sym* x)

Parses a single symbol x (a character).

sym- clj

(sym- x)

Parses a single symbol x (a character); not case-sensitive.

tab clj

Parses the tab character.

times clj

(times n p)

Applies p n times; collects the results in a vector.

token* clj

(token* xs)

(token* xs & more)

Parses a specific string, not necessarily delimited. If more than one are given it will try each choice in turn.

token- clj

(token- xs)

(token- xs & more)

Parses a specific string, not necessarily delimited; not case-sensitive. If more than one are given it will try each choice in turn.

unexpected clj

(unexpected msg s)

Sets s as failed because an unexpected reason.

unexpected-input clj

(unexpected-input in s)

Sets s as failed because of an unexpected input.

upper clj

Parses an upper-case letter.

value clj

(value p cs)

(value p cs src)

(value p cs src us)

Calls (parse) on the arguments and returns the actual parsed value, not the PState record.

white-space clj

Parses a whitespace character.

word* clj

(word* letter cs)

(word* letter cs & more)

Parses a specific string, delimited by letter. If more than one are given it will try each choice in turn.

word- clj

(word- letter cs)

(word- letter cs & more)

Parses a specific string, delimited by letter; not case-sensitive. If more than one are given it will try each choice in turn.