Cyan API Documentation

Some wrappers/conveniences around working with ansi escape codes. For example getting the length of a string that contains escape codes shouldnt include them

`ColorString:len(): integer`

Get the length of a given ColorString, not counting any escape sequences.

Note that ColorString:len() >= ColorString:tostring():len()

`ColorString:surround(col: {integer})`

surrounds a string with a color

`ColorString:to_raw(): string`

Converts a Colorstring to a regular string, stripping any ANSI escapes

`ColorString:tostring(): string`

Converts a Colorstring to a regular string with the correct ANSI escapes

`type ColorString`

record ColorString
   content: {string | {integer}}
   len: function(ColorString): integer
   tostring: function(ColorString): string

   metamethod __len: function(ColorString): integer
   metamethod __concat: function(ColorString | string, ColorString | string): ColorString
end

The main object that this library consumes and produces. It basically implements the 'string' interface and can be used wherever a string is.

Colors are described as arrays of numbers that directly correspond to ANSI escape sequences

`colorstring.highlight(hl: {integer}, str: string): ColorString`

Create a Colorstring by surrounding a string with the given ANSI color and an ANSI reset

`colorstring.new(...: string | {integer}): ColorString`

The Colorstring constructor

`colorstring.rgb_bg(r: integer, g: integer, b: integer): {integer, integer, integer, integer, integer}`

The ansi escape for an arbitrary RGB background color

`colorstring.rgb_fg(r: integer, g: integer, b: integer): {integer, integer, integer, integer, integer}`

The ansi escape for an arbitrary RGB foreground color

cyan.command

The common interface for commands to implement

`command.get(name: string): Command`

Get a command that was created with command.new

Works whether or not command.register_all was called

`command.merge_args_into_config(cfg: config.Config, args: Args)`

Merge the relevant entries of the provided command arguments into the provided config table

`command.new(cmd: Command)`

Create a new command

This is stored in an internal cache and will do nothing unless command.register_all is called afterwards

`command.register_all(p: argparse.Parser)`

Install all commands created with command.new into the given parser

cyan.config

Config loading API

`config.find(): fs.Path`

Find config.filename in the current or parent directories

`config.is_config(c: any): Config, {string}, {string}`

Check if c conforms to the Config type and return any errors and warnings generated from checking

`config.load(): Config, {string}, {string}`

Try to load tlconfig.lua in the current directory

cyan.fs.path

Object oriented lexical path management

`Path.eq(a: Path | string, b: Path | string, use_os_sep: boolean): boolean`

Check if two paths are equal

This function is used for the __eq metamethod with use_os_sep as false

`Path:ancestors(): function(): Path`

Iterate over the leading folders in a path

ex: path.new("foo/bar/baz/bat"):ancestors() will construct Path objects from "foo", "foo/bar", "foo/bar/baz"

`Path:append(other: string | Path)`

Mutate the given Path by appending another path to it

Traversals in the other path will be normalized

 local p = path.new "foo/bar"
 p:append "../baz"
 assert(p == path.new "foo/baz")

`Path:is_absolute(): boolean`

Returns whether the path is absolute

On windows, checks for paths like "C:\...", elsewhere looks for "/..."

`Path:is_directory(): boolean`

Get whether the "mode" attribute of the given path is set to "directory"

`Path:is_file(): boolean`

Get whether the "mode" attribute of the given path is set to "file"

`Path:is_in(dirname: string | Path, use_os_sep: boolean): boolean`

returns true if the path is inside the given directory

If relative and absolute paths are mixed, the relative path is assumed to be in the current working directory (as determined by lfs.currentdir())

If dirname is a string, a path will be constructed using path.new with use_os_sep

`Path:match(patt: string): boolean`

See if the given path matches the pattern

Path separators in patterns are always represented with '/'.

* characters represent any number of non-path-separator characters

**/ represent any number of directories

`Path:match_any(patts: {string}): integer, string`

See if the given path matches any of the given patterns

`Path:mk_parent_dirs(): boolean, string`

Attempt to create the leading directories of a given path

`Path:mkdir(): boolean, string`

Attempt to create a directory at the given path, creating the parent directories if needed. Can be seen as an equivalent to mkdir -p

`Path:mod_time(): integer`

Get the "modification" attribute of a file

`Path:normalize()`

Modify path in place to remove any traversals that it can

 local p = path.new "foo/bar/../baz"
 p:normalize()
 assert(p == path.new "foo/baz")

if a traversal can't be removed it will remain

 local p = path.new "../baz"
 p:normalize()
 assert(p == path.new "../baz")

`Path:prepend(other: string | Path)`

Mutate the given Path by prepending another path to it

`Path:relative_to(other: Path): Path`

Expresses a path in terms of another path. If any relative paths are given, they are treated as though they are in the current directory

for example: path.new("/foo/bar/baz"):relative_to(path.new("/foo/bat")) == path.new "../bar/baz"

`Path:remove_leading(p: string | Path)`

Mutate the given path by removing the leading parts from the given path

Will error if you attempt to mix absolute and non-absolute paths

`Path:to_absolute()`

Modify a path in place to become an absolute path

When the path is already absolute, does nothing

Otherwise, prepends the current directory

`Path:to_real_path(): string`

Convert a Path to a string describing a real path

`Path:tostring(): string`

Convert a path to a string. Always uses '/' as a path separator. Intended for displaying purposes. For an actual path in the filesystem, use Path:to_real_path()

Used for the __tostring metamethod

`type Path`

record Path
   {string}

   metamethod __concat: function(Path | string, Path | string): Path
   metamethod __eq: function(Path | string, Path | string): boolean
end

The main path object. Basically just an array of strings with some methods and metamethods to interact with other paths

`path.ensure(s: string | Path, use_os_sep: boolean): Path`

Ensures s is a Path.

If s is a string, parse it into a path otherwise return s unmodified

`path.new(s: string, use_os_sep: boolean): Path`

The Path constructor

By default uses '/' as a path separator

cyan.fs

Filesystem and path management

`fs.chdir(p: string | Path): boolean, string`

Change the current directory to p

`fs.copy(source: string | Path, dest: string | Path): boolean, string`

Copy a file

uses fs.read internally to get and cache the contents of source

`fs.cwd(): Path`

Get the current working directory as an fs.Path

`fs.dir(dir: string | Path, include_dotfiles: boolean): function(): Path`

Iterate over the given directory, returning fs.Path objects

By default, will not include paths that start with '.'

`fs.extension_split(p: Path | string, ndots: integer): string, string`

Split a path on its extension. Forces the extension to be lowercase.

the ndots argument lets you specify the upper limit of how many dots the extension can have

ex:

 fs.extension_split("foo.d.tl") => "foo.d", ".tl"
 fs.extension_split("foo.d.tl", 2) => "foo", ".d.tl"
 fs.extension_split("foo.D.TL", 2) => "foo", ".d.tl"

`fs.get_line(p: string, n: integer): string, string`

Gets line n of a file.

if the file is less than n lines, returns nil

if there was an error opening the file, returns nil, err

Uses fs.read() internally, which caches reads

`fs.path_concat(a: string, b: string): string`

Concatenate two strings using the os path separator

`fs.read(p: string): string, string`

Open a file, read it, close the file, return the contents or nil and an error if it couldn't be opened

Additionally caches results so multiple locations can read the same file for minimal cost. There is currently no way to clear out this cache.

`fs.scan_dir(dir: string | Path, include: {string}, exclude: {string}, include_directories: boolean): function(): Path`

Recursively iterate over the files in a directory, following the provided include and exclude patterns

For information on path patterns, see the Path:match() method

`fs.search_parent_dirs(start_path: string | Path, fname: string): Path`

Search for a file in the parent directories of the given path. Returns the path of the file found.

e.g. if file.txt is in /foo/bar, then fs.search_parent_dirs("/foo/bar/baz", "file.txt") == path.new "/foo/bar/file.txt"

cyan.graph

A utility for building directed acyclic graphs of Teal source files

This is the main driver behind the build command

`Dag:find(fstr: string | fs.Path): Node`

Find a node in the graph with the given path name

`Dag:insert_file(fstr: string | fs.Path, in_dir: string | fs.Path): boolean, {string}`

Inserts a file and its dependencies into a graph

Ignores absolute paths and non .tl or .lua files

If in_dir is provided, dependencies of the given file will not be added to the graph unless they are inside of the given dir

Returns false if inserting the file introduced a circular dependency along with a list of the filenames in the cycle

`Dag:mark_each(predicate: function(fs.Path): boolean)`

For each node in the graph, if predicate returns true for that input path, the node is marked for compilation, and that node's children are marked for type checking

`Dag:marked_nodes(): function(): Node`

Iterate over every node that has been marked, no matter what the mark is

`Dag:nodes(): function(): Node`

Iterate over nodes in order of dependents

If two nodes have the same number of dependent nodes, the order of iteration between those two nodes is not guaranteed

`graph.scan_dir(dir: string | fs.Path, include: {string}, exclude: {string}): Dag, {string}`

Recursively scan a directory (using fs.scan_dir) and build up a graph, respecting the given include and exclude patterns

Returns nil if a circular dependency was found, along with a list of the filenames in the cycle

cyan.interaction

Module for handling when input from the user is needed

`interaction.yes_no_prompt( prompt: string, logger: log.Logger, default: boolean, affirm: {string}, deny: {string} ): boolean`

Ask the user to affirm or deny a given prompt. The user input will be compared against the given affirm and deny lists (case-insensitive), with defaults used if - they are not provided.

The given logger will be used to print the prompt, and log.info if none is provided.

cyan.log

Console logging utils, not to be confused with log files

Each logger object has the same __call signature of function(...: any), and by default the following are provided:

Name	Stream	Description
`info`	stdout	General info, should be seen as the default, silenced by --quiet
`extra`	stdout	Extra info that isn't strictly necessary, enabled via -v extra, silenced by --quiet
`warn`	stderr	Used to display warnings, silenced by --quiet
`err`	stderr	Used to display errors
`debug`	stderr	Used for debugging, uses the inspect module (if it is found) to print its arguments, enabled by -v debug

You may notice that these are nicely padded and after the first line the prefix is replaced by a '...'. Another function is provided, create_logger,

 create_logger: function(
    stream: FILE,
    verbosity_threshold: Verbosity,
    prefix: string | ColorString,
    cont: string | ColorString,
    inspector: function(any): string
 ): Logger

to automatically generate formatted output. cont defaults to "..." and inspector defaults to tostring. Prefixes will be padded to 10 characters wide by default, so your logging may look off from the default if your prefix is longer.

Additionally, loggers will try to detect whether or not to display colors. This is only handled with the ColorString type to avoid the many pitfalls of trying to parse ANSI escape sequences. If a regular string contains any escape sequences or an inspector produces them (outside of a ColorString) it will not be handled.

`Logger:cont(...: any)`

Log only using the continuation prefix.

`Logger:cont_nonl(...: any)`

Log only using the continuation prefix, but don't put a newline at the end.

`Logger:format(fmt: string, ...: any)`

Call string.format with the given arguments and log that.

`Logger:format_nonl(fmt: string, ...: any)`

Call string.format with the given arguments and log that, without a new line.

`Logger:nonl(...: any)`

Same as calling the logger, but don't put a newline at the end

`Logger:should_log(): boolean`

Returns whether the current verbosity is less than or equal to this loggers verbosity threshold.

`type Logger`

record Logger
   stream: FILE
   verbosity_threshold: Verbosity
   prefix: string | cs.ColorString
   continuation: string | cs.ColorString
   inspector: function(any): string

   metamethod __call: function(...: any)
end

The data needed for a logger to do its job.

`type Verbosity`

enum Verbosity
   "quiet"
   "normal"
   "extra"
   "debug"
end

The thresholds for loggers to actually write their output

`create_logger( stream: FILE, verbosity_threshold: Verbosity, prefix: string | cs.ColorString, cont: string | cs.ColorString, inspector: function(any): string ): Logger`

Creates a Logger as described above

`log.set_prefix_padding(padding: integer)`

Globally set the padding of the prefixes of loggers.

`log.set_verbosity(level: Verbosity)`

Globally set the verbosity of the logging module.

cyan.meta

Meta information about Cyan itself

cyan.sandbox

Super simplistic sandboxing In the future maybe could be integrated with some very simple debugging utilities for now, we just offer the convenience of exiting gracefully if someone puts while true do end in their config for some reason

cyan.script

The script loading api

`script.disable()`

Make everything in this library a no-op, there is currently no way to re-enable this

`script.emit_hook(name: string, ...: any): boolean, string`

Iterates through each loaded script and runs any with the given hook, logging each script that it ran, and stopping early if any error

`script.emitter(name: string, ...: any): function(): fs.Path, boolean, string`

Emit a hook to load and run all registered scripts that run on the given hook.

This function will assert that ensure_loaded_for_command was called before.

Returns an iterator that will run the next script when called and returns the path to the script, whether the script was loaded and ran with no errors, and an error message if it didn't

`script.ensure_loaded_for_command(name: string): boolean, string | tl.Result`

Attempts to load each script that the given command may need

`script.register(path: string, command_name: string, hooks: string | {string})`

Registers a file path as a lua/teal script to execute for the given hook(s) when script.emit_hook is called

This is called by the cli driver to register the scripts found in the config file with the relevant hooks

Note: this function does not attempt to actually load the file. Scripts are loaded all at once via ensure_loaded_for_command

cyan.tlcommon

Common things needed by most commands in addition to wrappers around the tl api, since it isn't super stable

`type ParseResult`

record ParseResult
   tks: {Token}
   ast: Node
   reqs: {string}
   errs: {tl.Error}
end

The result from parsing source code including the tokens, ast, calls to require, and errors

returns the new string and the number of characters replaced

Cyan API Documentation

Table of Contents