technical/api-parse-options.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.5.2" />
   7 <title>parse-options API</title>
   8 <style type="text/css">
   9 /* Debug borders */
  10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  11 /*
  12   border: 1px solid red;
  13 */
  14 }
  15
  16 body {
  17   margin: 1em 5% 1em 5%;
  18 }
  19
  20 a {
  21   color: blue;
  22   text-decoration: underline;
  23 }
  24 a:visited {
  25   color: fuchsia;
  26 }
  27
  28 em {
  29   font-style: italic;
  30   color: navy;
  31 }
  32
  33 strong {
  34   font-weight: bold;
  35   color: #083194;
  36 }
  37
  38 tt {
  39   color: navy;
  40 }
  41
  42 h1, h2, h3, h4, h5, h6 {
  43   color: #527bbd;
  44   font-family: sans-serif;
  45   margin-top: 1.2em;
  46   margin-bottom: 0.5em;
  47   line-height: 1.3;
  48 }
  49
  50 h1, h2, h3 {
  51   border-bottom: 2px solid silver;
  52 }
  53 h2 {
  54   padding-top: 0.5em;
  55 }
  56 h3 {
  57   float: left;
  58 }
  59 h3 + * {
  60   clear: left;
  61 }
  62
  63 div.sectionbody {
  64   font-family: serif;
  65   margin-left: 0;
  66 }
  67
  68 hr {
  69   border: 1px solid silver;
  70 }
  71
  72 p {
  73   margin-top: 0.5em;
  74   margin-bottom: 0.5em;
  75 }
  76
  77 ul, ol, li > p {
  78   margin-top: 0;
  79 }
  80
  81 pre {
  82   padding: 0;
  83   margin: 0;
  84 }
  85
  86 span#author {
  87   color: #527bbd;
  88   font-family: sans-serif;
  89   font-weight: bold;
  90   font-size: 1.1em;
  91 }
  92 span#email {
  93 }
  94 span#revnumber, span#revdate, span#revremark {
  95   font-family: sans-serif;
  96 }
  97
  98 div#footer {
  99   font-family: sans-serif;
 100   font-size: small;
 101   border-top: 2px solid silver;
 102   padding-top: 0.5em;
 103   margin-top: 4.0em;
 104 }
 105 div#footer-text {
 106   float: left;
 107   padding-bottom: 0.5em;
 108 }
 109 div#footer-badges {
 110   float: right;
 111   padding-bottom: 0.5em;
 112 }
 113
 114 div#preamble {
 115   margin-top: 1.5em;
 116   margin-bottom: 1.5em;
 117 }
 118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 120 div.admonitionblock {
 121   margin-top: 1.0em;
 122   margin-bottom: 1.5em;
 123 }
 124 div.admonitionblock {
 125   margin-top: 2.0em;
 126   margin-bottom: 2.0em;
 127   margin-right: 10%;
 128   color: #606060;
 129 }
 130
 131 div.content { /* Block element content. */
 132   padding: 0;
 133 }
 134
 135 /* Block element titles. */
 136 div.title, caption.title {
 137   color: #527bbd;
 138   font-family: sans-serif;
 139   font-weight: bold;
 140   text-align: left;
 141   margin-top: 1.0em;
 142   margin-bottom: 0.5em;
 143 }
 144 div.title + * {
 145   margin-top: 0;
 146 }
 147
 148 td div.title:first-child {
 149   margin-top: 0.0em;
 150 }
 151 div.content div.title:first-child {
 152   margin-top: 0.0em;
 153 }
 154 div.content + div.title {
 155   margin-top: 0.0em;
 156 }
 157
 158 div.sidebarblock > div.content {
 159   background: #ffffee;
 160   border: 1px solid silver;
 161   padding: 0.5em;
 162 }
 163
 164 div.listingblock > div.content {
 165   border: 1px solid silver;
 166   background: #f4f4f4;
 167   padding: 0.5em;
 168 }
 169
 170 div.quoteblock, div.verseblock {
 171   padding-left: 1.0em;
 172   margin-left: 1.0em;
 173   margin-right: 10%;
 174   border-left: 5px solid #dddddd;
 175   color: #777777;
 176 }
 177
 178 div.quoteblock > div.attribution {
 179   padding-top: 0.5em;
 180   text-align: right;
 181 }
 182
 183 div.verseblock > div.content {
 184   white-space: pre;
 185 }
 186 div.verseblock > div.attribution {
 187   padding-top: 0.75em;
 188   text-align: left;
 189 }
 190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 191 div.verseblock + div.attribution {
 192   text-align: left;
 193 }
 194
 195 div.admonitionblock .icon {
 196   vertical-align: top;
 197   font-size: 1.1em;
 198   font-weight: bold;
 199   text-decoration: underline;
 200   color: #527bbd;
 201   padding-right: 0.5em;
 202 }
 203 div.admonitionblock td.content {
 204   padding-left: 0.5em;
 205   border-left: 3px solid #dddddd;
 206 }
 207
 208 div.exampleblock > div.content {
 209   border-left: 3px solid #dddddd;
 210   padding-left: 0.5em;
 211 }
 212
 213 div.imageblock div.content { padding-left: 0; }
 214 span.image img { border-style: none; }
 215 a.image:visited { color: white; }
 216
 217 dl {
 218   margin-top: 0.8em;
 219   margin-bottom: 0.8em;
 220 }
 221 dt {
 222   margin-top: 0.5em;
 223   margin-bottom: 0;
 224   font-style: normal;
 225   color: navy;
 226 }
 227 dd > *:first-child {
 228   margin-top: 0.1em;
 229 }
 230
 231 ul, ol {
 232     list-style-position: outside;
 233 }
 234 ol.arabic {
 235   list-style-type: decimal;
 236 }
 237 ol.loweralpha {
 238   list-style-type: lower-alpha;
 239 }
 240 ol.upperalpha {
 241   list-style-type: upper-alpha;
 242 }
 243 ol.lowerroman {
 244   list-style-type: lower-roman;
 245 }
 246 ol.upperroman {
 247   list-style-type: upper-roman;
 248 }
 249
 250 div.compact ul, div.compact ol,
 251 div.compact p, div.compact p,
 252 div.compact div, div.compact div {
 253   margin-top: 0.1em;
 254   margin-bottom: 0.1em;
 255 }
 256
 257 div.tableblock > table {
 258   border: 3px solid #527bbd;
 259 }
 260 thead, p.table.header {
 261   font-family: sans-serif;
 262   font-weight: bold;
 263 }
 264 tfoot {
 265   font-weight: bold;
 266 }
 267 td > div.verse {
 268   white-space: pre;
 269 }
 270 p.table {
 271   margin-top: 0;
 272 }
 273 /* Because the table frame attribute is overriden by CSS in most browsers. */
 274 div.tableblock > table[frame="void"] {
 275   border-style: none;
 276 }
 277 div.tableblock > table[frame="hsides"] {
 278   border-left-style: none;
 279   border-right-style: none;
 280 }
 281 div.tableblock > table[frame="vsides"] {
 282   border-top-style: none;
 283   border-bottom-style: none;
 284 }
 285
 286
 287 div.hdlist {
 288   margin-top: 0.8em;
 289   margin-bottom: 0.8em;
 290 }
 291 div.hdlist tr {
 292   padding-bottom: 15px;
 293 }
 294 dt.hdlist1.strong, td.hdlist1.strong {
 295   font-weight: bold;
 296 }
 297 td.hdlist1 {
 298   vertical-align: top;
 299   font-style: normal;
 300   padding-right: 0.8em;
 301   color: navy;
 302 }
 303 td.hdlist2 {
 304   vertical-align: top;
 305 }
 306 div.hdlist.compact tr {
 307   margin: 0;
 308   padding-bottom: 0;
 309 }
 310
 311 .comment {
 312   background: yellow;
 313 }
 314
 315 .footnote, .footnoteref {
 316   font-size: 0.8em;
 317 }
 318
 319 span.footnote, span.footnoteref {
 320   vertical-align: super;
 321 }
 322
 323 #footnotes {
 324   margin: 20px 0 20px 0;
 325   padding: 7px 0 0 0;
 326 }
 327
 328 #footnotes div.footnote {
 329   margin: 0 0 5px 0;
 330 }
 331
 332 #footnotes hr {
 333   border: none;
 334   border-top: 1px solid silver;
 335   height: 1px;
 336   text-align: left;
 337   margin-left: 0;
 338   width: 20%;
 339   min-width: 100px;
 340 }
 341
 342
 343 @media print {
 344   div#footer-badges { display: none; }
 345 }
 346
 347 div#toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 div#toctitle {
 352   color: #527bbd;
 353   font-family: sans-serif;
 354   font-size: 1.1em;
 355   font-weight: bold;
 356   margin-top: 1.0em;
 357   margin-bottom: 0.1em;
 358 }
 359
 360 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 361   margin-top: 0;
 362   margin-bottom: 0;
 363 }
 364 div.toclevel2 {
 365   margin-left: 2em;
 366   font-size: 0.9em;
 367 }
 368 div.toclevel3 {
 369   margin-left: 4em;
 370   font-size: 0.9em;
 371 }
 372 div.toclevel4 {
 373   margin-left: 6em;
 374   font-size: 0.9em;
 375 }
 376 /* Workarounds for IE6's broken and incomplete CSS2. */
 377
 378 div.sidebar-content {
 379   background: #ffffee;
 380   border: 1px solid silver;
 381   padding: 0.5em;
 382 }
 383 div.sidebar-title, div.image-title {
 384   color: #527bbd;
 385   font-family: sans-serif;
 386   font-weight: bold;
 387   margin-top: 0.0em;
 388   margin-bottom: 0.5em;
 389 }
 390
 391 div.listingblock div.content {
 392   border: 1px solid silver;
 393   background: #f4f4f4;
 394   padding: 0.5em;
 395 }
 396
 397 div.quoteblock-attribution {
 398   padding-top: 0.5em;
 399   text-align: right;
 400 }
 401
 402 div.verseblock-content {
 403   white-space: pre;
 404 }
 405 div.verseblock-attribution {
 406   padding-top: 0.75em;
 407   text-align: left;
 408 }
 409
 410 div.exampleblock-content {
 411   border-left: 3px solid #dddddd;
 412   padding-left: 0.5em;
 413 }
 414
 415 /* IE6 sets dynamically generated links as visited. */
 416 div#toc a:visited { color: blue; }
 417 </style>
 418 <script type="text/javascript">
 419 /*<![CDATA[*/
 420 window.onload = function(){asciidoc.footnotes();}
 421 var asciidoc = {  // Namespace.
 422
 423 /////////////////////////////////////////////////////////////////////
 424 // Table Of Contents generator
 425 /////////////////////////////////////////////////////////////////////
 426
 427 /* Author: Mihai Bazon, September 2002
 428  * http://students.infoiasi.ro/~mishoo
 429  *
 430  * Table Of Content generator
 431  * Version: 0.4
 432  *
 433  * Feel free to use this script under the terms of the GNU General Public
 434  * License, as long as you do not remove or alter this notice.
 435  */
 436
 437  /* modified by Troy D. Hanson, September 2006. License: GPL */
 438  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 439
 440 // toclevels = 1..4.
 441 toc: function (toclevels) {
 442
 443   function getText(el) {
 444     var text = "";
 445     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 446       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 447         text += i.data;
 448       else if (i.firstChild != null)
 449         text += getText(i);
 450     }
 451     return text;
 452   }
 453
 454   function TocEntry(el, text, toclevel) {
 455     this.element = el;
 456     this.text = text;
 457     this.toclevel = toclevel;
 458   }
 459
 460   function tocEntries(el, toclevels) {
 461     var result = new Array;
 462     var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
 463     // Function that scans the DOM tree for header elements (the DOM2
 464     // nodeIterator API would be a better technique but not supported by all
 465     // browsers).
 466     var iterate = function (el) {
 467       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 468         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 469           var mo = re.exec(i.tagName);
 470           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 471             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 472           }
 473           iterate(i);
 474         }
 475       }
 476     }
 477     iterate(el);
 478     return result;
 479   }
 480
 481   var toc = document.getElementById("toc");
 482   var entries = tocEntries(document.getElementById("content"), toclevels);
 483   for (var i = 0; i < entries.length; ++i) {
 484     var entry = entries[i];
 485     if (entry.element.id == "")
 486       entry.element.id = "_toc_" + i;
 487     var a = document.createElement("a");
 488     a.href = "#" + entry.element.id;
 489     a.appendChild(document.createTextNode(entry.text));
 490     var div = document.createElement("div");
 491     div.appendChild(a);
 492     div.className = "toclevel" + entry.toclevel;
 493     toc.appendChild(div);
 494   }
 495   if (entries.length == 0)
 496     toc.parentNode.removeChild(toc);
 497 },
 498
 499
 500 /////////////////////////////////////////////////////////////////////
 501 // Footnotes generator
 502 /////////////////////////////////////////////////////////////////////
 503
 504 /* Based on footnote generation code from:
 505  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 506  */
 507
 508 footnotes: function () {
 509   var cont = document.getElementById("content");
 510   var noteholder = document.getElementById("footnotes");
 511   var spans = cont.getElementsByTagName("span");
 512   var refs = {};
 513   var n = 0;
 514   for (i=0; i<spans.length; i++) {
 515     if (spans[i].className == "footnote") {
 516       n++;
 517       // Use [\s\S] in place of . so multi-line matches work.
 518       // Because JavaScript has no s (dotall) regex flag.
 519       note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 520       noteholder.innerHTML +=
 521         "<div class='footnote' id='_footnote_" + n + "'>" +
 522         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 523         n + "</a>. " + note + "</div>";
 524       spans[i].innerHTML =
 525         "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 526         "' title='View footnote' class='footnote'>" + n + "</a>]";
 527       var id =spans[i].getAttribute("id");
 528       if (id != null) refs["#"+id] = n;
 529     }
 530   }
 531   if (n == 0)
 532     noteholder.parentNode.removeChild(noteholder);
 533   else {
 534     // Process footnoterefs.
 535     for (i=0; i<spans.length; i++) {
 536       if (spans[i].className == "footnoteref") {
 537         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 538         href = href.match(/#.*/)[0];  // Because IE return full URL.
 539         n = refs[href];
 540         spans[i].innerHTML =
 541           "[<a href='#_footnote_" + n +
 542           "' title='View footnote' class='footnote'>" + n + "</a>]";
 543       }
 544     }
 545   }
 546 }
 547
 548 }
 549 /*]]>*/
 550 </script>
 551 </head>
 552 <body>
 553 <div id="header">
 554 <h1>parse-options API</h1>
 555 </div>
 556 <div id="content">
 557 <div id="preamble">
 558 <div class="sectionbody">
 559 <div class="paragraph"><p>The parse-options API is used to parse and massage options in git
 560 and to provide a usage help with consistent look.</p></div>
 561 </div>
 562 </div>
 563 <h2 id="_basics">Basics</h2>
 564 <div class="sectionbody">
 565 <div class="paragraph"><p>The argument vector <tt>argv[]</tt> may usually contain mandatory or optional
 566 <em>non-option arguments</em>, e.g. a filename or a branch, and <em>options</em>.
 567 Options are optional arguments that start with a dash and
 568 that allow to change the behavior of a command.</p></div>
 569 <div class="ulist"><ul>
 570 <li>
 571 <p>
 572 There are basically three types of options:
 573   <em>boolean</em> options,
 574   options with (mandatory) <em>arguments</em> and
 575   options with <em>optional arguments</em>
 576   (i.e. a boolean option that can be adjusted).
 577 </p>
 578 </li>
 579 <li>
 580 <p>
 581 There are basically two forms of options:
 582   <em>Short options</em> consist of one dash (<tt>-</tt>) and one alphanumeric
 583   character.
 584   <em>Long options</em> begin with two dashes (<tt>--</tt>) and some
 585   alphanumeric characters.
 586 </p>
 587 </li>
 588 <li>
 589 <p>
 590 Options are case-sensitive.
 591   Please define <em>lower-case long options</em> only.
 592 </p>
 593 </li>
 594 </ul></div>
 595 <div class="paragraph"><p>The parse-options API allows:</p></div>
 596 <div class="ulist"><ul>
 597 <li>
 598 <p>
 599 <em>sticked</em> and <em>separate form</em> of options with arguments.
 600   <tt>-oArg</tt> is sticked, <tt>-o Arg</tt> is separate form.
 601   <tt>--option=Arg</tt> is sticked, <tt>--option Arg</tt> is separate form.
 602 </p>
 603 </li>
 604 <li>
 605 <p>
 606 Long options may be <em>abbreviated</em>, as long as the abbreviation
 607   is unambiguous.
 608 </p>
 609 </li>
 610 <li>
 611 <p>
 612 Short options may be bundled, e.g. <tt>-a -b</tt> can be specified as <tt>-ab</tt>.
 613 </p>
 614 </li>
 615 <li>
 616 <p>
 617 Boolean long options can be <em>negated</em> (or <em>unset</em>) by prepending
 618   <tt>no-</tt>, e.g. <tt>--no-abbrev</tt> instead of <tt>--abbrev</tt>.
 619 </p>
 620 </li>
 621 <li>
 622 <p>
 623 Options and non-option arguments can clearly be separated using the <tt>--</tt>
 624   option, e.g. <tt>-a -b --option -- --this-is-a-file</tt> indicates that
 625   <tt>--this-is-a-file</tt> must not be processed as an option.
 626 </p>
 627 </li>
 628 </ul></div>
 629 </div>
 630 <h2 id="_steps_to_parse_options">Steps to parse options</h2>
 631 <div class="sectionbody">
 632 <div class="olist arabic"><ol class="arabic">
 633 <li>
 634 <p>
 635 <tt>#include "parse-options.h"</tt>
 636 </p>
 637 </li>
 638 <li>
 639 <p>
 640 define a NULL-terminated
 641   <tt>static const char * const builtin_foo_usage[]</tt> array
 642   containing alternative usage strings
 643 </p>
 644 </li>
 645 <li>
 646 <p>
 647 define <tt>builtin_foo_options</tt> array as described below
 648   in section <em>Data Structure</em>.
 649 </p>
 650 </li>
 651 <li>
 652 <p>
 653 in <tt>cmd_foo(int argc, const char **argv, const char *prefix)</tt>
 654   call
 655 </p>
 656 <div class="literalblock">
 657 <div class="content">
 658 <pre><tt>argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);</tt></pre>
 659 </div></div>
 660 <div class="paragraph"><p><tt>parse_options()</tt> will filter out the processed options of <tt>argv[]</tt> and leave the
 661 non-option arguments in <tt>argv[]</tt>.
 662 <tt>argc</tt> is updated appropriately because of the assignment.</p></div>
 663 <div class="paragraph"><p>You can also pass NULL instead of a usage array as the fifth parameter of
 664 parse_options(), to avoid displaying a help screen with usage info and
 665 option list.  This should only be done if necessary, e.g. to implement
 666 a limited parser for only a subset of the options that needs to be run
 667 before the full parser, which in turn shows the full help message.</p></div>
 668 <div class="paragraph"><p>Flags are the bitwise-or of:</p></div>
 669 <div class="dlist"><dl>
 670 <dt class="hdlist1">
 671 <tt>PARSE_OPT_KEEP_DASHDASH</tt>
 672 </dt>
 673 <dd>
 674 <p>
 675         Keep the <tt>--</tt> that usually separates options from
 676         non-option arguments.
 677 </p>
 678 </dd>
 679 <dt class="hdlist1">
 680 <tt>PARSE_OPT_STOP_AT_NON_OPTION</tt>
 681 </dt>
 682 <dd>
 683 <p>
 684         Usually the whole argument vector is massaged and reordered.
 685         Using this flag, processing is stopped at the first non-option
 686         argument.
 687 </p>
 688 </dd>
 689 <dt class="hdlist1">
 690 <tt>PARSE_OPT_KEEP_ARGV0</tt>
 691 </dt>
 692 <dd>
 693 <p>
 694         Keep the first argument, which contains the program name.  It&#8217;s
 695         removed from argv[] by default.
 696 </p>
 697 </dd>
 698 <dt class="hdlist1">
 699 <tt>PARSE_OPT_KEEP_UNKNOWN</tt>
 700 </dt>
 701 <dd>
 702 <p>
 703         Keep unknown arguments instead of erroring out.  This doesn&#8217;t
 704         work for all combinations of arguments as users might expect
 705         it to do.  E.g. if the first argument in <tt>--unknown --known</tt>
 706         takes a value (which we can&#8217;t know), the second one is
 707         mistakenly interpreted as a known option.  Similarly, if
 708         <tt>PARSE_OPT_STOP_AT_NON_OPTION</tt> is set, the second argument in
 709         <tt>--unknown value</tt> will be mistakenly interpreted as a
 710         non-option, not as a value belonging to the unknown option,
 711         the parser early.  That&#8217;s why parse_options() errors out if
 712         both options are set.
 713 </p>
 714 </dd>
 715 <dt class="hdlist1">
 716 <tt>PARSE_OPT_NO_INTERNAL_HELP</tt>
 717 </dt>
 718 <dd>
 719 <p>
 720         By default, parse_options() handles <tt>-h</tt>, <tt>--help</tt> and
 721         <tt>--help-all</tt> internally, by showing a help screen.  This option
 722         turns it off and allows one to add custom handlers for these
 723         options, or to just leave them unknown.
 724 </p>
 725 </dd>
 726 </dl></div>
 727 </li>
 728 </ol></div>
 729 </div>
 730 <h2 id="_data_structure">Data Structure</h2>
 731 <div class="sectionbody">
 732 <div class="paragraph"><p>The main data structure is an array of the <tt>option</tt> struct,
 733 say <tt>static struct option builtin_add_options[]</tt>.
 734 There are some macros to easily define options:</p></div>
 735 <div class="dlist"><dl>
 736 <dt class="hdlist1">
 737 <tt>OPT__ABBREV(&amp;int_var)</tt>
 738 </dt>
 739 <dd>
 740 <p>
 741         Add <tt>--abbrev[=&lt;n&gt;]</tt>.
 742 </p>
 743 </dd>
 744 <dt class="hdlist1">
 745 <tt>OPT__COLOR(&amp;int_var, description)</tt>
 746 </dt>
 747 <dd>
 748 <p>
 749         Add <tt>--color[=&lt;when&gt;]</tt> and <tt>--no-color</tt>.
 750 </p>
 751 </dd>
 752 <dt class="hdlist1">
 753 <tt>OPT__DRY_RUN(&amp;int_var, description)</tt>
 754 </dt>
 755 <dd>
 756 <p>
 757         Add <tt>-n, --dry-run</tt>.
 758 </p>
 759 </dd>
 760 <dt class="hdlist1">
 761 <tt>OPT__FORCE(&amp;int_var, description)</tt>
 762 </dt>
 763 <dd>
 764 <p>
 765         Add <tt>-f, --force</tt>.
 766 </p>
 767 </dd>
 768 <dt class="hdlist1">
 769 <tt>OPT__QUIET(&amp;int_var, description)</tt>
 770 </dt>
 771 <dd>
 772 <p>
 773         Add <tt>-q, --quiet</tt>.
 774 </p>
 775 </dd>
 776 <dt class="hdlist1">
 777 <tt>OPT__VERBOSE(&amp;int_var, description)</tt>
 778 </dt>
 779 <dd>
 780 <p>
 781         Add <tt>-v, --verbose</tt>.
 782 </p>
 783 </dd>
 784 <dt class="hdlist1">
 785 <tt>OPT_GROUP(description)</tt>
 786 </dt>
 787 <dd>
 788 <p>
 789         Start an option group. <tt>description</tt> is a short string that
 790         describes the group or an empty string.
 791         Start the description with an upper-case letter.
 792 </p>
 793 </dd>
 794 <dt class="hdlist1">
 795 <tt>OPT_BOOLEAN(short, long, &amp;int_var, description)</tt>
 796 </dt>
 797 <dd>
 798 <p>
 799         Introduce a boolean option.
 800         <tt>int_var</tt> is incremented on each use.
 801 </p>
 802 </dd>
 803 <dt class="hdlist1">
 804 <tt>OPT_BIT(short, long, &amp;int_var, description, mask)</tt>
 805 </dt>
 806 <dd>
 807 <p>
 808         Introduce a boolean option.
 809         If used, <tt>int_var</tt> is bitwise-ored with <tt>mask</tt>.
 810 </p>
 811 </dd>
 812 <dt class="hdlist1">
 813 <tt>OPT_NEGBIT(short, long, &amp;int_var, description, mask)</tt>
 814 </dt>
 815 <dd>
 816 <p>
 817         Introduce a boolean option.
 818         If used, <tt>int_var</tt> is bitwise-anded with the inverted <tt>mask</tt>.
 819 </p>
 820 </dd>
 821 <dt class="hdlist1">
 822 <tt>OPT_SET_INT(short, long, &amp;int_var, description, integer)</tt>
 823 </dt>
 824 <dd>
 825 <p>
 826         Introduce a boolean option.
 827         If used, set <tt>int_var</tt> to <tt>integer</tt>.
 828 </p>
 829 </dd>
 830 <dt class="hdlist1">
 831 <tt>OPT_SET_PTR(short, long, &amp;ptr_var, description, ptr)</tt>
 832 </dt>
 833 <dd>
 834 <p>
 835         Introduce a boolean option.
 836         If used, set <tt>ptr_var</tt> to <tt>ptr</tt>.
 837 </p>
 838 </dd>
 839 <dt class="hdlist1">
 840 <tt>OPT_STRING(short, long, &amp;str_var, arg_str, description)</tt>
 841 </dt>
 842 <dd>
 843 <p>
 844         Introduce an option with string argument.
 845         The string argument is put into <tt>str_var</tt>.
 846 </p>
 847 </dd>
 848 <dt class="hdlist1">
 849 <tt>OPT_INTEGER(short, long, &amp;int_var, description)</tt>
 850 </dt>
 851 <dd>
 852 <p>
 853         Introduce an option with integer argument.
 854         The integer is put into <tt>int_var</tt>.
 855 </p>
 856 </dd>
 857 <dt class="hdlist1">
 858 <tt>OPT_DATE(short, long, &amp;int_var, description)</tt>
 859 </dt>
 860 <dd>
 861 <p>
 862         Introduce an option with date argument, see <tt>approxidate()</tt>.
 863         The timestamp is put into <tt>int_var</tt>.
 864 </p>
 865 </dd>
 866 <dt class="hdlist1">
 867 <tt>OPT_CALLBACK(short, long, &amp;var, arg_str, description, func_ptr)</tt>
 868 </dt>
 869 <dd>
 870 <p>
 871         Introduce an option with argument.
 872         The argument will be fed into the function given by <tt>func_ptr</tt>
 873         and the result will be put into <tt>var</tt>.
 874         See <em>Option Callbacks</em> below for a more elaborate description.
 875 </p>
 876 </dd>
 877 <dt class="hdlist1">
 878 <tt>OPT_FILENAME(short, long, &amp;var, description)</tt>
 879 </dt>
 880 <dd>
 881 <p>
 882         Introduce an option with a filename argument.
 883         The filename will be prefixed by passing the filename along with
 884         the prefix argument of <tt>parse_options()</tt> to <tt>prefix_filename()</tt>.
 885 </p>
 886 </dd>
 887 <dt class="hdlist1">
 888 <tt>OPT_ARGUMENT(long, description)</tt>
 889 </dt>
 890 <dd>
 891 <p>
 892         Introduce a long-option argument that will be kept in <tt>argv[]</tt>.
 893 </p>
 894 </dd>
 895 <dt class="hdlist1">
 896 <tt>OPT_NUMBER_CALLBACK(&amp;var, description, func_ptr)</tt>
 897 </dt>
 898 <dd>
 899 <p>
 900         Recognize numerical options like -123 and feed the integer as
 901         if it was an argument to the function given by <tt>func_ptr</tt>.
 902         The result will be put into <tt>var</tt>.  There can be only one such
 903         option definition.  It cannot be negated and it takes no
 904         arguments.  Short options that happen to be digits take
 905         precedence over it.
 906 </p>
 907 </dd>
 908 <dt class="hdlist1">
 909 <tt>OPT_COLOR_FLAG(short, long, &amp;int_var, description)</tt>
 910 </dt>
 911 <dd>
 912 <p>
 913         Introduce an option that takes an optional argument that can
 914         have one of three values: "always", "never", or "auto".  If the
 915         argument is not given, it defaults to "always".  The <tt>--no-</tt> form
 916         works like <tt>--long=never</tt>; it cannot take an argument.  If
 917         "always", set <tt>int_var</tt> to 1; if "never", set <tt>int_var</tt> to 0; if
 918         "auto", set <tt>int_var</tt> to 1 if stdout is a tty or a pager,
 919         0 otherwise.
 920 </p>
 921 </dd>
 922 </dl></div>
 923 <div class="paragraph"><p>The last element of the array must be <tt>OPT_END()</tt>.</p></div>
 924 <div class="paragraph"><p>If not stated otherwise, interpret the arguments as follows:</p></div>
 925 <div class="ulist"><ul>
 926 <li>
 927 <p>
 928 <tt>short</tt> is a character for the short option
 929   (e.g. <tt>&#39;e&#39;</tt> for <tt>-e</tt>, use <tt>0</tt> to omit),
 930 </p>
 931 </li>
 932 <li>
 933 <p>
 934 <tt>long</tt> is a string for the long option
 935   (e.g. <tt>"example"</tt> for <tt>--example</tt>, use <tt>NULL</tt> to omit),
 936 </p>
 937 </li>
 938 <li>
 939 <p>
 940 <tt>int_var</tt> is an integer variable,
 941 </p>
 942 </li>
 943 <li>
 944 <p>
 945 <tt>str_var</tt> is a string variable (<tt>char *</tt>),
 946 </p>
 947 </li>
 948 <li>
 949 <p>
 950 <tt>arg_str</tt> is the string that is shown as argument
 951   (e.g. <tt>"branch"</tt> will result in <tt>&lt;branch&gt;</tt>).
 952   If set to <tt>NULL</tt>, three dots (<tt>&#8230;</tt>) will be displayed.
 953 </p>
 954 </li>
 955 <li>
 956 <p>
 957 <tt>description</tt> is a short string to describe the effect of the option.
 958   It shall begin with a lower-case letter and a full stop (<tt>.</tt>) shall be
 959   omitted at the end.
 960 </p>
 961 </li>
 962 </ul></div>
 963 </div>
 964 <h2 id="_option_callbacks">Option Callbacks</h2>
 965 <div class="sectionbody">
 966 <div class="paragraph"><p>The function must be defined in this form:</p></div>
 967 <div class="literalblock">
 968 <div class="content">
 969 <pre><tt>int func(const struct option *opt, const char *arg, int unset)</tt></pre>
 970 </div></div>
 971 <div class="paragraph"><p>The callback mechanism is as follows:</p></div>
 972 <div class="ulist"><ul>
 973 <li>
 974 <p>
 975 Inside <tt>func</tt>, the only interesting member of the structure
 976   given by <tt>opt</tt> is the void pointer <tt>opt-&gt;value</tt>.
 977   <tt>*opt-&gt;value</tt> will be the value that is saved into <tt>var</tt>, if you
 978   use <tt>OPT_CALLBACK()</tt>.
 979   For example, do <tt>*(unsigned long *)opt-&gt;value = 42;</tt> to get 42
 980   into an <tt>unsigned long</tt> variable.
 981 </p>
 982 </li>
 983 <li>
 984 <p>
 985 Return value <tt>0</tt> indicates success and non-zero return
 986   value will invoke <tt>usage_with_options()</tt> and, thus, die.
 987 </p>
 988 </li>
 989 <li>
 990 <p>
 991 If the user negates the option, <tt>arg</tt> is <tt>NULL</tt> and <tt>unset</tt> is 1.
 992 </p>
 993 </li>
 994 </ul></div>
 995 </div>
 996 <h2 id="_sophisticated_option_parsing">Sophisticated option parsing</h2>
 997 <div class="sectionbody">
 998 <div class="paragraph"><p>If you need, for example, option callbacks with optional arguments
 999 or without arguments at all, or if you need other special cases,
1000 that are not handled by the macros above, you need to specify the
1001 members of the <tt>option</tt> structure manually.</p></div>
1002 <div class="paragraph"><p>This is not covered in this document, but well documented
1003 in <tt>parse-options.h</tt> itself.</p></div>
1004 </div>
1005 <h2 id="_examples">Examples</h2>
1006 <div class="sectionbody">
1007 <div class="paragraph"><p>See <tt>test-parse-options.c</tt> and
1008 <tt>builtin-add.c</tt>,
1009 <tt>builtin-clone.c</tt>,
1010 <tt>builtin-commit.c</tt>,
1011 <tt>builtin-fetch.c</tt>,
1012 <tt>builtin-fsck.c</tt>,
1013 <tt>builtin-rm.c</tt>
1014 for real-world examples.</p></div>
1015 </div>
1016 </div>
1017 <div id="footnotes"><hr /></div>
1018 <div id="footer">
1019 <div id="footer-text">
1020 Last updated 2011-09-21 23:01:14 PDT
1021 </div>
1022 </div>
1023 </body>
1024 </html>