picky about the command line interface

[42sol-eu]

Dear Ned, I really love the idea and the concept - all the time and work you put into cog. After I heard about it on Python-Bytes I was planning to use and distribute it through different parts of my professional life and personal projects.

What I saw that made me itch to support you was the command line interface.

I really think there is a great standard with the short / long option style like -c / --crc If you then give it a broad help keyword - including those /? from windows the command line interface is really a self-documenting thing. At the moment you mainly use short options.

Would you be interested in a suggestion from me in form of a pull request? Would it be fine with you to add click as a dependency? (this is nice but not necessary)

Sincerly Felix

[nedbat]

Felix, thanks for enthusiasm!

Cog remains a back-burner project for me, though I still use it when needed. I'm not opposed to adding long-option support, or a click dependency. Honestly a big problem with cog is that the coding style is really archaic. When I go into the code to make a change, I am tempted to change everything, which I have to resist!

[42sol-eu]

which I have to resist!

Because of your time?

I would love to support you here. I really love the concept and want to use it heavily with our coding projects. I even have a small idea around a Qt and QtCreator project, where I need cog-superpowers.

I will come back to you with a suggestion...

[42sol-eu]

suggestion:

cog [OPTIONS] [INFILE | @FILELIST] ...

INFILE is the name of an input file, '-' will read from stdin.
FILELIST is the name of a text file containing file names or
    other @FILELISTs.

OPTIONS:
    -c / --crc            Checksum the output to protect it against accidental change.
    -d / --delete         Delete the generator code from the output file.
    -D name=val /   
    -DEFINE name=val      Define a global string available to your generator code.
    -e / --error          Warn if a file has no cog code in it.
    -I PATH /
    --INCLUDE PATH        Add PATH to the list of directories for data files and modules.
    -n ENCODING /
    --encoding ENCODING   Use ENCODING when reading and writing files.
    -o OUTNAME  /
    -out OUTNAME          Write the output to OUTNAME.
    -p PROLOGUE /
    -prepend PROLOGUE     Prepend the generator source with PROLOGUE. Useful to insert an
                          import line. Example: -p "import math"
    -r / --replace        Replace the input file with the output.
    -s STRING /
    --suffix STRING       Suffix all generated output lines with STRING.
    -U / --use-lf         Write the output with Unix newlines (only LF line-endings).
    -w CMD /
    --make-writeable CMD  Use CMD if the output file needs to be made writable.
                          A %s in the CMD will be filled with the filename.
    -x / --excise         Excise all the generated output without running the generators.
    -z / --end-eof        The end-output marker can be omitted, and is assumed at eof.
    -v / --version        Print the version of cog and exit.
    --verbosity=VERBOSITY
                Control the amount of output. 2 (the default) lists all files,
                1 lists only changed files, 0 lists no files.
    --markers='START END END-OUTPUT'
                The patterns surrounding cog inline instructions. Should
                include three values separated by spaces, the start, end,
                and end-output markers. Defaults to '[[[cog ]]] [[[end]]]'.
    -h / --help
    /? / -?     Print this help.

[42sol-eu]

next action: design the interface in click (maybe first outside the cog-project)

[nedbat]

Looks like in some places you used a single dash where you meant double (DEFINE, out, prepend). Honestly, -D, -I, and -o are so common, I might skip the double-dash version. If you want to keep them, use "--define" and "--include", the all-uppercase looks odd.

Thanks!

[42sol-eu]

Ok, no define, include and out. You are right - uppercase long names is very strange Thanks for the fast replies.

[42sol-eu]

WIP: first draft with click

Click has soooo many more possibilities.

TODO: look if TEXT and INTEGER could be renamed TODO: insert all default values in documentation TODO: look at click.File and click.Folder

  Console interface for cog_2020

  FILENAMES       is [IN_FILE | @IN_FILE_LIST] ...

  IN_FILE         is the name of an input file,                 '-' will
  read from STDIN. @IN_FILE_LIST   is the name of a text file containing
  IN_FILE names                 (it also can contain other @FILE_LIST names)

Options:
  --version                  Show the version and exit.
  -c, --crc / --no-crc       Checksum the output to protect it against
                             accidental change. [default: True]
  -d, --delete TEXT          Delete the generator code from the output file.
  -r, --replace TEXT         Replace the input file with the output.
  -e, --warn TEXT            Warn if a file has no cog code in it. [default:
                             True]
  -I, --path TEXT            Add PATH to the list of directories for data
                             files and modules.
  -D, --define TEXT          Define a global string available to your
                             generator code. (name=value)
  -p, --prepend TEXT         Prepend the generator source with PROLOGUE.
                             Useful to insert an import line.
                                     Example:
                             -p "import math"
  -s, --suffix TEXT          Suffix all generated output lines with STRING.
  -U, --use-lf TEXT          Write the output with Unix newlines (only LF
                             line-endings).
  -z, --end-eof TEXT         The end - output marker can be omitted, and is
                             assumed at eof.
  -x, --excise TEXT          Excise all the generated output without running
                             the generators.
  -n, --encoding TEXT        Use ENCODING when reading and writing files.
  -w, --make-writeable TEXT  Use CMD if the output file needs to be made
                             writable.`
                             A %s in the CMD will be filled with
                             the filename.
  -o, --outfile TEXT         Write the output to OUT_NAME. [default: IN_FILE]
  --verbosity INTEGER        Control the amount of output. 2 (the default)
                             lists all files,
                             lists only changed files, 0
                             lists no files.
  --markers TEXT             START END END-OUTPUT
                             The patterns surrounding cog
                             inline instructions.
                             Should include three values
                             separated by spaces, the start, end, and end -
                             output markers.Defaults to
                                     default =
                             "[[[cog ]]] [[[end]]]"
  --help                     Show this message and exit.

[42sol-eu]

I am bit hung up about the test strategy for the command line interface.

@nedbat : What would you see as a acceptable strategy