# AUX module – handling .aux files

Functions for reading and handling .aux files

LaTeX generates `.aux` files which tie together the collection of bibliographic citations obtained from the source file, the bibliographic data base(s) which are to be used (the `.bib` files) and the citation style.

The `.aux` file is in TeX syntax, with only the `\citation`, `\bibdata` and `\bibstyle` commands recognised:

If `beastie` is asked to process a `.aux` file as input, then it will assume that the citation style is a standard `.bst` file, and handle it on that basis. To use a separate `.scm` file, the extension must be included explicitly.

You can either parse the aux file directly, with `parse-aux-file`, or use `call-with-aux-file` to parse it and invoke a processor in one step.

## Functions

Index:

- call-with-aux-file
- parse-aux-file
- parse-aux-string

### call-with-aux-file

`call-with-aux-file : string? ((listof symbol?) (listof string?) string? [:parse-aux-file fn] -> unspecified`: In `(call-with-aux-file fn processor)`, the aux-file `fn` is opened, parsed, and the contents processed with the function `processor`, called with the results from `parse-aux-file`.

The given processor function is called with three arguments:

- citations: a list of citation keys, as symbols, or the special symbol `'all`
- bibdata: a list of paths to the .bib files to read from, as indicated by `\bibdata`
- bibstyle: a style file indicated by the `\bibstyle` command

If the `fn` is passed as `#f`, then parse stdin.

If the aux file can't be opened, or it can't be parsed, then return `#f`.

For a suitable processor, see the function `process-bibs/bst` in the `bst` module.

If the keyword argument `:parse-aux-file` is present, then that function is used, instead of the default `parse-aux-file` function, to parse the file. A suitable alternative function might be, for example,

    (define (parse-aux-file/nobst fn)
      (let ((result (parse-aux-file fn)))
        (list (car result) (cadr result) #f)))

will have the same effect as `parse-aux-file`, but discarding the style-file found there.

### parse-aux-file

`parse-aux-file : string? -> (list (listof symbol?) (listof string?) string?` : In `(parse-aux-file filename)` parse the aux file `filename`, and return relevant contents.

We return a list `(list-of-symbols list-of-strings string)` which are in order the list of citations, or `'all` if we see `\citation{*}`; the list of .bib databases to consult; and the style-file to use. The databases and style-file elements are returned as `#f` if they're absent.

We recognise the following commands in the `.aux` file:

- `\citation{foo}` : cite an object with BibTeX key `foo`.
- `\citation{*}` : include all of the entries in the database.
- `\bibdata{bib}` : names the BibTeX database to consult; this command can appear more than once, the argument can be a single file or a list separated by commas, and the `.bib` extension is optional.
- `\bibstyle{plain}` : the style file to be used.

If the kpathsea library was available when `beastie` was built (it usually is) then it will be used to look up the values of the `\bibdata` and `\bibstyle` commands.

If the `fn` is passed as `#f`, then parse stdin.

Returns `#f` if the file can't be parsed as an aux-file.

### parse-aux-string

Like parse-aux-file, mostly for debugging.

Norman
2026 August 02