SuperBOL LSP Server

SuperBOL provides an LSP server for COBOL. Every dialect supported by superbol is supported by the LSP server.

The server operates on the notion of projects, that bundle COBOL source files within a root directory, along with a configuration.

Project layout

A project layout associates a configuration given in a file named superbol.toml that is located at the root of the project, with a set of files that contain COBOL source code. A typical structure for a project may look as follows:

project
├── superbol.toml
├── src
│  └── prog1.cob
│  └── prog2.cob
│  └── ...
└── COPY
   └── copy1.cpy
   └── copy2.cpy
   └── ...

When a user opens any file that contains COBOL source code, the LSP server looks for the closest parent directory dir that directly contains a configuration file superbol.toml, and sets dir as the root project directory for that file. If no configuration file is found, the project’s root is defined as the directory that directly contains the opened file.

Note

Note that files from distinct projects may be edited all at once via the same LSP server.

Project configuration

The superbol.toml at the root of a project is a TOML file with a [cobol] secton that defines the following configuration fields for the project:

  • dialect: Sets the dialect for your project. Case insensitive. Possible values are:

    • "default" (default if not provided)

    • "gnucobol"

    • "cobol85"

    • "cobol2002"

    • "cobol2014"

    • "acu"

    • "bs2000"

    • "gcos"

    • "ibm"

    • "microfocus" or "mf"

    • "mvs"

    • "realia"

    • "rm"

    • "xopen"

    Every dialect strings from "acu" to "rm" (included) may be suffixed with "-strict" to indicate a strict configuration for the dialect should be used: such a configuration restricts the set of reserved words and disables GnuCOBOL extensions to match the language expected by other compilers for the dialect.

  • source-format: Select a specific COBOL source format. Possible values are:

    • "Auto" (default)

    • "Free"

    • "Fixed"

    • "Variable"

    • "XOpen"

    • "xCard"

    • "CRT"

    • "Terminal"

    • "COBOLX"

  • copybook: This array is to be filled with all the directories where copybooks are located. It only contains the current working directory by default. Each element of the array must have a dir field. This field may contain the name of a directory that is either: 1. relative to the project root; or 2. relative to the directory that contains the COBOL source file that defines the compilation group (when the associated Boolean field file-relative holds).

Every value given as a string for a configuration field is case insensitive, except when it describes a file or directory name.

Note

The superbol-free project init command enables you to automatically create a superbol.toml file with the default configuration. You can append a directory argument to indicate where the file should be placed; otherwise, the file is created in the current working directory.

Example configuration

Consider the following project layout:

project
├── superbol.toml
├── GLOBAL_COPYBOOKS
│  └── global.cpy
└── src
   ├── prog1
   │  ├── LOCAL_COPYBOOKS
   │  │  └── local.cpy
   │  └── prog1.cob
   └── prog2
      ├── LOCAL_COPYBOOKS
      │  └── local.cpy
      └── prog2.cob

Then you can provide the following configuration file:

superbol.toml
[cobol]
dialect = "GCOS"
source-format = "COBOLX"

[[cobol.copybook]]
dir = "GLOBAL_COPYBOOKS"

[[cobol.copybook]]
dir = "LOCAL_COPYBOOKS"
file-relative = true

All COBOL code in this project will be considered in GCOS dialect and written in COBOLX source format.

In addition, the copybook global.cpy can be used by any source file from this project. Furthermore, a COPY "local.cpy" in prog1.cob will include the copybook src/prog1/LOCAL_COPYBOOKS/local.copy (and respectively for prog2.cob and src/prog2/LOCAL_COPYBOOKS/local.copy).

Server capabilities

This is a list the LSP server’s capabilities. To see how they are used in VSCode, you can check SuperBOL extension features.

Go to definition

The server handles the textDocument/definition request, and can find definition of any data item in your code.

Find references

The server can list all the references to a data item in your code with the textDocument/references request

Code formatting

The server provides a formatter both for the full file or for a selection range. This formatter handles the FIXED and FREE format.

Hover

The server provides a way to peek into copybooks via the textDocument/hover request (more hovering features to come)

Semantic tokens

The server can provide semantic tokens data via the textDocument/semanticTokens/full request.