API

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.

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

The hy module is auto imported into every Hy module and provides convient access to the following methods

Reader Macros

Like regular macros, reader macros should return a Hy form that will then be passed to the compiler for execution. Reader macros access the Hy reader using the &reader name. It gives access to all of the text- and form-parsing logic that Hy uses to parse itself. See HyReader and its base class Reader for details regarding the available processing methods.

class hy.reader.hy_reader.HyReader

A modular reader for Hy source.

fill_pos(model, start)

Attach line/col information to a model.

Sets the end location of model to the current cursor position.

Parameters:

• model (hy.models.Object) – model to set line/col info for.

• start (tuple[int, int]) – (line, column) tuple indicating the start location to assign to model.

parse(stream, filename=None, skip_shebang=False)

Yields all hy.models.Object’s in source

Additionally exposes self as hy.&reader during read/compile time.

Parameters:

• source – Hy source to be parsed.

• filename (str | None) – Filename to use for error messages. If None then previously set filename is used.

• skip_shebang – Whether to detect a skip a shebang line at the start.

parse_forms_until(closer)

Yields hy.models.Object’s until character closer is seen.

Useful for reading a sequence such as s-exprs or lists.

parse_one_form()

Read from the stream until a form is parsed.

Guaranteed to return a model (i.e., skips over comments).

Returns:

hy.models.Object

read_default(key)

Default reader handler when nothing in the table matches.

Try to read an identifier. If there’s a double-quote immediately following, then instead parse it as a string with the given prefix (e.g., r”…”).

class hy.reader.reader.Reader

A reader base class for reading input character-by-character. Only for use as a base class; cannot be instantiated directly.

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

ends_ident

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 func

Type:

dict[str, Callable]

pos

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

Type:

tuple[int, int]

chars(eof_ok=False)

Iterator for the character stream.

Consumes characters as they are produced.

Parameters:

eof_ok (bool) – Whether or not it’s okay to hit the end of the file while consuming the iterator. Defaults to False

Yields:

str – The next character in source.

Raises:

PrematureEndOfInput – if eof_ok is False and the iterator hits the end of source

dispatch(tag)

Call the handler for the tag.

Parameters:

tag (str) – Reader macro dispatch key.

Returns:

Model returned by the reader macro defined for tag.

Return type:

hy.models.Object | None

end_identifier(character)

Temporarily add a new character to the ends_ident set.

getc()

Get one character from the stream, consuming it.

This function does the bookkeeping for position data, so it’s important that any character consumption go through this function.

Returns:

The character under the cursor at pos.

Return type:

str

getn(n)

Returns n characters.

peek_and_getc(target)

Peek one character and check if it’s equal to target.

Only consumes the peeked character if it is equal to target

Returns:

Whether or not the next character in the stream is equal to target.

Return type:

bool

peekc()

Peek at a character from the stream without consuming it.

Returns:

character at pos

Return type:

str

peeking(eof_ok=False)

Iterate over character stream without consuming any characters.

Useful for looking multiple characters ahead.

Parameters:

eof_ok (bool) – Whether or not it is okay to hit the end of the file while peeking. Defaults to False

Yields:

str – The next character in source.

Raises:

PrematureEndOfInput – if eof_ok is False and the iterator hits the end of source

read_ident(just_peeking=False)

Read characters until we hit something in ends_ident.

Parameters:

just_peeking – Whether or not to consume characters while peeking. Defaults to False.

Returns:

The identifier read.

Return type:

str

saving_chars()

Save all the characters read while in this block.

Useful for ‘=’ mode in f-strings.

Returns:

list[str]

slurp_space()

Returns and consumes 0 or more whitespace characters.

Python Operators

Reserved