Sub-commands and Arguments

Common arguments to all sub-commands:

  • --color WHEN Whether to color outputs: always, never, or auto (the default) to color those bound to a terminal. WHEN may also be a comma-separated list of stdout:WHEN or stderr:WHEN, to color the standard output or error alone. Overrides the environment variable SUPERBOL_COLOR, that accepts the same values

  • -q or --quiet Set verbosity level to 0

  • -v or --verbose Increase verbosity level

Overview of sub-commands:

cache analyze
  Analyze files, reusing and filling the cache of their project

cache status
  Report on the cache of a project

cache trim
  Reclaim entries a project's cache no longer needs

check syntax
  Check the syntax of a Cobol file

indent file
  Indentation

json vscode
  parse VSODE JSON files or generate package.json

lsp
  run LSP server

parallel
  Run a sub-command on batches of files, in parallel processes

project files
  List the source files of a project

sql preproc
  Preprocess SQL EXECs

main.exe cache analyze

Analyze files, reusing and filling the cache of their project

DESCRIPTION

Preprocess, parse and typecheck each FILE as the LSP server would, according to the configuration of the project it belongs to, and report diagnostics.

Analysis results are looked up in, or else stored into, the cache of that project, which is shared with the LSP server: a file analyzed by either is restored by the other, for as long as neither the file nor anything it depends upon (copybooks, project configuration) changes.

With –no-lsp-artifacts, what only the LSP server needs (e.g. semantic tokens, workspace symbols) is neither computed nor stored. The LSP server does not reuse analyses stored this way, whereas analyses it stored are reused all the same.

An LSP client such as Visual Studio Code may configure projects that have no configuration file through its settings: –client-settings gives those settings, and –storage-directory designates the caches of an LSP server started with that option, so that analyses are shared with that server.

Visual Studio Code decodes files according to its files.encoding setting before sending them to the server: analyses of files that are not plain UTF-8 are only shared with the server when –encoding gives that same encoding.

Options such as –dialect, –conf, –source-format, -I, –ext, -D, –recovery or –silence override the project configuration; analyses obtained with them are cached separately, and are not shared with the LSP server.

A file that cannot be analyzed (e.g. because it cannot be read) is reported, and the remaining files are analyzed all the same. The exit status is then at least 2; it is odd whenever some analyzed file holds errors, unless –no-error-status is given.

Files that appear to be copybooks are not analyzed. With –progress log-err, tell whether each analysis was found in the cache.

With –jobs N, files are split into batches (see –batch-size), each analyzed by a process of its own, with up to N processes running at once. The output of each process is shown as a whole when it ends, so diagnostics follow the order in which batches end rather than that of the given files. The exit status is computed over all of them. Builds of this program into JavaScript analyze files in turn instead.

USAGE

main.exe cache analyze FILE [OPTIONS]

Where options are:

  • FILE Cobol file to analyze

  • -D VAR=VAL Define a pre-processor variable VAR, with value VAL

  • -I DIR Add DIR to library search path

  • --batch-size K or -n K With –jobs, process files in batches of K, each in a process of its own (default: the size that splits files into as many batches as there are jobs, up to 25)

  • --client-settings JSON Configure projects that have no `superbol.toml’ file as an LSP server does when its client sends these settings of the `superbol.cobol’ section (e.g. `{“dialect”: “ibm”}’)

  • --conf CONF_FILE Set the configuration file to be used

  • --config-dir DIR Add DIR to config search path

  • --dialect DIALECT or --std DIALECT Set the dialect to bu used (overriden by –conf if used)

  • --encoding ENCODING Decode files as Visual Studio Code does with this value of its `files.encoding’ setting (e.g. `windows1252’, `cp850’). Files are read as they are by default, or (with a warning listing the supported encodings) if ENCODING is not supported

  • --ext EXT Add EXT as a filename extension for copybook resolution (default: cpy cbl cob)

  • --files-from LIST Also consider the files listed in file LIST, one per line, or on standard input if LIST is `-’; relative names are relative to the current directory. May be given several times

  • --free Shorthand for –source-format FREE

  • --jobs N or -j N Process files in up to N processes at once (default: 1)

  • --mf-comment Treat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)

  • --no-diagnostics Do not output the diagnostics of analyzed files (errors that prevent analyzing a file are still reported)

  • --no-error-status Exit with status 0 even when analyzed files hold errors (errors that prevent analyzing a file still make the program exit with a non-zero status)

  • --no-lsp-artifacts Leave out what only the LSP server needs (it does not reuse analyses stored this way)

  • --null or -0 Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)

  • --progress MODE Set how to display progress of the command.

MODE can be hide, force, log or log-err.

By default progress is displayed when stderr is a TTY.

  • --project-root DIR or --root DIR Set the root of the project (autodetected on a per-file basis otherwise)

  • --recovery BOOL Enable/disable parser recovery after syntax errors (default: true)

  • --silence STRING Silence specific messages

  • --source-format SOURCE_FORMAT Set the format of source code; allowed values are: { FIXED (the default), FREE}

Overrides format from configuration file if present.

  • --stdout Output errors/warnings to stdout

  • --storage-directory DIR Use the caches that an LSP server started with the same option uses

  • --walk-project Also consider every source file of the project (the one given with `–project-root’, or else the one of the current directory), as the LSP server does: according to the extensions that the platform and project configuration deem source files, and skipping hidden files, directories excluded by the configuration, and the working directory of the project

main.exe cache status

Report on the cache of a project

DESCRIPTION

Show where the cache of the project containing DIR lives, how much room it takes, and – with -l – what each entry holds and when it was last used.

The project containing DIR is the one whose root is the closest parent directory of DIR that holds a `superbol.toml’ file, or else DIR itself. –project-root designates a project by its root instead: Visual Studio Code puts every file of a workspace folder in the project of that folder. With –storage-directory, the cache is that of an LSP server started with the same option.

With –json, the totals are given as fields entries, values and disk_usage (in bytes), along with now (in seconds since the epoch); and with -l, field items lists every entry, with the date it was last_used, and the digest (value) and size (value_size) of the value it holds — values may be shared between entries. Field cache is null for a project that has no cache.

USAGE

main.exe cache status DIR [OPTIONS]

Where options are:

  • DIR Directory within the project (default: `.’)

  • --json Output a single JSON object, for use by other programs

  • --list-entries or -l List every entry, not just the totals

  • --project-root DIR or --root DIR Designate the project whose root is DIR, rather than the one the positional DIR belongs to

  • --storage-directory DIR Use the caches that an LSP server started with the same option uses

main.exe cache trim

Reclaim entries a project’s cache no longer needs

DESCRIPTION

Reclaim entries of the project containing DIR, along with every value they alone held.

–older-than removes those unused for that many days; –max-size removes the least recently used until the cache fits. Both may be given, and with neither nothing is reclaimed but the leftovers of instances that died mid-write. –older-than 0 empties the cache.

Nothing is reclaimed while another process is pruning the same cache.

The project containing DIR is the one whose root is the closest parent directory of DIR that holds a `superbol.toml’ file, or else DIR itself. –project-root designates a project by its root instead: Visual Studio Code puts every file of a workspace folder in the project of that folder. With –storage-directory, the cache is that of an LSP server started with the same option.

With –json, the number of entries reclaimed is given as field reclaimed, along with the totals that cache status –json gives.

USAGE

main.exe cache trim DIR [OPTIONS]

Where options are:

  • DIR Directory within the project (default: `.’)

  • --json Output a single JSON object, for use by other programs

  • --max-size SIZE Keep the cache under that size, reclaiming the entries least recently used. Accepts a suffix: 500M, 2G, 64k

  • --older-than DAYS Reclaim entries unused for that many days

  • --project-root DIR or --root DIR Designate the project whose root is DIR, rather than the one the positional DIR belongs to

  • --storage-directory DIR Use the caches that an LSP server started with the same option uses

main.exe check syntax

Check the syntax of a Cobol file

DESCRIPTION

Preprocess and parse each FILE with the options given on the command line only, and report diagnostics. Use superbol cache analyze to follow the configuration of each file’s project.

USAGE

main.exe check syntax FILE [OPTIONS]

Where options are:

  • FILE Cobol file to check

  • -D VAR=VAL Define a pre-processor variable VAR, with value VAL

  • -I DIR Add DIR to library search path

  • --conf CONF_FILE Set the configuration file to be used

  • --config-dir DIR Add DIR to config search path

  • --dialect DIALECT or --std DIALECT Set the dialect to bu used (overriden by –conf if used)

  • --ext EXT Add EXT as a filename extension for copybook resolution (default: cpy cbl cob)

  • --files-from LIST Also consider the files listed in file LIST, one per line, or on standard input if LIST is `-’; relative names are relative to the current directory. May be given several times

  • --free Shorthand for –source-format FREE

  • --mf-comment Treat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)

  • --null or -0 Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)

  • --progress MODE Set how to display progress of the command.

MODE can be hide, force, log or log-err.

By default progress is displayed when stderr is a TTY.

  • --recovery BOOL Enable/disable parser recovery after syntax errors (default: true)

  • --silence STRING Silence specific messages

  • --source-format SOURCE_FORMAT Set the format of source code; allowed values are: { FIXED (the default), FREE}

Overrides format from configuration file if present.

  • --stdout Output errors/warnings to stdout

main.exe indent file

Indentation

DESCRIPTION

USAGE

main.exe indent file FILES [OPTIONS]

Where options are:

  • FILES Cobol files to indent

  • -D VAR=VAL Define a pre-processor variable VAR, with value VAL

  • -I DIR Add DIR to library search path

  • --conf CONF_FILE Set the configuration file to be used

  • --config-dir DIR Add DIR to config search path

  • --dialect DIALECT or --std DIALECT Set the dialect to bu used (overriden by –conf if used)

  • --ext EXT Add EXT as a filename extension for copybook resolution (default: cpy cbl cob)

  • --free Shorthand for –source-format FREE

  • --gen-config Generate a config file .superbol-indent in this directory

  • --inplace Modify files in place

  • --intext For numeric, indentation size is relative to area A

  • --lines LINE-LINE Indent only lines between these lines

  • --mf-comment Treat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)

  • --numeric Output indentation size at the beginning of each line

  • --progress MODE Set how to display progress of the command.

MODE can be hide, force, log or log-err.

By default progress is displayed when stderr is a TTY.

  • --recovery BOOL Enable/disable parser recovery after syntax errors (default: true)

  • --silence STRING Silence specific messages

  • --source-format SOURCE_FORMAT Set the format of source code; allowed values are: { FIXED (the default), FREE}

Overrides format from configuration file if present.

  • --suffix EXT Set an extension for the file being generated

main.exe json vscode

parse VSODE JSON files or generate package.json

DESCRIPTION

USAGE

main.exe json vscode FILES [OPTIONS]

Where options are:

  • FILES JSON Files to parse

  • --gen FILE Generate FILE from current configuration

  • --grammar Parse files as syntaxes/*.json files

  • --language Parse files as language/configuration *.json files

  • --manifest Parse files as package.json files

  • --snippets Parse files as snippets/*.json files

  • --tasks Parse files as .vscode/tasks.json files

main.exe lsp

run LSP server

DESCRIPTION

Start a COBOL LSP server

USAGE

main.exe lsp [OPTIONS]

Where options are:

  • --cache-max-age DAYS Reclaim cache entries that have not been used for that many days. Kept indefinitely by default.

  • --cache-size-limit SIZE Keep each project’s cache under that size, reclaiming the entries least recently used whenever it is written out. Accepts a suffix: 500M, 2G, 64k. Unbounded by default.

  • --caching Enable caching (enabled by default)

  • --force-syntax-diagnostics Force reporting of syntax error and hint diagnostics for dialects other than COBOL85 (for which they are always enabled)

  • --no-caching Disable caching (enabled by default)

  • --storage-directory DIR Directory under which to store cache data — prevents the creation of a “_superbol” storage directory at the root of project trees.

main.exe parallel

Run a sub-command on batches of files, in parallel processes

SYNOPSIS

superbol parallel [-j N] [-n K] [–files-from LIST [-0]] – SUB-COMMAND [OPTION]… [– FILE…]

DESCRIPTION

Split the files into batches (see –batch-size), and run superbol SUB-COMMAND with its OPTIONs on each batch, in a process of its own, with up to N processes running at once (see –jobs). This is akin to xargs -P N -n K superbol SUB-COMMAND [OPTION]…, except that outputs of processes never interleave, and that the exit status is computed over all of them, as if SUB-COMMAND had been run on every file at once.

The first – ends the options of this command; files follow the second one, and are given along with those listed with –files-from. Without either, files are read from the standard input, one per line. Options of SUB-COMMAND that designate files, such as –files-from or –walk-project, are rejected: they would make each process consider every file they designate.

The output of each process is shown as a whole when it ends, so outputs follow the order in which batches end rather than that of the given files. Outputs are colored as those of this command, and laid out with the same margins.

With a single job, or in builds of this program into JavaScript, SUB-COMMAND is run on every file at once, within the same process.

EXAMPLES

superbol parallel -j 8 -- cache analyze --stdout -- *.cbl
find . -name '*.cbl' | superbol parallel -j 8 -- check syntax
superbol project files -0 | superbol parallel -j 8 -0 --files-from - -- sql preproc

USAGE

main.exe parallel SUB-COMMAND [OPTIONS]

Where options are:

  • SUB-COMMAND Sub-command to run, with its options, followed by – and the files to give it

  • --batch-size K or -n K With –jobs, process files in batches of K, each in a process of its own (default: the size that splits files into as many batches as there are jobs, up to 25)

  • --files-from LIST Also consider the files listed in file LIST, one per line, or on standard input if LIST is `-’; relative names are relative to the current directory. May be given several times

  • --jobs N or -j N Process files in up to N processes at once (default: 1)

  • --null or -0 Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)

  • --progress MODE Set how to display progress of the command.

MODE can be hide, force, log or log-err.

By default progress is displayed when stderr is a TTY.

main.exe project files

List the source files of a project

DESCRIPTION

List the files that the LSP server deems source files of the project (the one given with –project-root, or else the one of the current directory), one per line: those with extensions that the platform and project configuration deem source files, skipping hidden files, directories excluded by the configuration, and the working directory of the project.

This is the list of files other commands consider with –walk-project.

EXAMPLES

superbol project files -0 | superbol parallel -j 8 -0 --files-from - -- sql preproc

USAGE

main.exe project files [OPTIONS]

Where options are:

  • -D VAR=VAL Define a pre-processor variable VAR, with value VAL

  • -I DIR Add DIR to library search path

  • --conf CONF_FILE Set the configuration file to be used

  • --config-dir DIR Add DIR to config search path

  • --dialect DIALECT or --std DIALECT Set the dialect to bu used (overriden by –conf if used)

  • --encoding ENCODING Decode files as Visual Studio Code does with this value of its `files.encoding’ setting (e.g. `windows1252’, `cp850’). Files are read as they are by default, or (with a warning listing the supported encodings) if ENCODING is not supported

  • --ext EXT Add EXT as a filename extension for copybook resolution (default: cpy cbl cob)

  • --free Shorthand for –source-format FREE

  • --mf-comment Treat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)

  • --null or -0 Separate file names with NUL characters instead of newlines (for `–null’ options of other commands)

  • --progress MODE Set how to display progress of the command.

MODE can be hide, force, log or log-err.

By default progress is displayed when stderr is a TTY.

  • --project-root DIR or --root DIR Set the root of the project (autodetected on a per-file basis otherwise)

  • --recovery BOOL Enable/disable parser recovery after syntax errors (default: true)

  • --silence STRING Silence specific messages

  • --source-format SOURCE_FORMAT Set the format of source code; allowed values are: { FIXED (the default), FREE}

Overrides format from configuration file if present.

main.exe sql preproc

Preprocess SQL EXECs

USAGE

main.exe sql preproc FILE [OPTIONS]

Where options are:

  • FILE COBOL files to preproc

  • -D VAR=VAL Define a pre-processor variable VAR, with value VAL

  • -I DIR Add DIR to library search path

  • --conf CONF_FILE Set the configuration file to be used

  • --config-dir DIR Add DIR to config search path

  • --copybooks Preprocess copybooks also (without REPLACING)

  • --dialect DIALECT or --std DIALECT Set the dialect to bu used (overriden by –conf if used)

  • --encoding ENCODING Decode files as Visual Studio Code does with this value of its `files.encoding’ setting (e.g. `windows1252’, `cp850’). Files are read as they are by default, or (with a warning listing the supported encodings) if ENCODING is not supported

  • --ext EXT Add EXT as a filename extension for copybook resolution (default: cpy cbl cob)

  • --files-from LIST Also consider the files listed in file LIST, one per line, or on standard input if LIST is `-’; relative names are relative to the current directory. May be given several times

  • --free Shorthand for –source-format FREE

  • --mf-comment Treat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)

  • --null or -0 Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)

  • --progress MODE Set how to display progress of the command.

MODE can be hide, force, log or log-err.

By default progress is displayed when stderr is a TTY.

  • --project-root DIR or --root DIR Set the root of the project (autodetected on a per-file basis otherwise)

  • --recovery BOOL Enable/disable parser recovery after syntax errors (default: true)

  • --silence STRING Silence specific messages

  • --source-format SOURCE_FORMAT Set the format of source code; allowed values are: { FIXED (the default), FREE}

Overrides format from configuration file if present.

  • --test-ext Set file extension to .cbsql

  • --walk-project Also consider every source file of the project (the one given with `–project-root’, or else the one of the current directory), as the LSP server does: according to the extensions that the platform and project configuration deem source files, and skipping hidden files, directories excluded by the configuration, and the working directory of the project