1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* or http://www.opensolaris.org/os/licensing.
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 2010 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _CMDPARSE_H
#define _CMDPARSE_H
#ifdef __cplusplus
extern "C" {
#endif
#include <getopt.h>
#define SUBCOMMAND_BASE 1
/* bit defines for operand macros */
#define OPERAND_SINGLE 0x2
#define OPERAND_MULTIPLE 0x4
#define OPERAND_MANDATORY 0x8
#define OPERAND_OPTIONAL 0x10
/* maximum length of an option argument */
#define MAXOPTARGLEN 512
/* Following are used to express operand requirements */
#define OPERAND_NONE 0x1
#define OPERAND_MANDATORY_SINGLE (OPERAND_MANDATORY | OPERAND_SINGLE)
#define OPERAND_OPTIONAL_SINGLE (OPERAND_OPTIONAL | OPERAND_SINGLE)
#define OPERAND_MANDATORY_MULTIPLE (OPERAND_MANDATORY | OPERAND_MULTIPLE)
#define OPERAND_OPTIONAL_MULTIPLE (OPERAND_OPTIONAL | OPERAND_MULTIPLE)
/* subcommands must have a single bit on and must have exclusive values */
#define SUBCOMMAND(x) (SUBCOMMAND_BASE << x)
/*
* This structure is passed into the caller's callback function and
* will contain a list of all options entered and their associated
* option arguments if applicable
*/
typedef struct _cmdOptions {
int optval;
char optarg[MAXOPTARGLEN + 1];
} cmdOptions_t;
/*
* subcommand callback function
*
* argc - number of arguments in argv
* argv - operand arguments
* options - options entered on command line
* callData - pointer to caller data to be passed to subcommand function
*/
typedef int (*handler_t)(int argc, char *argv[], cmdOptions_t *options,
void *callData);
/*
* list of subcommands and associated properties
*
* name -> subcommand name
* handler -> function to call on successful syntax check
* optionString -> short options that are valid
* required -> Does it require at least one option?
* exclusive -> short options that are required to be exclusively entered
* operand -> Type of operand input. Can be:
*
* NO_OPERAND
* OPERAND_MANDATORY_SINGLE
* OPERAND_OPTIONAL_SINGLE
* OPERAND_MANDATORY_MULTIPLE
* OPERAND_OPTIONAL_MULTIPLE
*
* operandDefinition -> char * definition of the operand
*
* The long options table specifies whether an option argument is required.
*
*
* EXAMPLE:
*
* Based on "list-target" entry below:
*
* "list-target" is expected as the subcommand input
* listTarget is the function to be called on success
* "list-target" accepts -i, -s, -t and -l
* "list-target" requires the option 'i'.
* "list-target" has no exclusive options
* "list-target" may have one or more operands
* "list-target" operand description is "target-name"
*
*
* optionRules_t optionRules[] = {
* {"list-target", listTarget, "istl", "i", NULL,
* OPERAND_OPTIONAL_MULTIPLE, "target-name"},
* {"modify-target", modifyTarget, "t", "t", NULL,
* OPERAND_MANDATORY_MULTIPLE, "target-name"},
* {"enable", enable, NULL, NULL, NULL, NO_OPERAND, NULL},
* {NULL, 0, 0, NULL, 0, NULL}
* };
*/
typedef struct _subCommandProps {
char *name;
handler_t handler;
char *optionString;
char *required;
char *exclusive;
int operand;
char *operandDefinition;
char *helpText;
uint8_t reserved[60];
} subCommandProps_t;
#define required_arg required_argument
#define no_arg no_argument
/*
* Add short options and long options here
*
* name -> long option name
* has_arg -> required_arg, no_arg
* val -> short option character
* argDesc -> description of option argument
*
* Note: This structure may not be used if your CLI has no
* options. However, -?, --help and -V, --version will still be supported
* as they are standard for every CLI.
*
* EXAMPLE:
*
* optionTbl_t options[] = {
* {"filename", arg_required, 'f', "out-filename"},
* {NULL, 0, 0}
* };
*
*/
typedef struct _optionTbl {
char *name;
int has_arg;
int val;
char *argDesc;
} optionTbl_t;
/*
* After tables are set, assign them to this structure
* for passing into cmdparse()
*/
typedef struct _synTables {
char *versionString;
optionTbl_t *longOptionTbl;
subCommandProps_t *subCommandPropsTbl;
} synTables_t;
/*
* cmdParse is a parser that checks syntax of the input command against
* rules and property tables.
*
* When syntax is successfully validated, the function associated with the
* subcommand is called using the subcommands table functions.
*
* Syntax for the command is as follows:
*
* command [options] subcommand [<options>] [<operand ...>]
*
*
* There are two standard short and long options assumed:
* -?, --help Provides usage on a command or subcommand
* and stops further processing of the arguments
*
* -V, --version Provides version information on the command
* and stops further processing of the arguments
*
* These options are loaded by this function.
*
* input:
* argc, argv from main
* syntax rules tables (synTables_t structure)
* callArgs - void * passed by caller to be passed to subcommand function
*
* output:
* funcRet - pointer to int that holds subcommand function return value
*
* Returns:
*
* zero on successful syntax parse and function call
*
* 1 on unsuccessful syntax parse (no function has been called)
* This could be due to a version or help call or simply a
* general usage call.
*
* -1 check errno, call failed
*
*/
int cmdParse(int numOperands, char *operands[], synTables_t synTables,
void *callerArgs, int *funcRet);
#ifdef __cplusplus
}
#endif
#endif /* _CMDPARSE_H */
|
