Sub-commands and Arguments
Common arguments to all sub-commands:
-q
or--quiet
Set verbosity level to 0-v
or--verbose
Increase verbosity level
Overview of sub-commands:
check syntax
Check the syntax of a Cobol file
ebcdic translate
Convert to or from EBCDIC
env
Generate commands to set environment variables to use the specified switch
indent file
Indentation
json vscode
parse VSODE JSON files or generate package.json
lsp
run LSP server
pp
Preprocess a list of COBOL files, generating a preprocessed file with extension .i for each of them
project config
Print current project configuration in TOML format
project init
Project initialization
snapshot
Manage environment snapshots
switch
Print current switch
switch add
Add a directory as a switch
switch build
Configure, build, install GnuCOBOL and add a switch
switch config
Change the current config
switch env
Generate commands to set environment variables to use the specified switch
switch import
Import existing GnuCOBOL installations as switches
switch list
List known switches
switch set
Set the current default switch
texi2rst
build .texi documentation from gnucobol-docs
util detect cycle
Detect a cycle of lines in a file
util wc
Stats on file of lines (without taking UTF8 chars into account)
main.exe check syntax
Check the syntax of a Cobol file
DESCRIPTION
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--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 cbx)--free
Shorthand for –source-format FREE--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 ebcdic translate
Convert to or from EBCDIC
DESCRIPTION
This command translates to or from EBCDIC and ASCII.
USAGE
main.exe ebcdic translate EBCDIC-FILE [OPTIONS]
Where options are:
EBCDIC-FILE
File in EBCDIC format (source or target)--colseq FILE
Collating sequence file to read from GnuCOBOL--from-ascii ASCII-FILE
File in ASCII format to translate--to-ascii ASCII-FILE
File in ASCII format to generate
main.exe env
Generate commands to set environment variables to use the specified switch
DESCRIPTION
This command generates a list of command to set environment variables for an existing switch.
It is usually used as:
# eval $(superbol env)
# cobc --version
The –switch SWITCH option can be used to choose a different switch from the default one. SWITCH should match a sub-string of a switch name. –last can be used to select the most recent switch.
The –global option can be used to generate a file $HOME/.config/superbol/env that can be loaded from shell init scripts, using a symlink to point PATH and LD_LIBRARY_PATH to the current switch at any time. Changing the current switch will then automatically redirect cobc to that new switch.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe env SWITCH [OPTIONS]
Where options are:
SWITCH
Switch to use, instead of current--global
Use global configuration for default switch--last
Use the latest imported switch
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--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 cbx)--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--numeric
Output indentation size at the beginning of each line--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:
--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 pp
Preprocess a list of COBOL files, generating a preprocessed file with extension .i for each of them
DESCRIPTION
USAGE
main.exe pp FILE [OPTIONS]
Where options are:
FILE
Cobol file to preprocess-D VAR=VAL
Define a pre-processor variable VAR, with value VAL-I DIR
Add DIR to library search path--check
If true, check the output (implies –parse)--cobc
Activate cobc specific features--conf CONF_FILE
Set the configuration file to be used--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 cbx)--free
Shorthand for –source-format FREE--output FILE
or-o FILE
Output File (use ‘-’ for stdout)--parse
If true, parse the generated cobol before printing--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 project config
Print current project configuration in TOML format
DESCRIPTION
This command prints the current project configuration.
USAGE
main.exe project config DIR [OPTIONS]
Where options are:
DIR
Project directory
main.exe project init
Project initialization
DESCRIPTION
This command initializes a default project in a given directory (or the current directory if not provided).
USAGE
main.exe project init DIR [OPTIONS]
Where options are:
DIR
Project directory
main.exe snapshot
Manage environment snapshots
DESCRIPTION
This command can be used to snapshot the environment when a command is called, typically in a test script, to be able to run this command in the same environment from outside the script.
A snapshot typically contains:
cmd
The command to run with its arguments
pwd
The directory where the command should be run
env
The environment variables for the command
Snapshots are stored in $HOME/.config/superbol/snapshots.
SNAPSHOT CREATION
To snapshot a command, use:
# mname tname --save SNAP_ID -- cmd args
The previous command will create a snapshot SNAP_ID, and then run the command cmd args.
You can use –quit if you don’t want to run the command at all (the command will exit with status 2)
SNAPSHOT USAGE
To run a command in a previously created snapshot, use:
# mname tname --load SNAP_ID -- cmd args
The previous command will load the snapshot SNAP_ID, go to its directory, set the environment and then run the command cmd args.
If cmd args is empty, then the snapshot command is run.
The argument –no-cd can be used to run the command in the current directory.
The argument –env VAR=VALUE can be used to add an extra variable to the environment, after the one set by the snapshot.
If a cmd args is provided, the following special items are substituted:
__
is replaced by all the arguments (including the command) from the snapshot
_0
is replaced by the command from the snapshot
_1
is replaced by all the arguments (excluding the commnad) from the snapshot
For example:
# mname tname --load ID -- gdb _0 --args __
will run the command inside gdb with its arguments as provided by the snapshot.
USAGE
main.exe snapshot ARGS [OPTIONS]
Where options are:
ARGS
Command line arguments--env VAR=VALUE
Set a variable in the environment--load ID
Load snapshot ID--no-cd
Do not change directory to run the command--quit
Do not run the command, just exit--save ID
Create snapshot ID from state
main.exe switch
Print current switch
DESCRIPTION
This command prints the current default switch.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch [OPTIONS]
Where options are:
main.exe switch add
Add a directory as a switch
DESCRIPTION
This command adds a new known switch.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch add DIR [OPTIONS]
Where options are:
DIR
Directory to add--no-set
Do not set this directory as the current one--switch SWITCH
Name of switch to add
main.exe switch build
Configure, build, install GnuCOBOL and add a switch
DESCRIPTION
This command will build and install GnuCOBOL and add the corresponding switch. If DIR is specified, the installation directory will be created inside, otherwise the dir user option will be used. The name of the directory and the switch names are generated automatically from the GIT configuration. If –switch SWITCH is provided, it will be used for the switch name. The –sudo option will decide if installation should be performed with sudo. If the installation is successful, the switch is created and automatically set as the default switch, unless –no-set is specified.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch build DIR [OPTIONS]
Where options are:
DIR
Directory where GnuCOBOL should be installed--branch BRANCH
Branch name to use instead of git branch (the auto-detected name from git will be 3.x-$DATE-$COMMIT)--no-set
Do not set this directory as the current one--sudo
Use sudo for ‘make install’--switch SWITCH
Name of switch to add
main.exe switch config
Change the current config
DESCRIPTION
This command sets the current default switch.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch config [OPTIONS]
Where options are:
--compiler-coverage BOOL
Set compiler coverage--set-last
Use the latest imported switch--set-switch SWITCH
Switch to use
main.exe switch env
Generate commands to set environment variables to use the specified switch
DESCRIPTION
This command generates a list of command to set environment variables for an existing switch.
It is usually used as:
# eval $(superbol env)
# cobc --version
The –switch SWITCH option can be used to choose a different switch from the default one. SWITCH should match a sub-string of a switch name. –last can be used to select the most recent switch.
The –global option can be used to generate a file $HOME/.config/superbol/env that can be loaded from shell init scripts, using a symlink to point PATH and LD_LIBRARY_PATH to the current switch at any time. Changing the current switch will then automatically redirect cobc to that new switch.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch env SWITCH [OPTIONS]
Where options are:
SWITCH
Switch to use, instead of current--global
Use global configuration for default switch--last
Use the latest imported switch
main.exe switch import
Import existing GnuCOBOL installations as switches
DESCRIPTION
This command will scan the directories, looking for gnucobol-* folders with GnuCOBOL installed, and add them as switches. With no argument, it scans the default installation directory.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch import DIRS [OPTIONS]
Where options are:
DIRS
Directories to scan--clear
Clear the list before importing--no-set
Do not set the last imported directory as the current one
main.exe switch list
List known switches
DESCRIPTION
This command list existing switches.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch list [OPTIONS]
Where options are:
main.exe switch set
Set the current default switch
DESCRIPTION
This command sets the current default switch.
ABOUT SWITCHES
Switches are used to easily handle multiple GnuCOBOL installations. The section [switches] in the user configuration file $HOME/.config/superbol/config.toml contains several variables:
‘dir’
The directory where installations should be performed, and switches imported from.
‘current’
The current switch name to use by default
‘list’
The list of known switches, with the corresponding installation directory
‘num’
A counter used to name switches
Switches can be created, imported and used using the following commands:
superbol env [SWITCH] [–last] [–global] Output a list of shell commands to set the environment variables to use a specific switch
superbol import [DIRS] [–clear] [–no-set] Scan directories to detect GnuCOBOL installations, and created associated switches
superbol add DIR [–switch SWITCH] [–no-set] Add a specific GnuCOBOL installation directory as a switch
superbol build [DIR] [–sudo] [–switch SWITCH] [–no-set] From inside GnuCOBOL sources, configure, build and install and add the corresponding switch
superbol list List known switches
superbol set [SWITCH] [–last] Set the current default switch
USAGE
main.exe switch set SWITCH [OPTIONS]
Where options are:
SWITCH
Switch to use--last
Use the latest imported switch
main.exe texi2rst
build .texi documentation from gnucobol-docs
DESCRIPTION
Build .texi documentation from gnucobol-docs.
USAGE
main.exe texi2rst FILE [OPTIONS]
Where options are:
FILE
.texi file-I DIR
Add to lookup path for files-o DIR
Target directory for RST generation
main.exe util detect cycle
Detect a cycle of lines in a file
DESCRIPTION
This command will take a file of lines and detect cycles in the lines, and simplify them.
ABOUT UTILS
This is a list of small sub-commands that may be useful from time to time.
USAGE
main.exe util detect cycle FILES [OPTIONS]
Where options are:
FILES
Files to unrec
main.exe util wc
Stats on file of lines (without taking UTF8 chars into account)
DESCRIPTION
This command will print different statistics on a file of lines. Contrarily to wc, it will not take into account UTF8 chars for the max line length.
ABOUT UTILS
This is a list of small sub-commands that may be useful from time to time.
USAGE
main.exe util wc FILES [OPTIONS]
Where options are:
FILES
Files to wc