hissp.reader module

The Lissp language reader and associated helper functions.

Compiles Lissp files to Python files when run as the main module.

The reader is organized as a lexer and parser. The parser is extensible with Lissp reader macros. The lexer is not extensible, and doesn’t do much more than pull tokens from a relatively simple regex and track its position for error messages.

hissp.reader.ENTUPLE = ('lambda', (':', ':*', 'xAUTO0_'), 'xAUTO0_')

Used by the template macro to make tuples.

To avoid creating a dependency on Hissp, by default, templates spell out the entuple implementation every time, but you can override this by setting some other value here.

hissp.reader.DROP = <object object>

The sentinel value returned by the discard macro _#, which the reader skips over when parsing. Reader macros can have read-time side effects with no Hissp output by returning this.

exception hissp.reader.SoftSyntaxError

Bases: SyntaxError

A syntax error that could be corrected with more lines of input.

When the REPL encounters this when attempting to evaluate a form, it will ask for more lines, rather than aborting with an error.

class hissp.reader.Lexer(code: str, file: str = '<?>')

Bases: Iterator

The tokenizer for the Lissp language.

Most of the actual tokenizing is done by the regex. The Lexer adds some position tracking to that to help with error messages.

position(pos: int) → Tuple[str, int, int, str]

Compute the filename, lineno, offset and text for a SyntaxError, using the current character offset in code.

hissp.reader.gensym_counter(count=[31])

Call to increment the gensym counter, and return the new count. Used by the gensym reader macro $# to ensure symbols are unique.

class hissp.reader.Lissp(qualname='__main__', ns=None, verbose=False, evaluate=False, filename='<?>')

Bases: object

The parser for the Lissp language.

Wraps around a Hissp compiler instance. Parses Lissp tokens into Hissp syntax trees.

property ns

The wrapped Compiler’s ns.

reinit()

Reset position, nesting depth, and gensym stack.

position()

Get the filename, lineno, offset and text for a SyntaxError, from the Lexer given to parse.

parse(tokens: hissp.reader.Lexer) → Iterator

Build Hissp forms from a Lexer.

parse_macro(tag: str, form)

Apply a reader macro to a form.

static escape(atom)

Process the backslashes in a token.

template(form)

Process form as template.

qualify(symbol: str, invocation=False) → str

Qualify symbol based on current context.

reads(code: str) → Iterable

Read Hissp forms from code string.

compile(code: str) → str

Read Lissp code and pass it on to the Hissp compiler.

gensym(form: str)

Generate a symbol unique to the current template.

gensym_context()

Start a new gensym context for the current template.

unquote_context()

Start a new unquote context for the current template.

hissp.reader.is_string(form)

Determines if form could have been read from a Lissp string literal.

It’s not enough to check if the form has a string type. Several token types such as control words, symbols, and Python injections, read in as strings. Macros may need to distinguish these cases.

hissp.reader.transpile(package: Optional[Union[str, module]], *modules: Union[str, pathlib.PurePath])

Compiles the named modules to Python files. If the package is None or “”, it uses the current working directory without using a package. Lissp files must know their package at compile time to resolve imports correctly.

hissp.reader.transpile_module(package: Union[str, module], resource: Union[str, pathlib.PurePath], out: Union[None, str, bytes, pathlib.Path] = None)

Transpile a single submodule in a package.

hissp.reader.main()

Calls transpile with arguments from sys.argv.