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