Document options that take arguments

[verhovsky]

follow up to #7378

[verhovsky]

The updated script:

#!/usr/bin/env python3.9
from pathlib import Path
import sys

opts_file = Path('./src/tool_getparam.c')
help_file = Path('./src/tool_help.c')


opts_start = 'static const struct LongShort aliases[]= {'
opts_end = '};'

help_start = 'static const struct helptxt helptext[] = {'
help_end = '};'


def parse_getparam():
    opts = {}
    with open(opts_file) as f:
        for line in f:
            if line.startswith(opts_start):
                break
        for line in f:
            if line.startswith(opts_end):
                break
            if not line.startswith('  {'):
                continue

            short, opt, arg_type = line.strip().strip('{},').split(',')

            short = short.strip().strip('"')
            opt = opt.strip().strip('"')
            arg_type = arg_type.strip()

            if len(short) > 1:
                short = None

            opts[opt] = (short, arg_type)
    return opts


def parse_help():
    lines = {}
    opts = {}
    with open(help_file) as f:
        for line in f:
            if line.startswith(help_start):
                break
        for line in f:
            if line.startswith(help_end):
                break
            if not line.startswith('  {"'):
                continue

            line = line.strip().strip('{",')

            if line.startswith('-'):
                short, opt, *args = line.strip().lstrip('-').split(maxsplit=2)
                short = short.strip(',')
            else:
                short = None
                opt, *args = line.strip().split(maxsplit=1)

            if len(args) > 1:
                print('got more than 1 arg for', line)
            args = args[0] if args else None

            opt = opt.lstrip('-')
            # For example --buffer is documented as --no-buffer
            opt = opt.removeprefix('no-')

            lines[opt] = line
            opts[opt] = (short, args)
    return opts, lines

params = parse_getparam()
help_opts, lines = parse_help()


undocumented = params.keys() - help_opts.keys()
extra = help_opts.keys() - params.keys()
shared_opts = help_opts.keys() & params.keys()

def format_args(args):
    return ' '.join('--' + opt for opt in args)

if undocumented:
    print('these args appear in tool_getparam.c but not in tool_help.c:', format_args(undocumented), file=sys.stderr)
if extra:
    print('these args appear in tool_help.c but not in tool_getparam.c:', format_args(undocumented), file=sys.stderr)

#used_args = sorted({o[1] for o in help_opts.values() if o[1] is not None}, key=str.lower)
#print('possible args:', used_args, file=sys.stderr)
#print()

for opt in sorted(shared_opts):
    param_short, param_type = params[opt]
    help_short, help_args = help_opts[opt]

    if not help_args:
        help_type = 'ARG_BOOL'
    elif help_args in ['<file>', '<dir>', '<path>', '<filename>']:
        help_type = 'ARG_FILENAME'
    else:
        # strs.add(reported[opt])
        help_type = 'ARG_STRING'

    if param_type == 'ARG_NONE':
        param_type = 'ARG_BOOL'

    if param_type != help_type:
        print(params[opt][1].ljust(12).removeprefix('ARG_'), help_opts[opt][1])
        print(lines[opt])
        print()
    if param_short != help_short:
        print(params[opt][1].ljust(12).removeprefix('ARG_'), help_opts[opt][1])
        print(lines[opt])
        print()

Output (after the changes in this PR):

FILENAME <certificate[:password]>
-E, --cert <certificate[:password]>

STRING   <filename>
-c, --cookie-jar <filename>

STRING   <file>
    --egd-file <file>

BOOL     <category>
-h, --help <category>

FILENAME <key>
    --key <key>

STRING   <file>
    --libcurl <file>

STRING   <dir>
    --output-dir <dir>

FILENAME <cert[:passwd]>
    --proxy-cert <cert[:passwd]>

FILENAME <key>
    --proxy-key <key>

STRING   <path>
    --request-target <path>

The things that stand out are that --help was changed to take a <category> argument but is still marked as an ARG_BOOL. I'm guessing that's because you still want to print a help message if the arg is omitted? The other thing is these four options take what sounds like a file or directory name but have their type marked as ARG_STRING. I'm guessing that's because they shouldn't be validated as real files or something?

-c, --cookie-jar <filename>
    --egd-file <file>
    --libcurl <file>
    --output-dir <dir>

[danielgustafsson]

The other thing is these four options take what sounds like a file or directory name but have their type marked as ARG_STRING. I'm guessing that's because they shouldn't be validated as real files or something?

-c, --cookie-jar <filename>
    --egd-file <file>
    --libcurl <file>
    --output-dir <dir>

I have a feeling that at least a few of these might be oversights, closer inspection is for sure warranted.