Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document options that take arguments #7382

Closed
wants to merge 1 commit into from
Closed

Conversation

verhovsky
Copy link
Contributor

follow up to #7378

@verhovsky
Copy link
Contributor Author

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>

@verhovsky verhovsky changed the title Document that take arguments Document options that take arguments Jul 13, 2021
@danielgustafsson
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging this pull request may close these issues.

None yet

3 participants