.\" $KTH: cmd.3,v 1.1 2000/06/01 14:30:58 lha Exp $
.\" Things to fix:
.\"   * use better macros for arguments (like .Pa for files)
.\"
.Dd June 1, 2000
.Dt fs 3
.Os "Arla, KTH"
.Sh NAME
.Nm cmd
.Nd command line parser and mdoc manual page generator
.Sh SYNOPSIS
.Fo "struct cmd_syndesc * cmd_CreateSyntax"
.Fa "const char *name"
.Fa "cmd_proc main"
.Fa "void *rock"
.Fa "const char *help_str"
.Fc
.Fo "int cmd_setBeforeProc"
.Fa "int (*proc) (void *rock)"
.Fa "void *rock"
.Fc
.Fo "int cmd_setAfterProc"
.Fa "int (*proc) (void *rock)"
.Fa "void *rock"
.Fc
.Fo "void cmd_AddParm"
.Fa "struct cmd_syndesc *ts"
.Fa "const char *cmd"
.Fa "cmd_parmdesc_type type"
.Fa "cmd_parmdesc_flags flags"
.Fa "const char *help_str"
.Fc
.Fo "int cmd_CreateAlias"
.Fa "struct cmd_syndesc *ts"
.Fa "const char *name"
.Fc
.Fo "int cmd_Seek"
.Fa "struct cmd_syndesc *ts"
.Fa "int pos"
.Fc
.Fo "int cmd_ParseLine"
.Fa "const char *line"
.Fa "char **argv"
.Fa "int *n"
.Fa "int maxn"
.Fc
.Fo "void cmd_FreeArgv"
.Fa "char **argv"
.Fc
.Fo "int cmd_Dispatch"
.Fa "int argc"
.Fa "char **argv"
.Fc
.Sh DESCRIPTION
.Nm
is a suite of functions that parses file for the Arla programs in a
AFS compatible way.
.Pp
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.
.Pp
You create a new command by calling
.Fn cmd_CreateSyntax .
An alias to this command can be added with
.Fn cmd_CreateAlias .
Then parameters can be added to the command with
.Fn cmd_AddParm .
Finally
.Fn cmd_Dispatch
is called and the argument are parsed.
.Pp
The
.Fn cmd_CreateSyntax
function adds a new command
.Fa name
to the syntax. If the command is found when parsing, then function
.Fa main
is called with the argument
.Fa rock.
The helpstring
.Fn help_str
is shown whenever help is needed for this command.
.Pp
The function
.Fn cmd_setBeforeProc
sets a function to be called when parsing is complete and the
.Fa main
is about to be called for current command.
.Fa Rock
is passed as an argument to
.Fa proc
whenever called.
.Pp
The function
.Fn cmd_setAfterProc
sets a function to be called after
the
.Fa main
for the current command has been called.
.Fa Rock
is passed as an argument to
.Fa proc
whenever called.
.Pp
The function
.Fn cmd_AddParm
adds a new parameter
.Fa cmd
to the command
.Fa ts
of 
.Fa type
and with
.Fa flags .
If the user want help about the command,
.Fa help_str
is incorporated in the help output.
.Pp
The function
.Fn cmd_CreateAlias
creates a alias
.Fa name
for the command
.Fa ts .
.Pp
The function
.Fn cmd_Seek
changes the argument currently being set by
.Fn cmd_AddParm
This makes it possible to limit a
.Fa CMD_LIST|CMD_EXPANDS
parmeter, with respect to how many argument that it will parse.
.Pp
The function
.Fn cmd_ParseLine
will split up the
.Fa line
into argument that is saved in
.Fa argv
maximum of
.Fa maxn
will be parsed.
The number of argument will be stored in
.Fa n.
.Pp
The function
.fn cmd_FreeArgv
will free the arguments
.Fa argv
that
.Fn cmd_ParseLine
allocated.
.Pp
The function
.Fn cmd_Dispatch
will take the current syntax and try to parse the arguments
.Fa argc, argv.
.Pp
When a
.Xr 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
.Pp
.Dl %section-name part-name
.Pp
Typical lines are 
.Li %command
.Fa commandname,
where commandname is the name that was added with
.Fn cmd_CreateSyntax.
.Pp
Other sections are
.Bl -tag -width "section"
.It %name description
Description of the program (\&.Nm in mdoc).
.It %name os
Os version (\&.Os in mdoc).
.It %name section
Section of the manualpage (\&.Dt in mdoc).
.It %section description
Text for the DESCRIPTION section.
.It %section errors
Text for the ERRORS section.
.It %section see also
Text for the SEE ALSO section.
.It %section history
Text for the HISTORY section.
.It %section authors
Text for the AUTHORS section.
.It %section BUGS
Text for the bugs section.
.El
.Pp
Lines starting with # are comments.
.Sh ENVIRONMENT
When 
.Ev CMD_MANDOC
set to something and the built-in command
.Cm help
is called, mdoc output is generated.
.Ev srcdir
is looked upon when opening the .ctx file to enable building out of tree.
.Sh EXAMPLES
.Bd -literal
#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 ("\n");
    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;
}

.Ed
.Sh 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.
.Sh SEE ALSO
.Xr getarg 3 ,
.Xr mdoc 7
.Sh HISTORY
First written on CMU. Taken up by Transarc/IBM in their AFS
product. Reimplemented for Arla since a lot of people missed it. When
it got added to arla it also got functionally like generating mdoc
output.
.Sh AUTHORS
Love Hörnquist-Åstrand <lha@stacken.kth.se>
.Sh BUGS
Plenty of them.
.Pp
.Fn cmd_ParseLine
and
.Fn cmd_FreeArgv
isn't implemented.