fs(3)

NAME
cmd - command line parser and mdoc manual page generator

SYNOPSIS
struct cmd_syndesc * cmd_CreateSyntax(const char *name, cmd_proc main, void *rock, const char *help_str);
int cmd_setBeforeProc(int (*proc) (void *rock), void *rock);
int cmd_setAfterProc(int (*proc) (void *rock), void *rock);
void cmd_AddParm(struct cmd_syndesc *ts, const char *cmd, cmd_parmdesc_type type, cmd_parmdesc_flags flags, const char *help_str);
int cmd_CreateAlias(struct cmd_syndesc *ts, const char *name);
int cmd_Seek(struct cmd_syndesc *ts, int pos);
int cmd_ParseLine(const char *line, char **argv, int *n, int maxn);
void cmd_FreeArgv(char **argv);
int cmd_Dispatch(int argc, char **argv);

DESCRIPTION
cmd is a suite of functions that parses file for the Arla programs in a AFS compatible way.

There is some problems with the cmd interface, both that you have to do a lof of post-parsing yourself (like fetching converting to numbers) and the interface isn't reenterant.

You create a new command by calling cmd_CreateSyntax(). An alias to this command can be added with cmd_CreateAlias(). Then parameters can be added to the command with cmd_AddParm(). Finally cmd_Dispatch() is called and the argument are parsed.

The cmd_CreateSyntax() function adds a new command name to the syntax. If the command is found when parsing, then function main is called with the argument rock. The helpstring help_str() is shown whenever help is needed for this command.

The function cmd_setBeforeProc() sets a function to be called when parsing is complete and the main is about to be called for current command. Rock is passed as an argument to proc whenever called.

The function cmd_setAfterProc() sets a function to be called after the main for the current command has been called. Rock is passed as an argument to proc whenever called.

The function cmd_AddParm() adds a new parameter cmd to the command ts of type and with flags. If the user want help about the command, help_str is incorporated in the help output.

The function cmd_CreateAlias() creates a alias name for the command ts.

The function cmd_Seek() changes the argument currently being set by cmd_AddParm() This makes it possible to limit a CMD_LIST|CMD_EXPANDS parmeter, with respect to how many argument that it will parse.

The function cmd_ParseLine() will split up the line into argument that is saved in argv maxium of maxn will be parsed. The number of argument will be stored in n.

The function will free the arguments argv that cmd_ParseLine() allocated.

The function cmd_Dispatch() will take the current syntax and try to parse the arguments argc, argv.

When a mdoc(7) file is generated. The .ctx file for the command is read to add extra content to the manual-page. The file is split up in sections separated by

    %section-name part-name

Typical lines are %command commandname, where commandname is the name that was added with cmd_CreateSyntax.()

Other sections are

%name description
    Description of the program (.Nm in mdoc).

%name os
    Os version (.Os in mdoc).

%name section
    Section of the manualpage (.Dt in mdoc).

%section description
    Text for the DESCRIPTION section.

%section errors
    Text for the ERRORS section.

%section see also
    Text for the SEE ALSO section.

%section history
    Text for the HISTORY section.

%section authors
    Text for the AUTHORS section.

%section BUGS
    Text for the bugs section.

Lines starting with # are comments.

ENVIRONMENT
When CMD_MANDOC set to something and the built-in command help is called, mdoc output is generated. srcdir is looked upon when opening the .ctx file to enable building out of tree.

EXAMPLES

    #include <stdio.h>
    #include <err.h>
    #include <cmd.h>
    static int
    setacl (struct cmd_syndesc *t, void *ptr)
    {
        struct cmd_item *it;
        int i;
        printf ("setacl:");
        printf (" dir: %s aces:", (char *)t->params[0].items->data);
        for (it = t->params[1].items; it ; it = it->next) {
    	printf (" %s", (char *)it->data);
    	i++;
        }
        if (t->params[2].items)
    	printf (" flag: -clear");
        printf (");
        if (i % 2 != 0)
    	errx (1, "ace pairs isn't pairs");
        return 0;
    }
    int
    main (int argc, char **argv)
    {
        struct cmd_syndesc *ts;
        int ret;
        ts = cmd_CreateSyntax ("setacl", setacl, NULL, "set a acl on a directory");
        cmd_CreateAlias (ts, "sa");
        cmd_AddParm (ts, "-dir", CMD_SINGLE, CMD_REQUIRED, "dir");
        cmd_AddParm (ts, "-ace", CMD_LIST, CMD_REQUIRED, "acl entry");
        cmd_AddParm (ts, "-clear", CMD_FLAG, CMD_OPTIONAL, "");
        ret = cmd_Dispatch (argc, argv);
        if (ret)
    	errx (1, "dispatch failed");
        return 0;
    }

FILES
A file named the same way as the command binary (really argv[0]) with the extention .ctx will be used to add extra help-text in the mdoc manpage when its generated.

SEE ALSO
getarg(3), mdoc(7)

HISTORY
First written on CMU. Taken up by Transarc/IBM in their AFS product. Reimplmented for Arla since a lot of people missed it. When it got added to arla it also got functionally like generating mdoc output.

AUTHORS
Love Hörnquist-Åstrand <lha@stacken.kth.se>

BUGS
Plenty of them.

cmd_ParseLine() and cmd_FreeArgv() isn't implemeted.