modules/lang/lisp/parser.zzm

NAME

lang/lisp/parser - Parse Lisp/Scheme S-expressions.

SYNOPSIS

  from lang/lisp/parser import parse_program, parse_sexpr, sym;

  let expr := parse_sexpr("(+ 1 2)");
  say( expr[0].get_name() );  // +

  let direct := [ sym("+"), 1, 2 ];

  let program := parse_program("(define x 1)\n(+ x 2)", "example.lizp");
  say( program.location_for( program.get_exprs()[1] ) );  // example.lizp:2:1

DESCRIPTION

This module provides a general-purpose S-expression reader for Lisp/Scheme-style source text. It only parses; evaluation is provided by lang/lisp/eval.

Parsed values use ordinary Zuzu values where that is unambiguous:

• proper lists become Array values;
• strings become String values;
• numbers become Number values;
• #t and #f become Boolean values;
• symbols become LispSymbol objects;
• dotted pairs become LispPair chains.
• vector literals become LispVector objects.
• character literals become LispChar objects.
• bytevector literals become LispByteVector objects.

Symbols are objects so callers can pass nested Zuzu arrays directly to the evaluator while keeping Zuzu strings available as Lisp string literals. Use sym(name) when building those arrays in ZuzuScript.

The reader supports line comments beginning with ;, POD blocks beginning with a column-one directive such as =head1 and ending at =cut, double-quoted strings with simple escapes, quote syntax ', quasiquote syntax `, unquote syntax ,, unquote-splicing syntax ,@, dotted pairs, vector syntax #(...), character syntax #\x, and bytevector syntax #u8(...).

parse_program and load_program keep source text, source name, and a source map. This is useful for tools that want diagnostics or editor integration.

EXPORTS

Functions

• parse_sexpr(String text)

  Parses text and returns one S-expression value. Throws if the input contains zero expressions, more than one expression, an unterminated string or list, an unexpected closing parenthesis, or an invalid dotted pair.

• parse_sexprs(String text)

  Parses text and returns an Array containing every S-expression in the input. Whitespace, line comments, and embedded POD blocks are skipped between expressions.

• parse_program(String text, String source_name?)

  Parses text and returns a LispProgram. source_name defaults to <string> and is used in source locations.

• load_sexprs(Path path)

  Reads UTF-8 text from a std/io Path and returns the same value as parse_sexprs.

• load_program(Path path)

  Reads UTF-8 text from a std/io Path and returns the same value as parse_program, using the path text as the source name.

• sym(String name)

  Returns the interned LispSymbol for name. This is the preferred way to build direct nested-array S-expressions:

    lisp_eval( [ sym("+"), 1, 2 ], env );

• is_symbol(value)

  Returns true when value is a LispSymbol, otherwise false.

Classes

• LispError

  Base exception type for Lisp parser and evaluator errors. It carries an optional location() value when a caller attaches one.

• LispSyntaxError

  Subclass of LispError reserved for syntax-level failures.

• LispRuntimeError

  Subclass of LispError used by the evaluator for Lisp-level runtime errors.

• LispSymbol

  Represents a Lisp symbol.

  • symbol.get_name()

    Returns the symbol name as a String.

  • symbol.to_String()

    Returns the symbol name for string coercion.

• LispPair

  Represents a dotted pair.

  • pair.get_car()

    Returns the pair head.

  • pair.get_cdr()

    Returns the pair tail.

• LispVector

  Represents a Lisp vector.

  • vector.get_values()

    Returns the underlying Array.

  • vector.get_values().length()

    Returns the number of values in the vector.

  • vector.ref(Number index)

    Returns the value at index.

  • vector.set_value(Number index, value)

    Sets and returns the value at index.

  • vector.to_Array()

    Returns a shallow copy of the vector values as an Array.

• LispChar

  Represents a Lisp character.

  • char.get_value()

    Returns the character as a one-character String.

• LispByteVector

  Represents a bytevector.

  • bytevector.get_values()

    Returns the underlying Array of byte values.

  • bytevector.get_values().length()

    Returns the number of bytes.

  • bytevector.ref(Number index)

    Returns the byte at index.

  • bytevector.set_value(Number index, Number value)

    Sets and returns the byte at index.

  • bytevector.to_Array()

    Returns a shallow copy of the byte values.

• LispEOF

  Represents the Lisp end-of-file object used by ports.

• LispSourceLocation

  Represents a source position.

  • location.get_source_name()

    Returns the source name.

  • location.get_index()

    Returns the zero-based character index.

  • location.get_line()

    Returns the one-based line number.

  • location.get_column()

    Returns the one-based column number.

  • location.to_String()

    Returns source:line:column.

• LispProgram

  Parsed source plus source metadata.

  • program.get_exprs()

    Returns the parsed top-level expressions.

  • program.get_source()

    Returns the original source text.

  • program.get_source_name()

    Returns the source name used while parsing.

  • program.get_source_map()

    Returns source-map entries. Each entry contains value and location.

  • program.location_for(value)

    Returns the first recorded LispSourceLocation for value, or null if no location is recorded.

• SExprReader

  Stateful reader used by the convenience functions. Most callers should use parse_sexpr, parse_sexprs, or parse_program.

  • reader.get_source_map()

    Returns source-map entries recorded by this reader.

  • reader.read_expr()

    Reads and returns one expression from the current reader position.

  • reader.read_all()

    Reads all remaining expressions and returns them as an Array.

  • reader.eof()

    Skips whitespace and comments, then returns whether the reader is at end of input.

COPYRIGHT AND LICENCE

lang/lisp/parser is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.