New subcommand snapshot to save the state in which a command is run

.drom

@@ -5,7 +5,7 @@ version:0.9.0
 
 # hash of toml configuration files
 # used for generation of all files
-0b8b0a34a1a2cc1f1b27ccb09438599a:.
+7453fbe4cc9f9d6fd94e43d83fb6f16e:.
 # end context for .
 
 # begin context for .github/workflows/workflow.yml
@@ -80,7 +80,7 @@ c8281f46ba9a11d0b61bc8ef67eaa357:docs/style.css
 
 # begin context for dune-project
 # file dune-project
-ce7b96b842d3f265df300ce6c72e52d4:dune-project
+a56e5e78f9707d2e306293c9466e84b0:dune-project
 # end context for dune-project
 
 # begin context for opam/cobol_ast.opam
@@ -185,7 +185,7 @@ dcf0ebaa8b12787df9efcaa0ce8cbbe5:opam/package-json.opam
 
 # begin context for opam/superbol_free_lib.opam
 # file opam/superbol_free_lib.opam
-c86beae68d4d0173c716a8449fc2dfaf:opam/superbol_free_lib.opam
+e0cc097fe8a8d66f719468909a2ceaab:opam/superbol_free_lib.opam
 # end context for opam/superbol_free_lib.opam
 
 # begin context for opam/superbol_testutils.opam
@@ -400,7 +400,7 @@ bb6994bfe27f29a441abee11c82b032f:src/lsp/cobol_typeck/dune
 
 # begin context for src/lsp/superbol_free_lib/dune
 # file src/lsp/superbol_free_lib/dune
-562cdec92233a9d9156b6db06c636cde:src/lsp/superbol_free_lib/dune
+677e1d075fd0901268bc712c9af5325b:src/lsp/superbol_free_lib/dune
 # end context for src/lsp/superbol_free_lib/dune
 
 # begin context for src/lsp/superbol_free_lib/version.mlt

.gitignore

@@ -16,7 +16,7 @@ _build
 /_opam
 /_build
 .drom.config
-/_dist
+/dist
 /node_modules
 /yarn-error.log
 /yarn.lock
@@ -28,6 +28,5 @@ ATTIC
 *.vsix
 *.opam.locked
 /emacs/lsp-superbol-customs.el
-/_out
 
 

drom.toml

@@ -33,7 +33,7 @@ of the superbol-studio-oss OCaml project
 """
 
 [project]
-skip = ["@test", "@ocamlformat", "@ocp-indent", "README.md", "sphinx/about.rst", "LICENSE.md"]
+skip = ["@test", "@ocamlformat", "@ocp-indent", "README.md", "sphinx/about.rst", "LICENSE.md", "sphinx/index.rst"]
 
 # project-wide library dependencies (not for package-specific deps)
 [dependencies]

dune-project

@@ -205,6 +205,7 @@
    (vscode-json (= version))
    (ez_file ( >= 0.3 ))
    (ez_cmdliner (and (>= 0.3.0) (< 1.0.0)))
+   (ez_api ( >= 2.0 ))
    (cobol_typeck (= version))
    (cobol_parser (= version))
    (cobol_lsp (= version))

opam/superbol_free_lib.opam

@@ -51,6 +51,7 @@ depends: [
   "vscode-json" {= version}
   "ez_file" {>= "0.3"}
   "ez_cmdliner" {>= "0.3.0" & < "1.0.0"}
+  "ez_api" {>= "2.0"}
   "cobol_typeck" {= version}
   "cobol_parser" {= version}
   "cobol_lsp" {= version}

sphinx/commands.rst

@@ -16,12 +16,18 @@ Overview of sub-commands::
   indent range
     Indentation range
 
+  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
 
+  snapshot
+    Manage environment snapshots
+
   texi2rst
     build .texi documentation from gnucobol-docs
 
@@ -114,6 +120,41 @@ Overrides `format` from configuration file if present.
 * :code:`--strict`   Use the strict configuration
 
 
+main.exe json vscode
+~~~~~~~~~~~~~~~~~~~~~~
+
+parse VSODE JSON files or generate package.json
+
+
+
+**DESCRIPTION**
+
+
+
+
+**USAGE**
+::
+
+  main.exe json vscode FILES [OPTIONS]
+
+Where options are:
+
+
+* :code:`FILES`   JSON Files to parse
+
+* :code:`--gen FILE`   Generate FILE from current configuration
+
+* :code:`--grammar`   Parse files as syntaxes/*.json files
+
+* :code:`--language`   Parse files as language/configuration *.json files
+
+* :code:`--manifest`   Parse files as package.json files
+
+* :code:`--snippets`   Parse files as snippets/*.json files
+
+* :code:`--tasks`   Parse files as .vscode/tasks.json files
+
+
 main.exe lsp
 ~~~~~~~~~~~~~~
 
@@ -159,6 +200,8 @@ Where options are:
 
 * :code:`-I DIRECTORY`   Add DIRECTORY to library search path
 
+* :code:`--check`   If true, check the output (implies --parse)
+
 * :code:`--cobc`   Activate cobc specific features
 
 * :code:`--conf CONF_FILE`   Set the configuration file to be used
@@ -169,6 +212,8 @@ Where options are:
 
 * :code:`--output FILE` or :code:`-o FILE`   Output File (use '-' for stdout)
 
+* :code:`--parse`   If true, parse the generated cobol before printing
+
 * :code:`--recovery BOOL`   Enable/disable parser recovery after syntax errors (default: true)
 
 * :code:`--silence STRING`   Silence specific messages
@@ -179,6 +224,103 @@ Overrides `format` from configuration file if present.
 * :code:`--strict`   Use the strict configuration
 
 
+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:
+
+
+* :code:`ARGS`   Command line arguments
+
+* :code:`--env VAR=VALUE`   Set a variable in the environment
+
+* :code:`--load ID`   Load snapshot ID
+
+* :code:`--no-cd`   Do not change directory to run the command
+
+* :code:`--quit`   Do not run the command, just exit
+
+* :code:`--save ID`   Create snapshot ID from state
+
+
 main.exe texi2rst
 ~~~~~~~~~~~~~~~~~~~
 
@@ -201,4 +343,6 @@ Where options are:
 
 * :code:`FILE`   .texi file
 
+* :code:`-I DIR`   Add to lookup path for files
+
 * :code:`-o DIR`   Target directory for RST generation

sphinx/index.rst

@@ -13,6 +13,15 @@ Welcome to superbol-vscode-platform
    Home <https://ocamlpro.github.io/superbol-vscode-platform>
    about
    install
+   install-vscode
+   lsp
+   features
+   platform
+   tasks
+   settings
+   emacs
+   debug
+   commands
    API doc <https://ocamlpro.github.io/superbol-vscode-platform/doc>
    license