IMO, docopt.c.py has a bad CLI

[ffunenga]

Currently, the user workflow when using docopt.c.py has two things that IMO are bad. This

cat example.docopt | python docopt.c.py > docopt.c

and the header of example.c file:

#include "docopt.c"

This is a bad CLI and a bad C implementation:

• This is a sub-project of docopt and, as such, it should make use of it.
• If you have a "big" project, normally you create a header file for the source of the module and then compile it separately.

  Proposed Solution

Use the following docopt string, like I've implemented here [1]:

usage: docopt_c.py [options] [DOCOPT]

Processes a docopt formatted string, from either stdin or a file, and
outputs the equivalent C code to parse the CLI, to either the stdout or a
set of two files (.c and .h).

Options:
  -o OUTNAME --output-name=OUTNAME
                Filename used to write OUTNAME.h and OUTNAME.c.
                If not present, an equivalent C file is printed to stdout.
  -d TEMPLATE --dev=TEMPLATE
                Filename used to read TEMPLATE.c and TEMPLATE.h.
  -v <level> --verbosity=<level>
                Set the verbosity level of stderr debug messages [default: 0]
  -h,--help     Show this help message and exit

Arguments:
  DOCOPT        Input file describing your CLI in docopt language.

Be aware of the comments inside the if __name__ == '__main__': at the end and the comments inside def __parse_cli(): in line 396.

[1] https://github.com/ffunenga/docopt.c/blob/feature/update-workflow/src/docopt_c.py

[keleshev]

I agree, cat example.docopt | python docopt.c.py > docopt.c is bad and eventually docopt_c.py should have a CLI approx. as you described.

However, during active development (of the C part) it could be useful to have single docopt.c file. @kblomqvist you decide when it's best to switch to "real" CLI for docopt_c.py.

[ffunenga]

...it could be useful to have single docopt.c file. That is why I've used the -d TEMPLATE --dev=TEMPLATE option. (only for development purposes, of course)

As an example see this: https://github.com/ffunenga/docopt.c/blob/feature/update-workflow/README.md#development

[kblomqvist]

Although, I would like to focus other features first it wouldn't hurt to have a "real" CLI from the beginning. That said I'm open to merge the "real" CLI when there's a pull request.

Approx. three months ago we had an email discussion with @halst concerning the CLI. I had a need of docopt.c code that wouldn't call exit() nor printf(). Additionally I would have liked to pass a pointer to args record instead of getting it as a return value of docopt(), like this:

DocoptArgs args = {};
docopt(argc, argv, &args, /* help */ 1, /* version */ "0.1");

Templates were mentioned then (by @halst):

Another thing I thought was that, maybe, instead of --no-exit-or-printf or --pass-args-pointer, docopt_c.py should take an argument: a template-file for code generation? That would incorporate any possible use-case scenario.

So -d, --dev=<template> wouldn't be just for development purpose but a feature we most probably need anyway. Thus it could be renamed to -t, --template=<template>? But why to generate both .h and .c?

[ffunenga]

...when there's a pull request.

Ok, I can do it. And the __str__.replace issue is easy too. I'll make a pull request.

Thus it could be renamed to -t, --template=<template>?

Yes of course.

Additionally I would have liked to pass a pointer to args record instead of getting it as a return value...

I totally agree with this :+1:

But why to generate both .h and .c?

I think docopt_c.py should output either:

• a C file to stdout OR
• a .c and a .h files written to two files .

I'm not saying that the approach cat example.docopt | python docopt.c.py > docopt.c (lets call it the Bash-Piped-Approach [BPA]) should be removed.

What I'm actually saying is that the BPA is not enough for a broader audience and the production of the header file should also be offered. (see this example) The motive behind this is, IMO, the need to EASILY integrate the docopt_c approach to a (real) C project (with a lot of modules, libraries, makefiles, CMakeLists.txt files and a big number of subfolders everywhere). (see here)

Kim, I understand this can disturb development and I suggest the implementation to be made at another time. Lets keep it simple and forget about the header file for now:

Proposed docopt string of docopt_c.py

usage: docopt_c.py [options] [DOCOPT]

Processes a docopt formatted string, from either stdin or a file, and
outputs the equivalent C code to parse a CLI, to either the stdout or a file.

Options:
  -o OUTNAME --output-name=OUTNAME
                Filename used to write the produced C file.
                If not present, the produced code is printed to stdout.
  -t TEMPLATE --template=TEMPLATE
                Filename used to read a TEMPLATE.
  -h,--help     Show this help message and exit

Arguments:
  DOCOPT        Input file describing your CLI in docopt language.

[kblomqvist]

Already merged to master.