# 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

### 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, bracketed_templates=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.

## Python operators