Skip to content

API

Jump to bottom
Augusto Stoffel edited this page Jun 10, 2020 · 4 revisions

Overview

Besides the language server executable, Digestif provides an API in Lua. The main component is the Manuscript class, which represents a single TeX file, possibly linked to parent and included files. There is also a Cache class that helps manage the state of documents as they change. Here is a quick overview of how they work:

Manuscript = require "digestif.Manuscript"
Cache = require "digestif.Cache"

my_files = Cache {["foo.tex"] = "See \\ci"}
my_doc = Manuscript {
  filename = "foo.tex",
  format = "latex",
  files = my_files
}
items = my_doc:complete(#"See \\ci" + 1)

print(#items, items.prefix)
--> 3	ci

Above, we created a manuscript named foo.tex with content See \ci. In the constructor of the Manuscript class, the files field is a function that takes a file path as argument and returns the file contents; the Cache class is a convenient way to create such a function. Next, we asked for completions at the very end of the file. We found 3 candidates, corresponding to the common prefix ci. To further inspect the results, we can look at the text field of each completion candidate:

for i, item in ipairs(items) do
  print(i, item.text)
end
--> 1	circ
--> 2	circle
--> 3	cite

Each item has further properties, such as signature and docstring, as detailed below.

Now, suppose the user selected one of the completion options and the new content of the file is See \cite. Then we can use the Cache:put method to update the stored content of foo.tex and create a new manuscript object. Using again the Manuscript constructor would work fine in this case, but for large, multi-file documents, it's important to reuse as much of the previously calculated results as possible. For this, the Cache:manuscript method is provided. It takes a file path and a TeX format as arguments, and returns a Manuscript object. The code to update our document and get a docstring for the item at position 8 is as follows.

my_files:put("foo.tex", "See \\cite")
my_doc = my_files:manuscript("foo.tex", "latex")
help = my_doc:describe(8)

print(help.label, help.summary)
--> \cite[subcite]{keys}	Refer to a bibliography item.

Class digestif.Manuscript

All position arguments are measured in bytes, starting from 1.

Manuscript(arg)

Creates a new Manuscript object. arg is a table with the following fields:

  • filename: path to the file
  • format: the TeX format ("latex", "plain", "context" or "texinfo")
  • parent: a parent manuscript (optional)
  • files: a function that takes a path as argument and returns a string

If the files function returns two values, the manuscript will keep a reference to the second value. This can be used to control garbage collection.

Manuscript:complete(pos)

Computes possible completions at document position pos. The return value is a list of completion candidates, with the following additional fields:

  • pos: position where the match begins
  • prefix: the substring of the document source that matched
  • kind: one of "command", "environment", "key", "value", "label", "bibitem"

Each completion item is a table with the following fields:

  • text: the completion text; may not start with prefix
  • annotation: a short string suitable for display next to the candidate in a pop-up menu (optional)
  • summary: a short documentation string (optional)
  • snippet: a TextMate-style snippet (optional)

The completion candidate list is already suitably sorted. Exact matches are sorted alphabetically or, where applicable, by order in the document. Fuzzy matches, if enabled, come afterwards, sorted by score.

Manuscript:describe(pos)

Manuscript:find_references(pos)

Manuscript:find_definition(pos)

Manuscript:outline()

Class digestif.Cache

Cache(arg)

Creates a new cache object. The optional argument is a table of file paths and file contents, stored as with the put method.

Cache:put(path, str)

Stores the string str as the content of the file path.

Cache:__call(path)

Calling a cache object as a function returns the stored value for path. If no value has been stored, then the file is read from disk, if it exists, and its content is stored and returned. If the file does not exist on disk, returns nil.

Items stored with put are kept until overwritten or forget is called. Items read from disk are stored as weak references and may be garbage collected immediately. To avoid this, keep a reference to the second return value of this function (this is a token you shouldn't otherwise fiddle with).

Cache:forget(path)

Removes the stored value for path

Cache:manuscript(path, format, root_path)

Returns a manuscript object with source at path and TeX format format. The manuscript belongs to a tree of manuscript objects representing the document to which it belongs.

The optional root_path, if provided, specifies the root of the document. If omitted, the root is inferred from TeXShop-style magic comment at the beginning of the file.

This method uses memoization, so that it is efficient to make repeated calls to it.

Module digestif.config

config.data_dirs = {...}

A list of directories where data files are searched for.

config.extra_snippets = {...}

A table where keys are command names and values are snippet strings. These override the internally computed ones.

config.fuzzy_cite = true

If true, enable fuzzy matching for citations. Matches are done against the author, year and title.

config.fuzzy_ref = true

If true, enable fuzzy matching for labels. Matches are done against the text surrounding the label, starting at the command immediately preceding the \label command.

config.info_command = "info %q"

A command used to fetch info pages. This is passed to format with the info node as argument.

Clone this wiki locally