Formats Jai source. On success result is newly allocated (free it with free); on failure
it is empty and error (temporary storage) says why, with a line:column: prefix when it
points at the input: text that does not lex, unbalanced brackets, or the internal token check.
macOSLinuxWindowswasm
#import "Extensions/Jai_Format";
A source formatter for Jai (indentation, spacing, brace placement, blank lines).
Pure text in, text out: no file access (a front end passes a file reader to
format_find_config), so it runs the same natively, under jaic -interp and in the browser
playground. jaifmt/ is the command-line front end. See docs/tools/jaifmt.md.
#import "File";
text := "main :: () {}";
config, ok, error := parse_config(read_entire_file("jacket.toml"));
formatted, formatted_ok, format_error := format_source(text, config);This one is only checked to compile, not run.
Show moreShow less
Formatting never changes the token stream: the result is lexed again and compared with the
input, and on any difference format_source fails instead of returning text.
Procedures#
General#
Parses the [format] section of jacket.toml text (see the docs for the keys). Other tables are
skipped; without a [format] section the result is the default config. Bad values are errors,
reported as line N: ...; unknown keys are dropped and listed in unknown_keys.
format_apply_settingsince 0.29.0
Sets one setting from key=value, the value written as in the TOML file (4, true,
"preserve"): how a caller that already resolved the settings passes them on. Unlike the file
parser, a key the formatter does not have is an error.
format_unknown_setting_notesince 0.24.0
(key: string, file: string) -> string
The warning for an entry of config.unknown_keys found in the file file, with a suggestion
when a known key is close.
(before: string, after: string) -> (ok: bool, why: string)
Whether before and after are the same program as far as the compiler can tell: the same
tokens, comments and the line breaks and adjacency the parser depends on. format_source
already checks its own output with this.
Is path ignored by config.ignore? Globs are relative to config.root: * and ? stay
within a path component, ** crosses components, and a matched directory covers its contents.
(pattern: string, text: string) -> bool
format_find_configsince 0.30.0
(directory: string, read: Format_File_Reader, stop := "") -> (config: Format_Config, file: string, ok: bool, error: string)
The settings for files in directory, from the nearest jacket.toml at or above it (up to
stop), with read supplying file contents; see find_config in project.jai.
format_parent_directorysince 0.30.0
(path: string) -> string
a/b/c -> a/b; /a -> /; a -> "".
(text: string, max_width: int) -> int
Lines in text longer than max_width code points.
Project#
find_configsince 0.30.0
(directory: string, read: Format_File_Reader, stop := "") -> (config: Format_Config, file: string, ok: bool, error: string)
The settings for files in directory: the [format] of the nearest jacket.toml in it or one
of its parents, up to and including stop ("" to go to the top), else the defaults. file is
the jacket.toml that was used ("" for the defaults); config.root is its directory. When the
file cannot be parsed, ok is false and error says why (line N: ...).
parent_directory_ofsince 0.30.0
(path: string) -> string
a/b/c -> a/b; /a -> /; a -> "".
Types#
Brace_Styleenum
:: enum
Format_Configstruct
:: struct
:: #type (path: string) -> text: string, ok: bool
Reads the file at path for format_find_config: its text, and whether it could be read.
Constants#
JACKET_CONFIG_FILE_NAMEsince 0.20.0
:: "jacket.toml"
The config file the command-line tool looks for, upward from each file (its [format] section).