API reference¶

This chapter describes most of Hy's public-facing macros, functions, and classes. It refers to Python's own documentation when appropriate rather than recapitulating the details of Python semantics.

Core macros ¶

The following macros are automatically imported into all Hy modules as their base names, such that hy.core.macros.foo can be called as just foo. Macros that are also available as functions are described as functions under Python operators.

Fundamentals ¶

:warn-on-core-shadow: If true (the default), :hy:func:`defmacro` and :hy:func:`require` will raise a warning at compile-time if you define a macro with the same name as a core macro. Shadowing a core macro in this fashion is dangerous, because other macros may call your new macro when they meant to refer to the core macro.

Quoting ¶

Assignment, mutation, and annotation ¶

Subsetting ¶

Conditionals and basic loops ¶

Comprehensions ¶

Context managers and pattern-matching ¶

Exception-handling ¶

Functions ¶

Macros ¶

Classes ¶

Modules ¶

Miscellany ¶

Placeholder macros ¶

There are a few core macros that are unusual in that all they do, when expanded, is crash, regardless of their arguments:

else
except
except*
finally
unpack-mapping
unquote
unquote-splice

The purpose of these macros is merely to reserve their names. Each symbol is interpreted specially by one or more other core macros (e.g., else in while) and thus, in these contexts, any definition of these names as a function or macro would be ignored. If you really want to, you can override these names like any others, but beware that, for example, trying to call your new else inside while may not work.

Hy ¶

A few core functions, mostly related to the manipulation of Hy code, are available through the module hy.

Readers ¶

Hy's reader (i.e., parser) classes are most interesting to the user in the context of reader macros.

class hy.HyReader(*, use_current_readers=False)¶

A modular reader for Hy source. It inherits from hy.Reader.

When use_current_readers is true, initialize this reader with all reader macros from the calling module.

fill_pos(model, start)¶: Set position information for model. start should be a (line number, column number) tuple for the start position, whereas the end position is set to the current cursor position.

parse(stream, filename=None, skip_shebang=False)¶: Yield all models in stream. The parameters are understood as in :hy:func:`hy.read-many`.

parse_forms_until(closer)¶: Yield models until the character closer is seen. This method is useful for reading sequential constructs such as lists.

parse_one_form()¶: Parse the next form in the stream and return its model. Any preceding whitespace and comments are skipped over.

read_default(key)¶

Try to read an identifier. If the next character after that is ", then instead parse it as a string with the given prefix (e.g., r"...").

(This method is the default reader handler, for when nothing in the read table matches.)

class hy.Reader¶

An abstract base class for reading input character-by-character.

See hy.HyReader for an example of creating a reader class.

ends_ident¶

The set of characters that indicate the end of an identifier

Type:: set[str]

reader_table¶

A dictionary mapping a reader-macro key to its dispatch function

Type:: dict[str, Callable]

pos¶

A read-only (line, column) tuple indicating the current cursor position of the source being read

Type:: tuple[int, int]

chars(eof_ok=False)¶: Consume and yield characters of the stream. If eof_ok is false (the default) and the end of the stream is reached, raise hy.PrematureEndOfInput.

dispatch(tag)¶: Call the handler for the reader macro with key tag (a string). Return the model it produces, if any.

end_identifier(character)¶: A context manager to temporarily add a new character to the ends_ident set.

getc()¶: Consume one character from the stream and return it. This method does the bookkeeping for position data, so all character consumption should go through it.

getn(n)¶: Consume and return n characters.

peek_and_getc(target)¶: Peek at the next character and check if it's equal to target, only consuming it if it's equal. A bool is returned.

peekc()¶: Peek at the next character, returning it but not consuming it.

peeking(eof_ok=False)¶: As chars(), but without consuming any of the returned characters. This method is useful for looking several characters ahead.

read_ident(just_peeking=False)¶: Read characters until we hit something in ends_ident. The characters are consumed unless just_peeking is true.

saving_chars()¶: A context manager to save all read characters. The value is a list of characters, rather than a single string.

slurp_space()¶: Consume and return zero or more whitespace characters.

exception hy.PrematureEndOfInput(message, expression=None, filename=None, source=None, lineno=1, colno=1)¶: Raised when input ends unexpectedly during parsing.