mike-lischke / antlr-format Goto Github PK

npmjs.org has an antlr-format-cli: entry: https://www.npmjs.com/package/antlr-format-cli

This webpage displays the current version of 1.2.4. However, when I run the tool antlr-format --version from the command line, the tool outputs "1.0.1".

The package.json for the cache, c:\Users\Kenne\AppData\Roaming\npm\node_modules\antlr-format-cli\package.json, contains the correct version:

{
    "name": "antlr-format-cli",
    "version": "1.2.4",
    "description": "A cli wrapper for the antlr-format package",
    "author": "Mike Lischke",
...

I am positive that I am running the correct version of the tool:

$ node /c/Users/Kenne/AppData/Roaming/npm/node_modules/antlr-format-cli/dist/antlr-format.cjs --version
antlr-format 1.0.1
04/13-17:01:18 ~/issues/g4-4047/sql/tsql
$

Rather than hardwire the version in the source code, I suggest it read the package.json for the version of the tool. In addition, I can't tell what the version of the package antlr-format itself may be. I also suggest printing this out as well.

It can be useful in CI/CD. Currently if I run --help, there is no such option

$ antlr-format -h
Usage: antlr-format [options] <file1, pattern2, ...>

Arguments:
  file1, pattern2,             A list of files or glob patterns for multiple files.

Options:
  -a, --add-options [boolean]  Insert the used ANTLR grammar formatting options to the grammar file, if it contains no options. (default: true)
  -c, --config <path>          Path to a JSON file containing the formatting options to use.
  -s, --silent                 Suppress all output except errors.
  -v, --verbose                Print additional information.
  -V, --version                output the version number
  -h, --help                   display help for command

Example of such option in prettier:
https://github.com/prettier/prettier/blob/main/docs/cli.md#--check

I'm fairly certain I messed up something when installed antlr-format and -cli.

When I execute it all I get is the following stream of output. Does this look familiar? Does anything jump out at you as the possible cause?

bill

$ antlr-format --help
/usr/local/lib/node_modules/antlr-format-cli/dist/antlr-format.cjs:12

• specify the name in Command constructor or using .name());return t=t||{},t.isDefault&&(this._defaultCommandName=e._name),(t.noHelp||t.hidden)&&(e._hidden=!0),this._registerCommand(e),e.parent=this,e._checkForBrokenPassThrough(),this}createArgument(e,t){return new lS(e,t)}argument(e,t,n,s){let i=this.createArgument(e,t);return typeof n=="function"?i.default(s).argParser(n):i.default(n),this.addArgument(i),this}arguments(e){return e.trim().split(/ +/).forEach(t=>{this.argument(t)}),this}addArgument(e){let t=this.registeredArguments.slice(-1)[0];if(t&&t.variadic)throw new Error(only the last argument can be variadic '${t.name()}');if(e.required&&e.defaultValue!==void 0&&e.parseArg===void 0)throw new Error(a default value for a required argument is never used: '${e.name()}');return this.registeredArguments.push(e),this}helpCommand(e,t){if(typeof e=="boolean")return this._addImplicitHelpCommand=e,this;e=e??"help [command]";let[,n,s]=e.match(/([^ ]+) *(.*)/),i=t??"display help for command",a=this.createCommand(n);return a.helpOption(!1),s&&a.arguments(s),i&&a.description(i),this._addImplicitHelpCommand=!0,this._helpCommand=a,this}addHelpCommand(e,t){return typeof e!="object"?(this.helpCommand(e,t),this):(this._addImplicitHelpCommand=!0,this._helpCommand=e,this)}_getHelpCommand(){return this._addImplicitHelpCommand??(this.commands.length&&!this._actionHandler&&!this._findCommand("help"))?(this._helpCommand===void 0&&this.helpCommand(void 0,void 0),this._helpCommand):null}hook(e,t){let n=["preSubcommand","preAction","postAction"];if(!n.includes(e))throw new Error(Unexpected value for event passed to hook : '${e}'.
  ^

SyntaxError: Unexpected token '?'
at wrapSafe (internal/modules/cjs/loader.js:915:16)
at Module._compile (internal/modules/cjs/loader.js:963:27)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1027:10)
at Module.load (internal/modules/cjs/loader.js:863:32)
at Function.Module._load (internal/modules/cjs/loader.js:708:14)
at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:60:12)
at internal/main/run_main_module.js:17:47
$

Hi,

Sometimes we could need to disable some formating rule in order to keep a human readable form
exemple :

    | CREATE or_replace? SECURE? FUNCTION object_name LR_BRACKET ( arg_decl (COMMA  arg_decl)* )? RR_BRACKET
        RETURNS ( data_type | TABLE LR_BRACKET (col_decl (COMMA col_decl)* )? RR_BRACKET )
        null_not_null?
        (CALLED ON NULL_ INPUT | RETURNS NULL_ ON NULL_ INPUT | STRICT)?
        (VOLATILE | IMMUTABLE)?
        MEMOIZABLE?
        comment_clause?
        AS function_definition

is more readable than the reformated :

    | CREATE or_replace? SECURE? FUNCTION object_name LR_BRACKET (arg_decl (COMMA arg_decl)*)? RR_BRACKET RETURNS (
        data_type
        | TABLE LR_BRACKET (col_decl (COMMA col_decl)*)? RR_BRACKET
    ) null_not_null? (CALLED ON NULL_ INPUT | RETURNS NULL_ ON NULL_ INPUT | STRICT)? (
        VOLATILE
        | IMMUTABLE
    )? MEMOIZABLE? comment_clause? AS function_definition

Is there a way to disable/ignore formatting rule for small part of grammar ?

Add a new option that allows to specify the line break style to be used (\n˙, ˙\n\r or default for current OS).

Note: since all whitespaces are generated (not taken over from the original file), this will automatically fix all non-matching line breaks.

The antlr-format tool has a bug in reaching a fixed point (i.e., if I take version "before" which is outputed by the tool and rerun the tool on it, the tool should return exactly the same file). In addition it removed a comment that should not have been removed. It's essential that the antlr-format tool outputs a format that reliably follows the coding standard.

Here is a grammar that takes five applications of antlr-format to get to a fixed point PlSqlLexer.g4.txt. You will also need a file for the antlr-format options. repo_coding_style.json

The script I can use to check this is here:

#

rm -rf foo
mkdir foo
pushd foo
cp ../PlSqlLexer.g4.txt PlSqlLexer.g4
i=1
while :
do
	echo Iteration $i
	cp PlSqlLexer.g4 PlSqlLexer.g4.before
	cp PlSqlLexer.g4 PlSqlLexer.g4.after
	dos2unix *.g4
	antlr-format -c ../repo_coding_style.json PlSqlLexer.g4.after 2>&1 1> /dev/null
	dos2unix *.g4
	diff PlSqlLexer.g4.before PlSqlLexer.g4.after
	if [ $? -ne 0 ]
	then
		echo No fixed point yet.
	else
		echo Fixed point achieved.
		break
	fi
	cp PlSqlLexer.g4.after PlSqlLexer.g4
	i=`expr $i + 1`
done

Note, the script includes a call to dos2unix because antlr-format outputs raw '\n's regardless of the host operating system. (On Windows, the newline is '\n\r'.)

The first concern is that there are several comments removed in the START_CMD rule depending on the iteration of antlr-format.

The second concern is whether there are grammars that may not ever converge to a fixed point.

Thank you for this tool. The tool requires the -p option, and there can only be one -p option value. I'm confused as to why. Why isn't a list of file names as args to the tool supported? E.g., antlr-format f1.g4 f2.g4 f3.g4 ....). Most shells already provide glob expansion, and Gnu Bash can support globstar expansion with env adjustments. So, antlr-format *.g4 would be expanded as antlr-format f1.g4 f2.g4 f3.g4 .....

Note, in the readme, you don't single quote the arg to the -p option. For Bash and Powershell, the default is to do glob pattern matching unless you set your environment carefully to not do that. So, it may be confusing to some.

I tried this out on a few different environments. See below. Note, globstar pattern expansion in the tool does not work for Windows.

Linux

The tool fine on Linux, e.g.:

ken@DESKTOP-DL44R7B:~/grammars-v4/abb$ ls
Generated-Java  abbLexer.g4  abbParser.g4  desc.xml  examples  pom.xml  readme.txt
ken@DESKTOP-DL44R7B:~/grammars-v4/abb$ antlr-format -p '*.g4'

antlr-format, processing options...

formatting 2 file(s)...

done [82 ms]

ken@DESKTOP-DL44R7B:~/grammars-v4/abb$

But, Bash does glob expansion. So, this does not work:

ken@DESKTOP-DL44R7B:~/grammars-v4/abb$ ls
Generated-Java  abbLexer.g4  abbParser.g4  desc.xml  examples  pom.xml  readme.txt
ken@DESKTOP-DL44R7B:~/grammars-v4/abb$ antlr-format -p *.g4

antlr-format, processing options...

formatting 1 file(s)...

done [70 ms]

ken@DESKTOP-DL44R7B:~/grammars-v4/abb$

The second file is not formatted, and there is no warning.

Windows

Over on Windows, the pattern expansion does not work.

11/26-15:51:13 ~/issues/g4-3833/abb
$ antlr-format -p '*.g4'
No grammar file found using this pattern: C:\msys64\home\Kenne\issues\g4-3833\abb\*.g4.

11/26-15:51:29 ~/issues/g4-3833/abb
$ antlr-format -p './*.g4'
No grammar file found using this pattern: C:\msys64\home\Kenne\issues\g4-3833\abb\*.g4.

11/26-15:51:36 ~/issues/g4-3833/abb

Note, I am using Msys2 Bash ("Cygwin"-based shell), so single quotes are necessary to avoid Bash glob expansion.

NB: The tool does work on Windows if I skip glob patterns, and simply use the file name explicitly. The tool works fine for either relative or absolute paths, and using either the forward slash or backward slash directory separators.

11/26-16:05:51 ~/issues/g4-3833/abb
$ antlr-format -p abbLexer.g4

antlr-format, processing options...

formatting 1 file(s)...

done [52 ms]

11/26-16:06:01 ~/issues/g4-3833/abb
$ antlr-format -p abbParser.g4

antlr-format, processing options...

formatting 1 file(s)...

done [44 ms]

11/26-16:06:11 ~/issues/g4-3833/abb

Multiple files with one call to antlr-format

If I try to give two files, only the first is formatted.

11/26-15:52:47 ~/issues/g4-3833/abb
$ antlr-format -p abbLexer.g4 abbParser.g4

antlr-format, processing options...

formatting 1 file(s)...

done [52 ms]

11/26-15:53:29 ~/issues/g4-3833/abb
$

If I try to give the -p option twice, the second -p option is ignored without warning.

11/26-15:53:29 ~/issues/g4-3833/abb
$ antlr-format -p abbLexer.g4 -p abbParser.g4

antlr-format, processing options...

formatting 1 file(s)...

done [44 ms]

11/26-15:54:21 ~/issues/g4-3833/abb
$

It does not matter if I use cmd.exe either.

Powershell on Linux

Powershell operates similarly to Bash. Glob patterns are expanded prior to exec() of the tool. So, one must single quote arguments when calling the tool.

What is the purpose of -p option? Doesn't every shell offer some equivalent to "find"?

Why is the -p option provided? Bash supports glob patterns, and globstar patterns when the env is set for it. (NB: expansion of the glob or globstar patter cannot work if multiple files are discovered, because the -p option only takes one parameter.)

I can also do a find and call the tool for each file:

$ find . -name '*.g4' -exec antlr-format -p '{}' ';'

antlr-format, processing options...

formatting 1 file(s)...

done [51 ms]


antlr-format, processing options...

formatting 1 file(s)...

done [45 ms]

11/26-15:52:47 ~/issues/g4-3833/a