Sub-commands and Arguments
Common arguments to all sub-commands:
--color WHENWhether 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-qor--quietSet verbosity level to 0-vor--verboseIncrease 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:
FILECobol file to analyze-D VAR=VALDefine a pre-processor variable VAR, with value VAL-I DIRAdd DIR to library search path--batch-size Kor-n KWith –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 JSONConfigure 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_FILESet the configuration file to be used--config-dir DIRAdd DIR to config search path--dialect DIALECTor--std DIALECTSet the dialect to bu used (overriden by –conf if used)--encoding ENCODINGDecode 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 EXTAdd EXT as a filename extension for copybook resolution (default: cpy cbl cob)--files-from LISTAlso 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--freeShorthand for –source-format FREE--jobs Nor-j NProcess files in up to N processes at once (default: 1)--mf-commentTreat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)--no-diagnosticsDo not output the diagnostics of analyzed files (errors that prevent analyzing a file are still reported)--no-error-statusExit 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-artifactsLeave out what only the LSP server needs (it does not reuse analyses stored this way)--nullor-0Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)--progress MODESet 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 DIRor--root DIRSet the root of the project (autodetected on a per-file basis otherwise)--recovery BOOLEnable/disable parser recovery after syntax errors (default: true)--silence STRINGSilence specific messages--source-format SOURCE_FORMATSet the format of source code; allowed values are: { FIXED (the default), FREE}
Overrides format from configuration file if present.
--stdoutOutput errors/warnings to stdout--storage-directory DIRUse the caches that an LSP server started with the same option uses--walk-projectAlso 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:
DIRDirectory within the project (default: `.’)--jsonOutput a single JSON object, for use by other programs--list-entriesor-lList every entry, not just the totals--project-root DIRor--root DIRDesignate the project whose root is DIR, rather than the one the positional DIR belongs to--storage-directory DIRUse 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:
DIRDirectory within the project (default: `.’)--jsonOutput a single JSON object, for use by other programs--max-size SIZEKeep the cache under that size, reclaiming the entries least recently used. Accepts a suffix: 500M, 2G, 64k--older-than DAYSReclaim entries unused for that many days--project-root DIRor--root DIRDesignate the project whose root is DIR, rather than the one the positional DIR belongs to--storage-directory DIRUse 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:
FILECobol file to check-D VAR=VALDefine a pre-processor variable VAR, with value VAL-I DIRAdd DIR to library search path--conf CONF_FILESet the configuration file to be used--config-dir DIRAdd DIR to config search path--dialect DIALECTor--std DIALECTSet the dialect to bu used (overriden by –conf if used)--ext EXTAdd EXT as a filename extension for copybook resolution (default: cpy cbl cob)--files-from LISTAlso 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--freeShorthand for –source-format FREE--mf-commentTreat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)--nullor-0Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)--progress MODESet 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 BOOLEnable/disable parser recovery after syntax errors (default: true)--silence STRINGSilence specific messages--source-format SOURCE_FORMATSet the format of source code; allowed values are: { FIXED (the default), FREE}
Overrides format from configuration file if present.
--stdoutOutput errors/warnings to stdout
main.exe indent file
Indentation
DESCRIPTION
USAGE
main.exe indent file FILES [OPTIONS]
Where options are:
FILESCobol files to indent-D VAR=VALDefine a pre-processor variable VAR, with value VAL-I DIRAdd DIR to library search path--conf CONF_FILESet the configuration file to be used--config-dir DIRAdd DIR to config search path--dialect DIALECTor--std DIALECTSet the dialect to bu used (overriden by –conf if used)--ext EXTAdd EXT as a filename extension for copybook resolution (default: cpy cbl cob)--freeShorthand for –source-format FREE--gen-configGenerate a config file .superbol-indent in this directory--inplaceModify files in place--intextFor numeric, indentation size is relative to area A--lines LINE-LINEIndent only lines between these lines--mf-commentTreat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)--numericOutput indentation size at the beginning of each line--progress MODESet 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 BOOLEnable/disable parser recovery after syntax errors (default: true)--silence STRINGSilence specific messages--source-format SOURCE_FORMATSet the format of source code; allowed values are: { FIXED (the default), FREE}
Overrides format from configuration file if present.
--suffix EXTSet 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:
FILESJSON Files to parse--gen FILEGenerate FILE from current configuration--grammarParse files as syntaxes/*.json files--languageParse files as language/configuration *.json files--manifestParse files as package.json files--snippetsParse files as snippets/*.json files--tasksParse 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 DAYSReclaim cache entries that have not been used for that many days. Kept indefinitely by default.--cache-size-limit SIZEKeep 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.--cachingEnable caching (enabled by default)--force-syntax-diagnosticsForce reporting of syntax error and hint diagnostics for dialects other than COBOL85 (for which they are always enabled)--no-cachingDisable caching (enabled by default)--storage-directory DIRDirectory 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-COMMANDSub-command to run, with its options, followed by – and the files to give it--batch-size Kor-n KWith –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 LISTAlso 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 Nor-j NProcess files in up to N processes at once (default: 1)--nullor-0Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)--progress MODESet 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=VALDefine a pre-processor variable VAR, with value VAL-I DIRAdd DIR to library search path--conf CONF_FILESet the configuration file to be used--config-dir DIRAdd DIR to config search path--dialect DIALECTor--std DIALECTSet the dialect to bu used (overriden by –conf if used)--encoding ENCODINGDecode 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 EXTAdd EXT as a filename extension for copybook resolution (default: cpy cbl cob)--freeShorthand for –source-format FREE--mf-commentTreat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)--nullor-0Separate file names with NUL characters instead of newlines (for `–null’ options of other commands)--progress MODESet 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 DIRor--root DIRSet the root of the project (autodetected on a per-file basis otherwise)--recovery BOOLEnable/disable parser recovery after syntax errors (default: true)--silence STRINGSilence specific messages--source-format SOURCE_FORMATSet 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:
FILECOBOL files to preproc-D VAR=VALDefine a pre-processor variable VAR, with value VAL-I DIRAdd DIR to library search path--conf CONF_FILESet the configuration file to be used--config-dir DIRAdd DIR to config search path--copybooksPreprocess copybooks also (without REPLACING)--dialect DIALECTor--std DIALECTSet the dialect to bu used (overriden by –conf if used)--encoding ENCODINGDecode 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 EXTAdd EXT as a filename extension for copybook resolution (default: cpy cbl cob)--files-from LISTAlso 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--freeShorthand for –source-format FREE--mf-commentTreat lines with an asterisk (*) in the first column as comments in FIXED, COBOL85, and VARIABLE source formats (like GnuCOBOL’s -fmfcomment)--nullor-0Names in lists given with `–files-from’ are separated by NUL characters instead of newlines (as output by `find -print0’)--progress MODESet 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 DIRor--root DIRSet the root of the project (autodetected on a per-file basis otherwise)--recovery BOOLEnable/disable parser recovery after syntax errors (default: true)--silence STRINGSilence specific messages--source-format SOURCE_FORMATSet the format of source code; allowed values are: { FIXED (the default), FREE}
Overrides format from configuration file if present.
--test-extSet file extension to .cbsql--walk-projectAlso 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