~ubuntu-branches/ubuntu/trusty/argtable2/trusty : revision 1

1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

2

<HTML>

3

<HEAD>

4

5

<TITLE>Advanced argtable topics</TITLE>

6

7

8

9

10

11

<STYLE>

12

<!--

13

@page { size: 8.27in 11.69in }

14

H1 { margin-top: 0.79in }

15

PRE { margin-left: 0.3in }

16

PRE.western { font-size: 9pt }

17

-->

18

</STYLE>

19

</HEAD>

20

21

<H1 ALIGN=CENTER>Advanced argtable-2.x topics An ANSI

22

C library for parsing GNU style command line arguments</H1>

23

Stewart

24

Heitmann sheitmann@users.sourceforge.net

25

<H1 ALIGN=CENTER>Topics</H1>

26

Parsing multiple command line syntaxes

27

Writing custom callbacks

28

Creating custom argument types

29

30

1. Parsing multiple command line syntaxes</H1>

31

example code:

32

<installdir>/share/doc/argtable2/example/multisyntax.c

33

This topic shows

34

how to use argtable to implement a program having multiple

35

alternative command line syntaxes. In this case our example program

36

has four alternate syntaxes as follows:

37

<PRE CLASS="western">Usage: multisyntax [-nvR] insert <file> [<file>]... [-o <output>]

38

multisyntax [-nv] remove <file>

39

multisyntax [-v] search <pattern> [-o <output>]

40

multisyntax [--help] [--version]

41

This program demonstrates the use of the argtable2 library for parsing multiple command line syntaxes.

42

-n take no action

43

-v, --verbose verbose messages

44

-R recurse through subdirectories

45

<file> input file(s)

46

-o <output> output file (default is "-")

47

<pattern> search string

48

--help print this help and exit

49

</PRE>

50

A separate argument table is defined for each alternate syntax and

51

each is parsed against the command line in turn. That syntax which

52

returns no errors is taken to be the winner. Should no syntax match

53

the command line then the appropriate error messages are displayed

54

and the program exits. Obviously, you must design your alternate

55

syntaxes to be mutually exclusive, otherwise your program syntax will

56

be ambiguous. Mutual exclusion is achieved in this case by the use of

57

keywords (insert, remove, search) in the command line which uniquely

58

identify each syntax.

59

Looking at the

60

code, we see that each syntax is defined by its own argument table as

61

follows:

62

<PRE CLASS="western">/* SYNTAX 1: insert [-nvR] <file> [file]... -o <file> */

63

struct arg_rex *cmd1 = arg_rex1(NULL, NULL, "insert", NULL, REG_ICASE, NULL);

64

struct arg_lit *noact1 = arg_lit0("n", NULL, "take no action");

65

struct arg_lit *verbose1 = arg_lit0("v", "verbose", "verbose messages");

66

struct arg_lit *recurse1 = arg_lit0("R", NULL, "recurse through subdirectories");

67

struct arg_file *infiles1 = arg_filen(NULL,NULL, NULL, 1,argc+2, "input files)");

68

struct arg_file *outfile1 = arg_file0("o", NULL, "<output>", "output file (default is \"-\")");

69

struct arg_end *end1 = arg_end(20);

70

void* argtable1[] = {cmd1,noact1,verbose1,recurse1,infiles1,outfile1,end1};

71

int nerrors1;

72

73

/* SYNTAX 2: remove [-nv] <file> */

74

struct arg_rex *cmd2 = arg_rex1(NULL, NULL, "remove", NULL, REG_ICASE, NULL);

75

struct arg_lit *noact2 = arg_lit0("n", NULL, NULL);

76

struct arg_lit *verbose2 = arg_lit0("v", "verbose", NULL);

77

struct arg_file *infiles2 = arg_file1(NULL, NULL, NULL, NULL);

78

struct arg_end *end2 = arg_end(20);

79

void* argtable2[] = {cmd2,noact2,verbose2,infiles2,end2};

80

int nerrors2;

81

82

/* SYNTAX 3: search [-v] <pattern> [-o <file>] [--help] [--version] */

83

struct arg_rex *cmd3 = arg_rex1(NULL, NULL, "search", NULL, REG_ICASE, NULL);

84

struct arg_lit *verbose3 = arg_lit0("v", "verbose", NULL);

85

struct arg_str *pattern3 = arg_str1(NULL, NULL, "<pattern>", "search string");

86

struct arg_file *outfile3 = arg_file0("o", NULL, "<output>", NULL);

87

struct arg_end *end3 = arg_end(20);

88

void* argtable3[] = {cmd3,verbose3,pattern3,outfile3,end3};

89

int nerrors3;

90

91

/* SYNTAX 4: [-help] [-version] */

92

struct arg_lit *help4 = arg_lit0(NULL,"help", "print this help and exit");

93

struct arg_lit *version4 = arg_lit0(NULL,"version", "print version information and exit");

94

struct arg_end *end4 = arg_end(20);

95

void* argtable4[] = {help4,version4,end4};

96

int nerrors4;</PRE>

97

Notice that the argument tables keep their contents separate from

98

each other. While it may be tempting to share an arg_xxx

99

structure between multiple argument tables, that will not work in

100

this example code since the contents of any shared arg_xxx

101

structure will be repeatedly overwritten when each successive

102

argument table is parsed.

103

The insert/remove/search keywords are

104

implemented using arg_rex

105

arguments. These are parsed as untagged string arguments that must

106

match a given regular expression: "insert", "remove",

107

and "search" respectively. The REG_ICASE regex flag is also

108

given to allow case insensitive regular expression matching as a

109

nicety. See the argtable programmer's manual for more information of

110

the arg_rex argument

111

type.

112

Since we have multiple argument

113

tables, you'll need to pre-set any default argument values in every

114

argument table in which the value appears. Here we set the default

115

value of the output filename argument which appears in both the first

116

and third argument tables as struct

117

arg_file *outfile1 and struct

118

arg_file *outfile2 respectively.

119

<PRE CLASS="western">/* set any command line default values prior to parsing */

120

outfile1->filename[0]="-";

121

outfile3->filename[0]="-";</PRE>

122

Having completed the argument tables, the command line is parsed

123

against each argument table in turn and we record the number of

124

errors reported by each.

125

<PRE CLASS="western">nerrors1 = arg_parse(argc,argv,argtable1);

126

nerrors2 = arg_parse(argc,argv,argtable2);

127

nerrors3 = arg_parse(argc,argv,argtable3);

128

nerrors4 = arg_parse(argc,argv,argtable4);</PRE>

129

If any of these return zero errors then we have detected a successful

130

matching command line and we can pass the argument data from the

131

matching argument table to our program's main processing routine.

132

133

<PRE CLASS="western">if (nerrors1==0)

134

exitcode = mymain1(noact1->count, verbose1->count, recurse1->count,

135

outfile1->filename[0], infiles1->filename, infiles1->count);

136

else if (nerrors2==0)

137

exitcode = mymain2(noact2->count, verbose2->count, infiles2->filename[0]);

138

else if (nerrors3==0)

139

exitcode = mymain3(verbose3->count, pattern3->sval[0], outfile3->filename[0]);

140

else if (nerrors4==0)

141

exitcode = mymain4(help4->count, version4->count, progname, argtable1, argtable2, argtable3, argtable4);</PRE>

142

Should they all return errors then we must display the appropriate

143

syntax error messages. The trick is knowing which error messages to

144

display. Simply displaying the error messages for each and every

145

syntax will work, but is overkill as it generates a lot of irrelevant

146

messages. A better strategy is to display only those errors related

147

to the syntax that gave the fewest errors on the presumption that the

148

user got it mostly correct. The strategy used in this example however

149

is to utilise the presence of any keywords ("insert",

150

"remove", "search") as markers to indicate which

151

syntax the user intended and only display the errors for that syntax.

152

Remember that the keywords were implemented using arg_rex

153

argument structures (cmd1,

154

cmd2, cmd3) and these will return a count of 0

155

if the keyword was missing from the command line and 1 otherwise.

156

Thus we can test the presence of each keyword by checking the count

157

value stored in the cmd1, cmd2, and cmd3

158

structures.

159

160

So if the "insert" keyword

161

was given on the command line then we display only those errors

162

associated with the first argument table, namely, the errors stored

163

in struct arg_end *end1.

164

<PRE CLASS="western">if (cmd1->count > 0)

165

{

166

/* here the cmd1 argument was correct, so presume syntax 1 was intended target */

167

arg_print_errors(stdout,end1,progname);

168

printf("usage: %s ", progname);

169

arg_print_syntax(stdout,argtable1,"\n");

170

}</PRE>

171

Likewise for the "remove" and "search" keywords

172

of the second and third argument tables

173

<PRE CLASS="western">else if (cmd2->count > 0)

174

{

175

/* here the cmd2 argument was correct, so presume syntax 2 was intended target */

176

arg_print_errors(stdout,end2,progname);

177

printf("usage: %s ", progname);

178

arg_print_syntax(stdout,argtable2,"\n");

179

}

180

else if (cmd3->count > 0)

181

{

182

/* here the cmd3 argument was correct, so presume syntax 3 was intended target */

183

arg_print_errors(stdout,end3,progname);

184

printf("usage: %s ", progname);

185

arg_print_syntax(stdout,argtable3,"\n");

186

}</PRE>

187

If none of the keywords were detected we display a message to that

188

effect followed by the full usage description.

189

<PRE CLASS="western">else

190

{

191

/* no correct cmd literals were given, so we cant presume which syntax was intended */

192

printf("%s: missing <insert|remove|search> command.\n",progname);

193

printf("usage 1: %s ", progname); arg_print_syntax(stdout,argtable1,"\n");

194

printf("usage 2: %s ", progname); arg_print_syntax(stdout,argtable2,"\n");

195

printf("usage 3: %s ", progname); arg_print_syntax(stdout,argtable3,"\n");

196

printf("usage 4: %s", progname); arg_print_syntax(stdout,argtable4,"\n");

197

}</PRE>

198

Lastly, remember to clean up all the argument tables at program's

199

end.

200

<PRE CLASS="western">arg_freetable(argtable1,sizeof(argtable1)/sizeof(argtable1[0]));

201

arg_freetable(argtable2,sizeof(argtable2)/sizeof(argtable2[0]));

202

arg_freetable(argtable3,sizeof(argtable3)/sizeof(argtable3[0]));

203

arg_freetable(argtable4,sizeof(argtable4)/sizeof(argtable4[0]));</PRE>

204

<HR>

205

<H1>2. Writing custom callbacks</H1>

206

example code:

207

<installdir>/share/doc/argtable2/example/callbacks.c

208

This topic shows

209

how to write your own argtable callback functions for controlling the

210

parsing, validation, and error reporting aspects of the command line

211

parsing. Each arg_xxx struct has four callback routines that

212

get called by the argtable parser. These are buried within the

213

arg_hdr structure that each arg_xxx structure has.

214

Among other things, you can see the relevant function pointers below.

215

They are called resetfn, scanfn, checkfn, and

216

errorfn.

217

<PRE CLASS="western">typedef void (arg_resetfn)(void *parent);

218

typedef int (arg_scanfn)(void *parent, const char *argval);

219

typedef int (arg_checkfn)(void *parent);

220

typedef void (arg_errorfn)(void *parent, FILE *fp, int error, const char *argval, const char *progname);

221

222

struct arg_hdr

223

{

224

char flag;

225

const char *shortopts;

226

const char *longopts;

227

const char *datatype;

228

const char *glossary;

229

int mincount;

230

int maxcount;

231

void *parent;

232

arg_resetfn *resetfn;

233

arg_scanfn *scanfn;

234

arg_checkfn *checkfn;

235

arg_errorfn *errorfn;

236

void *priv;

237

};</PRE>

238

These function pointers are always pre-set by the arg_xxx

239

constructor functions to the default routines for that argument type

240

and ordinarily there is no need to change them. However, you may

241

replace them with your own custom routines if you wish. Thus when

242

argtable parses the command line for these particular argument types,

243

it will call your custom callbacks rather than the default routines.

244

However responsibility comes with control, and all callbacks must

245

implement certain features that argtable expects. These are each

246

discussed in turn.

247

<H4>void resetfn(void *parent)</H4>

248

The resetfn of each arg_xxx

249

within an argument table is called once by the parser prior to

250

parsing the command line. This provides the opportunity to initialise

251

the arg_xxx structure prior to parsing and nominally requires

252

resetting the argument count to zero. The parent parameter is

253

actually a pointer to the pertinent arg_xxx structure, and

254

should be cast appropriately. The casting may be done in the function

255

definition as shown in this example for an arg_int struct.

256

257

<PRE CLASS="western">void myresetfn(struct arg_int *parent)

258

{

259

parent->count=0;

260

}</PRE>

261

The storage space for the parsed argument values should not be

262

initialised since the user may have deliberately set default values

263

that should be retained.

264

<H4>int scanfn(void *parent, const char *argval)</H4>

265

The parser calls an arg_xxx's

266

scanfn routine once for each matching command line argument that

267

needs to be parsed. Its purpose is to extract the argument's data

268

value from the argument string in argval, convert it to the

269

appropriate data type, and store the result in the arg_xxx's

270

data array. The function must return zero to indicate success and a

271

non-zero error code otherwise. The error codes may be of your own

272

choosing as they will latter be handled by your own errorfn

273

callback.

274

<PRE CLASS="western">enum {EMINCOUNT=1, EMAXCOUNT, EBADINT};

275

276

int myscanfn(struct arg_int *parent, const char *argval)

277

{

278

int val;

279

char *end;

280

/* return EMAXCOUNT if we have exceeded the maximum argument count */

281

if (parent->count == parent->hdr.maxcount )

282

return EMAXCOUNT;

283

284

/* extract base10 integer from argval string into val */

285

/* return EBADINT if conversion failed */

286

val = (int)strtol(argval,&end,10);

287

if (*end!=0)

288

return EBADINT;

289

290

/* <perform custom checks here> */

291

292

/* store the value in parent's ival[] array and increment the argument count */

293

parent->ival[parent->count++] = val;

294

295

/* return zero to indicate success */

296

return 0;

297

}</PRE>

298

Do not print error messages from within scanfn as the

299

user may wish to delay the error messages until alternative argument

300

tables have been tried. In the meantime the parser will save each

301

returned error code in the argument table's arg_end structure.

302

Latter, the arg_print_errors function will be called to

303

retrieve those error codes from arg_end and pass them onto the

304

errorfn callbacks whose job is to print the appropriate

305

messages.

306

<H4>int checkfn(void *parent)</H4>

307

The checkfn of each arg_xxx

308

within an the argument table is called by the parser once upon

309

completion of command line parsing. It provides the opportunity to

310

perform any post-parse error checks and nominally requires checking

311

the minimum argument count for the arg_xxx structure has been

312

satisfied.

313

314

<PRE CLASS="western">int mycheckfn(struct arg_int *parent)

315

{

316

/* return EMINCOUNT if the minimum number of arguments is not present. */

317

if (parent->count < parent->hdr.mincount)

318

return EMINCOUNT;

319

320

/* <perform custom checks here> */

321

322

/* all checks passed */

323

return 0;

324

}</PRE>

325

Like scanfn, it should return zero for success and a user-defined

326

non-zero error code otherwise. These error codes are likewise

327

destined to be passed onto errorfn.

328

<H4>int errorfn(void *parent, FILE *fp, int errorcode, const char

329

*argval, const char *progname)</H4>

330

When the users wishes to print the

331

syntax error messages he or she calls the arg_print_errors

332

function which in turn calls the errorfn routine of each

333

arg_xxx for each error that was previously reported. This is

334

where the error messages for the corresponding error codes are

335

printed. The parent pointer refers to the pertinent arg_xxx

336

structure, and FILE* fp designates the output stream onto

337

which the error messages should be printed. The errorcode

338

parameter contains the same value returned by the scanfn or

339

checkfn routine that reported the error, and argval

340

points to the offending command line argument string. The progname

341

parameter is the same one passed to the arg_print_errors

342

function, and is expected to contain the name of the program which is

343

usually prefixed onto the error message by convention. Notice that

344

each arg_xxx need only handle the error codes generated by its

345

own scanfn and checkfn routines.

346

<PRE CLASS="western">void myerrorfn(struct arg_int *parent, FILE *fp, int errorcode, const char *argval, const char *progname)

347

{

348

/* for convenience */

349

const char *shortopts = parent->hdr.shortopts;

350

const char *longopts = parent->hdr.longopts;

351

const char *datatype = parent->hdr.datatype;

352

353

/* prefix all error messages with the program name */

354

fprintf(fp,"%s: ",progname);

355

356

switch(errorcode)

357

{

358

case EMINCOUNT:

359

fputs("missing option ",fp);

360

arg_print_option(fp,shortopts,longopts,datatype,"\n");

361

break;

362

363

case EMAXCOUNT:

364

fputs("excess option ",fp);

365

arg_print_option(fp,shortopts,longopts,argval,"\n");

366

break;

367

368

case EBADINT:

369

arg_print_option(fp,shortopts,longopts,argval," is not a valid <int>\n");

370

break;

371

372

/* <add custom error messages here> */

373

374

}

375

}</PRE><H4>

376

Hooking the callbacks into the arg_xxx structure</H4>

377

There are no functions for

378

registering callbacks with arg_xxx structures, you simply write the

379

function pointers directly into the arg_xxx structure after it has

380

been constructed.

381

<PRE CLASS="western">struct arg_int *val = arg_intn(NULL,NULL,NULL,2,100,"blah blah");

382

383

/* replace the default arg_int parser routines with custom routines */

384

val->hdr.resetfn = (arg_resetfn*)myresetfn;

385

val->hdr.scanfn = (arg_scanfn*)myscanfn;

386

val->hdr.checkfn = (arg_checkfn*)mycheckfn;

387

val->hdr.errorfn = (arg_errorfn*)myerrorfn;</PRE><H4>

388

Words of restraint</H4>

389

Callbacks are part of the argtable

390

design to make it possible to add new argument data types in future

391

without changing the base argtable source code. Since they exist,

392

they may be exploited by the programmer for finer control of the

393

parsing and error validation but that was never their intended role.

394

It is the authors view that the majority of custom argument checking

395

tasks are better done as a second stage in your program after

396

argtable has done its job. It is usually much simpler to implement

397

additional post-parse checks in your own code than creating custom

398

argtable callbacks that do it all. Custom callbacks are really only

399

required if you are scanning data types that argtable does not

400

support natively. In such cases you may also need to create a custom

401

arg_xxx structure in which to store the results, as is described in

402

the next topic.

403

<HR>

404

<H1>3. Creating custom argument types</H1>

405

example code:

406

<installdir>/share/doc/argtable2/example/argcustom.c,

407

argxxx.c, argxxx.h

408

This topic shows how

409

to write new argument types for use with the argtable parser. These

410

need not be compiled into the library base code, so you can create

411

custom argument types for specific programs at will. A custom

412

argument type is required if you need to handle a data type that is

413

not supported natively by the argtable library. It involves defining

414

a new arg_xxx structure and writing the callback and

415

constructor functions that go with it. If you merely wish to alter

416

the parsing and validation rules applied to an existing arg_xxx

417

data type then hooking your own custom callbacks into the existing

418

structure as described in the previous topic is more appropriate.

419

<H4>Defining an arg_xxx structure</H4>

420

Every arg_xxx struct must have

421

an arg_hdr struct as its first data member. Internally,

422

argtable casts all arg_xxx structures to arg_hdr

423

structures, so it is imperative that arg_hdr be the first data

424

member. Argtable uses the information within it to cast the command

425

line option into the format required by GNU getopt which actually

426

does the parsing.

427

<PRE CLASS="western">struct arg_xxx

428

{

429

struct arg_hdr hdr; /* The mandatory argtable header struct */

430

int count; /* Number of matching arguments parsed */

431

<xxx> *data; /* Array for storing the argument values */

432

... /* Other custom fields go here */

433

};</PRE>

434

Custom data members follow the arg_hdr struct. Since argtable

435

supports multiple instances of any given command line argument, it is

436

usual that your structure provides an array for storing multiple

437

argument values (arg_xxx.data) and a count of them

438

(arg_xxx.count). Add any other fields you need for your custom

439

parsing routines as required. Any internal data you would prefer to

440

hide from the end-user can be stored in a user-defined private data

441

structure that is encapsulated by the arg_hdr structure as you

442

will see next.

443

<PRE CLASS="western">struct arg_xxx_priv

444

{

445

/* Private custom data goes here */

446

...

447

};</PRE><H4>

448

Defining the argx_xxx constructors</H4>

449

Each arg_xxx structure should have a

450

constructor function that is responsible for allocating memory for it

451

and populating the data within it. By convention, there are

452

ordinarily three forms of constructor function for each arg_xxx

453

struct

454

<PRE CLASS="western">struct arg_xxx* arg_xxx0(const char* shortopts, const char* longopts, const char *datatype, const char *glossary);

455

456

struct arg_xxx* arg_xxx1(const char* shortopts, const char* longopts, const char *datatype, const char *glossary);

457

458

struct arg_xxx* arg_xxxn(const char* shortopts, const char* longopts, const char *datatype,

459

int mincount, int maxcount, const char *glossary);</PRE>

460

The different forms provide a convenient means for specifying command

461

line arguments that accept either zero-or-one, exactly-one, or many

462

instances on the command line. The first two forms are typically

463

implemented as wrapper functions of the third. You may customise the

464

actual parameters to fit your purposes, the declarations above are

465

merely examples of common forms.

466

467

468

The diagram shows the general layout

469

of the data structure that should be returned by the arg_xxx

470

constructor function(s). It comprises of a single contiguous block of

471

heap allocated memory, with the arg_xxx struct at its head,

472

followed by the storage space for maxcount argument values as

473

well as an optional private data structure that may be used to hide

474

internal data from the end-user. If the allocation failed then the

475

constructor should return NULL.

476

<PRE CLASS="western">size_t nbytes;

477

struct arg_xxx *result;

478

479

nbytes = sizeof(struct arg_xxx) + sizeof(struct arg_xxx_priv) + maxcount*sizeof(<xxx>) ;

480

result = (struct arg_xxx*)malloc(nbytes);</PRE>

481

The entire arg_hdr structure must be populated by the

482

constructor, including the pointers to the appropriate callback

483

functions, the enclosing arg_xxx structure (void *parent),

484

and the private data structure (void *priv).

485

486

<PRE CLASS="western">result->hdr.flag = ARG_HASVALUE; /* argument accepts a value */

487

result->hdr.shortopts = shortopts; /* short options */

488

result->hdr.longopts = longopts; /* long options */

489

result->hdr.datatype = datatype ? datatype : "<xxx>"; /* datatype description */

490

result->hdr.glossary = glossary; /* glossary description */

491

result->hdr.mincount = mincount; /* minimum number of arguments */

492

result->hdr.maxcount = maxcount; /* maximum number of arguments */

493

result->hdr.parent = result; /* ptr to parent arg_xxx struct */

494

result->hdr.resetfn = (arg_resetfn*)resetfn; /* ptr to resetfn callback */

495

result->hdr.scanfn = (arg_scanfn*)scanfn; /* ptr to scanfn callback */

496

result->hdr.checkfn = (arg_checkfn*)checkfn; /* ptr to checkfn callback */

497

result->hdr.errorfn = (arg_errorfn*)errorfn; /* ptr to errorfn callback */

498

result->hdr.priv = result + 1; /* ptr to private data */ </PRE>

499

The custom arg_xxx fields should also be populated,

500

particularly the pointer to the argument storage array. The values

501

within the array may or may not be initialised at your discretion.

502

<PRE CLASS="western">/* locate the data[maxcount] array immediately after the private data structure */

503

result->data = (<xxx>*)((struct arg_xxx_priv*)(result->hdr.priv) + 1);

504

505

/* init the remaining of the arg_xxx struct variables */

506

result->count = 0;

507

...</PRE>

508

Lastly, we return a pointer to the completed data structure

509

<PRE CLASS="western" STYLE="margin-top: 0.2in; margin-bottom: 0.2in">return result;</PRE>

510

511

512

</BODY>

513

</HTML>

b'\\ No newline at end of file'