Google Git
Sign in
chromium / external / gitster / git-htmldocs / bcd98f41a1bf21a71ee80e4b1f381e1290909b66 / . / technical / api-parse-options.html
blob: eb8f7ffa821b72af08b2e38c4147df08e7555feb [file] [log] [blame]
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]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>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]5<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]6<meta name="generator" content="AsciiDoc 8.6.9" />
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]7<title>parse-options API</title>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]8<style type="text/css">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]9/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
10
11/* Default font. */
12body {
13 font-family: Georgia,serif;
14}
15
16/* Title font. */
17h1, h2, h3, h4, h5, h6,
18div.title, caption.title,
19thead, p.table.header,
20#toctitle,
21#author, #revnumber, #revdate, #revremark,
22#footer {
23 font-family: Arial,Helvetica,sans-serif;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]24}
25
26body {
27 margin: 1em 5% 1em 5%;
28}
29
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]30a {
31 color: blue;
32 text-decoration: underline;
33}
34a:visited {
35 color: fuchsia;
36}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]37
38em {
39 font-style: italic;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]40 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]41}
42
43strong {
44 font-weight: bold;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]45 color: #083194;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]46}
47
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]48h1, h2, h3, h4, h5, h6 {
49 color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]50 margin-top: 1.2em;
51 margin-bottom: 0.5em;
52 line-height: 1.3;
53}
54
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]55h1, h2, h3 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]56 border-bottom: 2px solid silver;
57}
58h2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]59 padding-top: 0.5em;
60}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]61h3 {
62 float: left;
63}
64h3 + * {
65 clear: left;
66}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]67h5 {
68 font-size: 1.0em;
69}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]70
71div.sectionbody {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]72 margin-left: 0;
73}
74
75hr {
76 border: 1px solid silver;
77}
78
79p {
80 margin-top: 0.5em;
81 margin-bottom: 0.5em;
82}
83
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]84ul, ol, li > p {
85 margin-top: 0;
86}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]87ul > li { color: #aaa; }
88ul > li > * { color: black; }
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]89
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]90.monospaced, code, pre {
91 font-family: "Courier New", Courier, monospace;
92 font-size: inherit;
93 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]94 padding: 0;
95 margin: 0;
96}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]97pre {
98 white-space: pre-wrap;
99}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]100
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]101#author {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]102 color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]103 font-weight: bold;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]104 font-size: 1.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]105}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]106#email {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]107}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]108#revnumber, #revdate, #revremark {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]109}
110
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]111#footer {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]112 font-size: small;
113 border-top: 2px solid silver;
114 padding-top: 0.5em;
115 margin-top: 4.0em;
116}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]117#footer-text {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]118 float: left;
119 padding-bottom: 0.5em;
120}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]121#footer-badges {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]122 float: right;
123 padding-bottom: 0.5em;
124}
125
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]126#preamble {
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]127 margin-top: 1.5em;
128 margin-bottom: 1.5em;
129}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]130div.imageblock, div.exampleblock, div.verseblock,
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]131div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
132div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]133 margin-top: 1.0em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]134 margin-bottom: 1.5em;
135}
136div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]137 margin-top: 2.0em;
138 margin-bottom: 2.0em;
139 margin-right: 10%;
140 color: #606060;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]141}
142
143div.content { /* Block element content. */
144 padding: 0;
145}
146
147/* Block element titles. */
148div.title, caption.title {
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]149 color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]150 font-weight: bold;
151 text-align: left;
152 margin-top: 1.0em;
153 margin-bottom: 0.5em;
154}
155div.title + * {
156 margin-top: 0;
157}
158
159td div.title:first-child {
160 margin-top: 0.0em;
161}
162div.content div.title:first-child {
163 margin-top: 0.0em;
164}
165div.content + div.title {
166 margin-top: 0.0em;
167}
168
169div.sidebarblock > div.content {
170 background: #ffffee;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]171 border: 1px solid #dddddd;
172 border-left: 4px solid #f0f0f0;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]173 padding: 0.5em;
174}
175
176div.listingblock > div.content {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]177 border: 1px solid #dddddd;
178 border-left: 5px solid #f0f0f0;
179 background: #f8f8f8;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]180 padding: 0.5em;
181}
182
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]183div.quoteblock, div.verseblock {
184 padding-left: 1.0em;
185 margin-left: 1.0em;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]186 margin-right: 10%;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]187 border-left: 5px solid #f0f0f0;
188 color: #888;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]189}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]190
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]191div.quoteblock > div.attribution {
192 padding-top: 0.5em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]193 text-align: right;
194}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]195
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]196div.verseblock > pre.content {
197 font-family: inherit;
198 font-size: inherit;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]199}
200div.verseblock > div.attribution {
201 padding-top: 0.75em;
202 text-align: left;
203}
204/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]205div.verseblock + div.attribution {
206 text-align: left;
207}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]208
209div.admonitionblock .icon {
210 vertical-align: top;
211 font-size: 1.1em;
212 font-weight: bold;
213 text-decoration: underline;
214 color: #527bbd;
215 padding-right: 0.5em;
216}
217div.admonitionblock td.content {
218 padding-left: 0.5em;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]219 border-left: 3px solid #dddddd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]220}
221
222div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]223 border-left: 3px solid #dddddd;
224 padding-left: 0.5em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]225}
226
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]227div.imageblock div.content { padding-left: 0; }
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]228span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]229a.image:visited { color: white; }
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]230
231dl {
232 margin-top: 0.8em;
233 margin-bottom: 0.8em;
234}
235dt {
236 margin-top: 0.5em;
237 margin-bottom: 0;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]238 font-style: normal;
239 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]240}
241dd > *:first-child {
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]242 margin-top: 0.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]243}
244
245ul, ol {
246 list-style-position: outside;
247}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]248ol.arabic {
249 list-style-type: decimal;
250}
251ol.loweralpha {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]252 list-style-type: lower-alpha;
253}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]254ol.upperalpha {
255 list-style-type: upper-alpha;
256}
257ol.lowerroman {
258 list-style-type: lower-roman;
259}
260ol.upperroman {
261 list-style-type: upper-roman;
262}
263
264div.compact ul, div.compact ol,
265div.compact p, div.compact p,
266div.compact div, div.compact div {
267 margin-top: 0.1em;
268 margin-bottom: 0.1em;
269}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]270
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]271tfoot {
272 font-weight: bold;
273}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]274td > div.verse {
275 white-space: pre;
276}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]277
278div.hdlist {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]279 margin-top: 0.8em;
280 margin-bottom: 0.8em;
281}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]282div.hdlist tr {
283 padding-bottom: 15px;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]284}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]285dt.hdlist1.strong, td.hdlist1.strong {
286 font-weight: bold;
287}
288td.hdlist1 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]289 vertical-align: top;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]290 font-style: normal;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]291 padding-right: 0.8em;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]292 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]293}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]294td.hdlist2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]295 vertical-align: top;
296}
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]297div.hdlist.compact tr {
298 margin: 0;
299 padding-bottom: 0;
300}
301
302.comment {
303 background: yellow;
304}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]305
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]306.footnote, .footnoteref {
307 font-size: 0.8em;
308}
309
310span.footnote, span.footnoteref {
311 vertical-align: super;
312}
313
314#footnotes {
315 margin: 20px 0 20px 0;
316 padding: 7px 0 0 0;
317}
318
319#footnotes div.footnote {
320 margin: 0 0 5px 0;
321}
322
323#footnotes hr {
324 border: none;
325 border-top: 1px solid silver;
326 height: 1px;
327 text-align: left;
328 margin-left: 0;
329 width: 20%;
330 min-width: 100px;
331}
332
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]333div.colist td {
334 padding-right: 0.5em;
335 padding-bottom: 0.3em;
336 vertical-align: top;
337}
338div.colist td img {
339 margin-top: 0.3em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]340}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]341
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]342@media print {
343 #footer-badges { display: none; }
344}
345
346#toc {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]347 margin-bottom: 2.5em;
348}
349
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]350#toctitle {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]351 color: #527bbd;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]352 font-size: 1.1em;
353 font-weight: bold;
354 margin-top: 1.0em;
355 margin-bottom: 0.1em;
356}
357
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]358div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]359 margin-top: 0;
360 margin-bottom: 0;
361}
362div.toclevel2 {
363 margin-left: 2em;
364 font-size: 0.9em;
365}
366div.toclevel3 {
367 margin-left: 4em;
368 font-size: 0.9em;
369}
370div.toclevel4 {
371 margin-left: 6em;
372 font-size: 0.9em;
373}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]374
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]375span.aqua { color: aqua; }
376span.black { color: black; }
377span.blue { color: blue; }
378span.fuchsia { color: fuchsia; }
379span.gray { color: gray; }
380span.green { color: green; }
381span.lime { color: lime; }
382span.maroon { color: maroon; }
383span.navy { color: navy; }
384span.olive { color: olive; }
385span.purple { color: purple; }
386span.red { color: red; }
387span.silver { color: silver; }
388span.teal { color: teal; }
389span.white { color: white; }
390span.yellow { color: yellow; }
391
392span.aqua-background { background: aqua; }
393span.black-background { background: black; }
394span.blue-background { background: blue; }
395span.fuchsia-background { background: fuchsia; }
396span.gray-background { background: gray; }
397span.green-background { background: green; }
398span.lime-background { background: lime; }
399span.maroon-background { background: maroon; }
400span.navy-background { background: navy; }
401span.olive-background { background: olive; }
402span.purple-background { background: purple; }
403span.red-background { background: red; }
404span.silver-background { background: silver; }
405span.teal-background { background: teal; }
406span.white-background { background: white; }
407span.yellow-background { background: yellow; }
408
409span.big { font-size: 2em; }
410span.small { font-size: 0.6em; }
411
412span.underline { text-decoration: underline; }
413span.overline { text-decoration: overline; }
414span.line-through { text-decoration: line-through; }
415
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]416div.unbreakable { page-break-inside: avoid; }
417
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]418
419/*
420 * xhtml11 specific
421 *
422 * */
423
424div.tableblock {
425 margin-top: 1.0em;
426 margin-bottom: 1.5em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]427}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]428div.tableblock > table {
429 border: 3px solid #527bbd;
430}
431thead, p.table.header {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]432 font-weight: bold;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]433 color: #527bbd;
434}
435p.table {
436 margin-top: 0;
437}
438/* Because the table frame attribute is overriden by CSS in most browsers. */
439div.tableblock > table[frame="void"] {
440 border-style: none;
441}
442div.tableblock > table[frame="hsides"] {
443 border-left-style: none;
444 border-right-style: none;
445}
446div.tableblock > table[frame="vsides"] {
447 border-top-style: none;
448 border-bottom-style: none;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]449}
450
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]451
452/*
453 * html5 specific
454 *
455 * */
456
457table.tableblock {
458 margin-top: 1.0em;
459 margin-bottom: 1.5em;
460}
461thead, p.tableblock.header {
462 font-weight: bold;
463 color: #527bbd;
464}
465p.tableblock {
466 margin-top: 0;
467}
468table.tableblock {
469 border-width: 3px;
470 border-spacing: 0px;
471 border-style: solid;
472 border-color: #527bbd;
473 border-collapse: collapse;
474}
475th.tableblock, td.tableblock {
476 border-width: 1px;
477 padding: 4px;
478 border-style: solid;
479 border-color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]480}
481
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]482table.tableblock.frame-topbot {
483 border-left-style: hidden;
484 border-right-style: hidden;
485}
486table.tableblock.frame-sides {
487 border-top-style: hidden;
488 border-bottom-style: hidden;
489}
490table.tableblock.frame-none {
491 border-style: hidden;
492}
493
494th.tableblock.halign-left, td.tableblock.halign-left {
495 text-align: left;
496}
497th.tableblock.halign-center, td.tableblock.halign-center {
498 text-align: center;
499}
500th.tableblock.halign-right, td.tableblock.halign-right {
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]501 text-align: right;
502}
503
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]504th.tableblock.valign-top, td.tableblock.valign-top {
505 vertical-align: top;
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]506}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]507th.tableblock.valign-middle, td.tableblock.valign-middle {
508 vertical-align: middle;
509}
510th.tableblock.valign-bottom, td.tableblock.valign-bottom {
511 vertical-align: bottom;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]512}
513
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]514
515/*
516 * manpage specific
517 *
518 * */
519
520body.manpage h1 {
521 padding-top: 0.5em;
522 padding-bottom: 0.5em;
523 border-top: 2px solid silver;
524 border-bottom: 2px solid silver;
525}
526body.manpage h2 {
527 border-style: none;
528}
529body.manpage div.sectionbody {
530 margin-left: 3em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]531}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]532
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]533@media print {
534 body.manpage div#toc { display: none; }
535}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]536
537
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]538</style>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]539<script type="text/javascript">
540/*<![CDATA[*/
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]541var asciidoc = { // Namespace.
542
543/////////////////////////////////////////////////////////////////////
544// Table Of Contents generator
545/////////////////////////////////////////////////////////////////////
546
547/* Author: Mihai Bazon, September 2002
548 * http://students.infoiasi.ro/~mishoo
549 *
550 * Table Of Content generator
551 * Version: 0.4
552 *
553 * Feel free to use this script under the terms of the GNU General Public
554 * License, as long as you do not remove or alter this notice.
555 */
556
557 /* modified by Troy D. Hanson, September 2006. License: GPL */
558 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
559
560// toclevels = 1..4.
561toc: function (toclevels) {
562
563 function getText(el) {
564 var text = "";
565 for (var i = el.firstChild; i != null; i = i.nextSibling) {
566 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
567 text += i.data;
568 else if (i.firstChild != null)
569 text += getText(i);
570 }
571 return text;
572 }
573
574 function TocEntry(el, text, toclevel) {
575 this.element = el;
576 this.text = text;
577 this.toclevel = toclevel;
578 }
579
580 function tocEntries(el, toclevels) {
581 var result = new Array;
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]583 // Function that scans the DOM tree for header elements (the DOM2
584 // nodeIterator API would be a better technique but not supported by all
585 // browsers).
586 var iterate = function (el) {
587 for (var i = el.firstChild; i != null; i = i.nextSibling) {
588 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
589 var mo = re.exec(i.tagName);
590 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
591 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
592 }
593 iterate(i);
594 }
595 }
596 }
597 iterate(el);
598 return result;
599 }
600
601 var toc = document.getElementById("toc");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]602 if (!toc) {
603 return;
604 }
605
606 // Delete existing TOC entries in case we're reloading the TOC.
607 var tocEntriesToRemove = [];
608 var i;
609 for (i = 0; i < toc.childNodes.length; i++) {
610 var entry = toc.childNodes[i];
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]611 if (entry.nodeName.toLowerCase() == 'div'
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]612 && entry.getAttribute("class")
613 && entry.getAttribute("class").match(/^toclevel/))
614 tocEntriesToRemove.push(entry);
615 }
616 for (i = 0; i < tocEntriesToRemove.length; i++) {
617 toc.removeChild(tocEntriesToRemove[i]);
618 }
619
620 // Rebuild TOC entries.
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]621 var entries = tocEntries(document.getElementById("content"), toclevels);
622 for (var i = 0; i < entries.length; ++i) {
623 var entry = entries[i];
624 if (entry.element.id == "")
625 entry.element.id = "_toc_" + i;
626 var a = document.createElement("a");
627 a.href = "#" + entry.element.id;
628 a.appendChild(document.createTextNode(entry.text));
629 var div = document.createElement("div");
630 div.appendChild(a);
631 div.className = "toclevel" + entry.toclevel;
632 toc.appendChild(div);
633 }
634 if (entries.length == 0)
635 toc.parentNode.removeChild(toc);
636},
637
638
639/////////////////////////////////////////////////////////////////////
640// Footnotes generator
641/////////////////////////////////////////////////////////////////////
642
643/* Based on footnote generation code from:
644 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
645 */
646
647footnotes: function () {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]648 // Delete existing footnote entries in case we're reloading the footnodes.
649 var i;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]650 var noteholder = document.getElementById("footnotes");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]651 if (!noteholder) {
652 return;
653 }
654 var entriesToRemove = [];
655 for (i = 0; i < noteholder.childNodes.length; i++) {
656 var entry = noteholder.childNodes[i];
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]658 entriesToRemove.push(entry);
659 }
660 for (i = 0; i < entriesToRemove.length; i++) {
661 noteholder.removeChild(entriesToRemove[i]);
662 }
663
664 // Rebuild footnote entries.
665 var cont = document.getElementById("content");
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]666 var spans = cont.getElementsByTagName("span");
667 var refs = {};
668 var n = 0;
669 for (i=0; i<spans.length; i++) {
670 if (spans[i].className == "footnote") {
671 n++;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]672 var note = spans[i].getAttribute("data-note");
673 if (!note) {
674 // Use [\s\S] in place of . so multi-line matches work.
675 // Because JavaScript has no s (dotall) regex flag.
676 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
677 spans[i].innerHTML =
678 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
679 "' title='View footnote' class='footnote'>" + n + "</a>]";
680 spans[i].setAttribute("data-note", note);
681 }
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]682 noteholder.innerHTML +=
683 "<div class='footnote' id='_footnote_" + n + "'>" +
684 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
685 n + "</a>. " + note + "</div>";
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]686 var id =spans[i].getAttribute("id");
687 if (id != null) refs["#"+id] = n;
688 }
689 }
690 if (n == 0)
691 noteholder.parentNode.removeChild(noteholder);
692 else {
693 // Process footnoterefs.
694 for (i=0; i<spans.length; i++) {
695 if (spans[i].className == "footnoteref") {
696 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
697 href = href.match(/#.*/)[0]; // Because IE return full URL.
698 n = refs[href];
699 spans[i].innerHTML =
700 "[<a href='#_footnote_" + n +
701 "' title='View footnote' class='footnote'>" + n + "</a>]";
702 }
703 }
704 }
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]705},
706
707install: function(toclevels) {
708 var timerId;
709
710 function reinstall() {
711 asciidoc.footnotes();
712 if (toclevels) {
713 asciidoc.toc(toclevels);
714 }
715 }
716
717 function reinstallAndRemoveTimer() {
718 clearInterval(timerId);
719 reinstall();
720 }
721
722 timerId = setInterval(reinstall, 500);
723 if (document.addEventListener)
724 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
725 else
726 window.onload = reinstallAndRemoveTimer;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]727}
728
729}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]730asciidoc.install();
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]731/*]]>*/
732</script>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]733</head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]734<body class="article">
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]735<div id="header">
736<h1>parse-options API</h1>
737</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]738<div id="content">
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]739<div id="preamble">
740<div class="sectionbody">
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]741<div class="paragraph"><p>The parse-options API is used to parse and massage options in Git
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]742and to provide a usage help with consistent look.</p></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]743</div>
744</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]745<div class="sect1">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]746<h2 id="_basics">Basics</h2>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]747<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]748<div class="paragraph"><p>The argument vector <code>argv[]</code> may usually contain mandatory or optional
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]749<em>non-option arguments</em>, e.g. a filename or a branch, and <em>options</em>.
750Options are optional arguments that start with a dash and
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]751that allow to change the behavior of a command.</p></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]752<div class="ulist"><ul>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]753<li>
754<p>
755There are basically three types of options:
756 <em>boolean</em> options,
757 options with (mandatory) <em>arguments</em> and
758 options with <em>optional arguments</em>
759 (i.e. a boolean option that can be adjusted).
760</p>
761</li>
762<li>
763<p>
764There are basically two forms of options:
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]765 <em>Short options</em> consist of one dash (<code>-</code>) and one alphanumeric
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]766 character.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]767 <em>Long options</em> begin with two dashes (<code>--</code>) and some
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]768 alphanumeric characters.
769</p>
770</li>
771<li>
772<p>
773Options are case-sensitive.
774 Please define <em>lower-case long options</em> only.
775</p>
776</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]777</ul></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]778<div class="paragraph"><p>The parse-options API allows:</p></div>
779<div class="ulist"><ul>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]780<li>
781<p>
Junio C Hamanof079f702013-12-06 23:43:18[diff] [blame]782<em>stuck</em> and <em>separate form</em> of options with arguments.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]783 <code>-oArg</code> is stuck, <code>-o Arg</code> is separate form.
784 <code>--option=Arg</code> is stuck, <code>--option Arg</code> is separate form.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]785</p>
786</li>
787<li>
788<p>
789Long options may be <em>abbreviated</em>, as long as the abbreviation
790 is unambiguous.
791</p>
792</li>
793<li>
794<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]795Short options may be bundled, e.g. <code>-a -b</code> can be specified as <code>-ab</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]796</p>
797</li>
798<li>
799<p>
800Boolean long options can be <em>negated</em> (or <em>unset</em>) by prepending
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]801 <code>no-</code>, e.g. <code>--no-abbrev</code> instead of <code>--abbrev</code>. Conversely,
802 options that begin with <code>no-</code> can be <em>negated</em> by removing it.
Junio C Hamanoc7102962013-05-29 23:57:17[diff] [blame]803 Other long options can be unset (e.g., set string to NULL, set
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]804 integer to 0) by prepending <code>no-</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]805</p>
806</li>
807<li>
808<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]809Options and non-option arguments can clearly be separated using the <code>--</code>
810 option, e.g. <code>-a -b --option -- --this-is-a-file</code> indicates that
811 <code>--this-is-a-file</code> must not be processed as an option.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]812</p>
813</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]814</ul></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]815</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]816</div>
817<div class="sect1">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]818<h2 id="_steps_to_parse_options">Steps to parse options</h2>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]819<div class="sectionbody">
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]820<div class="olist arabic"><ol class="arabic">
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]821<li>
822<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]823<code>#include "parse-options.h"</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]824</p>
825</li>
826<li>
827<p>
828define a NULL-terminated
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]829 <code>static const char * const builtin_foo_usage[]</code> array
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]830 containing alternative usage strings
831</p>
832</li>
833<li>
834<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]835define <code>builtin_foo_options</code> array as described below
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]836 in section <em>Data Structure</em>.
837</p>
838</li>
839<li>
840<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]841in <code>cmd_foo(int argc, const char **argv, const char *prefix)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]842 call
843</p>
844<div class="literalblock">
845<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]846<pre><code>argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);</code></pre>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]847</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]848<div class="paragraph"><p><code>parse_options()</code> will filter out the processed options of <code>argv[]</code> and leave the
849non-option arguments in <code>argv[]</code>.
850<code>argc</code> is updated appropriately because of the assignment.</p></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]851<div class="paragraph"><p>You can also pass NULL instead of a usage array as the fifth parameter of
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]852parse_options(), to avoid displaying a help screen with usage info and
853option list. This should only be done if necessary, e.g. to implement
854a limited parser for only a subset of the options that needs to be run
855before the full parser, which in turn shows the full help message.</p></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]856<div class="paragraph"><p>Flags are the bitwise-or of:</p></div>
857<div class="dlist"><dl>
858<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]859<code>PARSE_OPT_KEEP_DASHDASH</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]860</dt>
861<dd>
862<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]863 Keep the <code>--</code> that usually separates options from
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]864 non-option arguments.
865</p>
866</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]867<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]868<code>PARSE_OPT_STOP_AT_NON_OPTION</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]869</dt>
870<dd>
871<p>
872 Usually the whole argument vector is massaged and reordered.
873 Using this flag, processing is stopped at the first non-option
874 argument.
875</p>
876</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]877<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]878<code>PARSE_OPT_KEEP_ARGV0</code>
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]879</dt>
880<dd>
881<p>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]882 Keep the first argument, which contains the program name. It&#8217;s
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]883 removed from argv[] by default.
884</p>
885</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]886<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]887<code>PARSE_OPT_KEEP_UNKNOWN</code>
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]888</dt>
889<dd>
890<p>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]891 Keep unknown arguments instead of erroring out. This doesn&#8217;t
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]892 work for all combinations of arguments as users might expect
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]893 it to do. E.g. if the first argument in <code>--unknown --known</code>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]894 takes a value (which we can&#8217;t know), the second one is
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]895 mistakenly interpreted as a known option. Similarly, if
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]896 <code>PARSE_OPT_STOP_AT_NON_OPTION</code> is set, the second argument in
897 <code>--unknown value</code> will be mistakenly interpreted as a
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]898 non-option, not as a value belonging to the unknown option,
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]899 the parser early. That&#8217;s why parse_options() errors out if
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]900 both options are set.
901</p>
902</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]903<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]904<code>PARSE_OPT_NO_INTERNAL_HELP</code>
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]905</dt>
906<dd>
907<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]908 By default, parse_options() handles <code>-h</code>, <code>--help</code> and
909 <code>--help-all</code> internally, by showing a help screen. This option
Junio C Hamano18f51402009-03-10 16:39:13[diff] [blame]910 turns it off and allows one to add custom handlers for these
911 options, or to just leave them unknown.
912</p>
913</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]914</dl></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]915</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]916</ol></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]917</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]918</div>
919<div class="sect1">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]920<h2 id="_data_structure">Data Structure</h2>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]921<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]922<div class="paragraph"><p>The main data structure is an array of the <code>option</code> struct,
923say <code>static struct option builtin_add_options[]</code>.
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]924There are some macros to easily define options:</p></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]925<div class="dlist"><dl>
926<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]927<code>OPT__ABBREV(&amp;int_var)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]928</dt>
929<dd>
930<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]931 Add <code>--abbrev[=&lt;n&gt;]</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]932</p>
933</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]934<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]935<code>OPT__COLOR(&amp;int_var, description)</code>
Junio C Hamano4aa0bcc2010-03-03 05:13:12[diff] [blame]936</dt>
937<dd>
938<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]939 Add <code>--color[=&lt;when&gt;]</code> and <code>--no-color</code>.
Junio C Hamano4aa0bcc2010-03-03 05:13:12[diff] [blame]940</p>
941</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]942<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]943<code>OPT__DRY_RUN(&amp;int_var, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]944</dt>
945<dd>
946<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]947 Add <code>-n, --dry-run</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]948</p>
949</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]950<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]951<code>OPT__FORCE(&amp;int_var, description)</code>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]952</dt>
953<dd>
954<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]955 Add <code>-f, --force</code>.
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]956</p>
957</dd>
958<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]959<code>OPT__QUIET(&amp;int_var, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]960</dt>
961<dd>
962<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]963 Add <code>-q, --quiet</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]964</p>
965</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]966<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]967<code>OPT__VERBOSE(&amp;int_var, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]968</dt>
969<dd>
970<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]971 Add <code>-v, --verbose</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]972</p>
973</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]974<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]975<code>OPT_GROUP(description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]976</dt>
977<dd>
978<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]979 Start an option group. <code>description</code> is a short string that
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]980 describes the group or an empty string.
981 Start the description with an upper-case letter.
982</p>
983</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]984<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]985<code>OPT_BOOL(short, long, &amp;int_var, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]986</dt>
987<dd>
988<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]989 Introduce a boolean option. <code>int_var</code> is set to one with
990 <code>--option</code> and set to zero with <code>--no-option</code>.
Junio C Hamano4c6612f2011-10-12 23:54:21[diff] [blame]991</p>
992</dd>
993<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]994<code>OPT_COUNTUP(short, long, &amp;int_var, description)</code>
Junio C Hamano4c6612f2011-10-12 23:54:21[diff] [blame]995</dt>
996<dd>
997<p>
998 Introduce a count-up option.
Junio C Hamanof2a3a752016-05-23 22:54:39[diff] [blame]999 Each use of <code>--option</code> increments <code>int_var</code>, starting from zero
1000 (even if initially negative), and <code>--no-option</code> resets it to
1001 zero. To determine if <code>--option</code> or <code>--no-option</code> was encountered at
1002 all, initialize <code>int_var</code> to a negative value, and if it is still
1003 negative after parse_options(), then neither <code>--option</code> nor
1004 <code>--no-option</code> was seen.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1005</p>
1006</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1007<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1008<code>OPT_BIT(short, long, &amp;int_var, description, mask)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1009</dt>
1010<dd>
1011<p>
1012 Introduce a boolean option.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1013 If used, <code>int_var</code> is bitwise-ored with <code>mask</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1014</p>
1015</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1016<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1017<code>OPT_NEGBIT(short, long, &amp;int_var, description, mask)</code>
Junio C Hamano7ae18252009-05-23 09:53:32[diff] [blame]1018</dt>
1019<dd>
1020<p>
1021 Introduce a boolean option.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1022 If used, <code>int_var</code> is bitwise-anded with the inverted <code>mask</code>.
Junio C Hamano7ae18252009-05-23 09:53:32[diff] [blame]1023</p>
1024</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1025<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1026<code>OPT_SET_INT(short, long, &amp;int_var, description, integer)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1027</dt>
1028<dd>
1029<p>
Junio C Hamano4c6612f2011-10-12 23:54:21[diff] [blame]1030 Introduce an integer option.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1031 <code>int_var</code> is set to <code>integer</code> with <code>--option</code>, and
1032 reset to zero with <code>--no-option</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1033</p>
1034</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1035<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1036<code>OPT_STRING(short, long, &amp;str_var, arg_str, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1037</dt>
1038<dd>
1039<p>
1040 Introduce an option with string argument.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1041 The string argument is put into <code>str_var</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1042</p>
1043</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1044<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1045<code>OPT_INTEGER(short, long, &amp;int_var, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1046</dt>
1047<dd>
1048<p>
1049 Introduce an option with integer argument.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1050 The integer is put into <code>int_var</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1051</p>
1052</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1053<dt class="hdlist1">
Junio C Hamanod7ed4042015-08-03 19:43:00[diff] [blame]1054<code>OPT_MAGNITUDE(short, long, &amp;unsigned_long_var, description)</code>
1055</dt>
1056<dd>
1057<p>
1058 Introduce an option with a size argument. The argument must be a
1059 non-negative integer and may include a suffix of <em>k</em>, <em>m</em> or <em>g</em> to
1060 scale the provided value by 1024, 1024<sup>2 or 1024</sup>3 respectively.
1061 The scaled value is put into <code>unsigned_long_var</code>.
1062</p>
1063</dd>
1064<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1065<code>OPT_DATE(short, long, &amp;int_var, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1066</dt>
1067<dd>
1068<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1069 Introduce an option with date argument, see <code>approxidate()</code>.
1070 The timestamp is put into <code>int_var</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1071</p>
1072</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1073<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1074<code>OPT_EXPIRY_DATE(short, long, &amp;int_var, description)</code>
Junio C Hamanoc7102962013-05-29 23:57:17[diff] [blame]1075</dt>
1076<dd>
1077<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1078 Introduce an option with expiry date argument, see <code>parse_expiry_date()</code>.
1079 The timestamp is put into <code>int_var</code>.
Junio C Hamanoc7102962013-05-29 23:57:17[diff] [blame]1080</p>
1081</dd>
1082<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1083<code>OPT_CALLBACK(short, long, &amp;var, arg_str, description, func_ptr)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1084</dt>
1085<dd>
1086<p>
1087 Introduce an option with argument.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1088 The argument will be fed into the function given by <code>func_ptr</code>
1089 and the result will be put into <code>var</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1090 See <em>Option Callbacks</em> below for a more elaborate description.
1091</p>
1092</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1093<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1094<code>OPT_FILENAME(short, long, &amp;var, description)</code>
Junio C Hamano3d141512009-06-01 01:22:40[diff] [blame]1095</dt>
1096<dd>
1097<p>
1098 Introduce an option with a filename argument.
1099 The filename will be prefixed by passing the filename along with
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1100 the prefix argument of <code>parse_options()</code> to <code>prefix_filename()</code>.
Junio C Hamano3d141512009-06-01 01:22:40[diff] [blame]1101</p>
1102</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1103<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1104<code>OPT_ARGUMENT(long, description)</code>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1105</dt>
1106<dd>
1107<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1108 Introduce a long-option argument that will be kept in <code>argv[]</code>.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1109</p>
1110</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1111<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1112<code>OPT_NUMBER_CALLBACK(&amp;var, description, func_ptr)</code>
Junio C Hamano7ae18252009-05-23 09:53:32[diff] [blame]1113</dt>
1114<dd>
1115<p>
1116 Recognize numerical options like -123 and feed the integer as
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1117 if it was an argument to the function given by <code>func_ptr</code>.
1118 The result will be put into <code>var</code>. There can be only one such
Junio C Hamano7ae18252009-05-23 09:53:32[diff] [blame]1119 option definition. It cannot be negated and it takes no
1120 arguments. Short options that happen to be digits take
1121 precedence over it.
1122</p>
1123</dd>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1124<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1125<code>OPT_COLOR_FLAG(short, long, &amp;int_var, description)</code>
Junio C Hamano4aa0bcc2010-03-03 05:13:12[diff] [blame]1126</dt>
1127<dd>
1128<p>
1129 Introduce an option that takes an optional argument that can
1130 have one of three values: "always", "never", or "auto". If the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1131 argument is not given, it defaults to "always". The <code>--no-</code> form
1132 works like <code>--long=never</code>; it cannot take an argument. If
1133 "always", set <code>int_var</code> to 1; if "never", set <code>int_var</code> to 0; if
1134 "auto", set <code>int_var</code> to 1 if stdout is a tty or a pager,
Junio C Hamano4aa0bcc2010-03-03 05:13:12[diff] [blame]1135 0 otherwise.
1136</p>
1137</dd>
Junio C Hamano4c6612f2011-10-12 23:54:21[diff] [blame]1138<dt class="hdlist1">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1139<code>OPT_NOOP_NOARG(short, long)</code>
Junio C Hamano4c6612f2011-10-12 23:54:21[diff] [blame]1140</dt>
1141<dd>
1142<p>
1143 Introduce an option that has no effect and takes no arguments.
1144 Use it to hide deprecated options that are still to be recognized
1145 and ignored silently.
1146</p>
1147</dd>
Junio C Hamanod7ed4042015-08-03 19:43:00[diff] [blame]1148<dt class="hdlist1">
1149<code>OPT_PASSTHRU(short, long, &amp;char_var, arg_str, description, flags)</code>
1150</dt>
1151<dd>
1152<p>
1153 Introduce an option that will be reconstructed into a char* string,
1154 which must be initialized to NULL. This is useful when you need to
1155 pass the command-line option to another command. Any previous value
1156 will be overwritten, so this should only be used for options where
1157 the last one specified on the command line wins.
1158</p>
1159</dd>
1160<dt class="hdlist1">
1161<code>OPT_PASSTHRU_ARGV(short, long, &amp;argv_array_var, arg_str, description, flags)</code>
1162</dt>
1163<dd>
1164<p>
1165 Introduce an option where all instances of it on the command-line will
1166 be reconstructed into an argv_array. This is useful when you need to
1167 pass the command-line option, which can be specified multiple times,
1168 to another command.
1169</p>
1170</dd>
Junio C Hamano84ea1e42016-04-08 21:53:48[diff] [blame]1171<dt class="hdlist1">
1172<code>OPT_CMDMODE(short, long, &amp;int_var, description, enum_val)</code>
1173</dt>
1174<dd>
1175<p>
1176 Define an "operation mode" option, only one of which in the same
1177 group of "operating mode" options that share the same <code>int_var</code>
1178 can be given by the user. <code>enum_val</code> is set to <code>int_var</code> when the
1179 option is used, but an error is reported if other "operating mode"
1180 option has already set its value to the same <code>int_var</code>.
1181</p>
1182</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1183</dl></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1184<div class="paragraph"><p>The last element of the array must be <code>OPT_END()</code>.</p></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1185<div class="paragraph"><p>If not stated otherwise, interpret the arguments as follows:</p></div>
1186<div class="ulist"><ul>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1187<li>
1188<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1189<code>short</code> is a character for the short option
1190 (e.g. <code>'e'</code> for <code>-e</code>, use <code>0</code> to omit),
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1191</p>
1192</li>
1193<li>
1194<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1195<code>long</code> is a string for the long option
1196 (e.g. <code>"example"</code> for <code>--example</code>, use <code>NULL</code> to omit),
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1197</p>
1198</li>
1199<li>
1200<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1201<code>int_var</code> is an integer variable,
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1202</p>
1203</li>
1204<li>
1205<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1206<code>str_var</code> is a string variable (<code>char *</code>),
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1207</p>
1208</li>
1209<li>
1210<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1211<code>arg_str</code> is the string that is shown as argument
1212 (e.g. <code>"branch"</code> will result in <code>&lt;branch&gt;</code>).
1213 If set to <code>NULL</code>, three dots (<code>...</code>) will be displayed.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1214</p>
1215</li>
1216<li>
1217<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1218<code>description</code> is a short string to describe the effect of the option.
1219 It shall begin with a lower-case letter and a full stop (<code>.</code>) shall be
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1220 omitted at the end.
1221</p>
1222</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1223</ul></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1224</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1225</div>
1226<div class="sect1">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1227<h2 id="_option_callbacks">Option Callbacks</h2>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1228<div class="sectionbody">
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1229<div class="paragraph"><p>The function must be defined in this form:</p></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1230<div class="literalblock">
1231<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1232<pre><code>int func(const struct option *opt, const char *arg, int unset)</code></pre>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1233</div></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1234<div class="paragraph"><p>The callback mechanism is as follows:</p></div>
1235<div class="ulist"><ul>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1236<li>
1237<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1238Inside <code>func</code>, the only interesting member of the structure
1239 given by <code>opt</code> is the void pointer <code>opt-&gt;value</code>.
1240 <code>*opt-&gt;value</code> will be the value that is saved into <code>var</code>, if you
1241 use <code>OPT_CALLBACK()</code>.
1242 For example, do <code>*(unsigned long *)opt-&gt;value = 42;</code> to get 42
1243 into an <code>unsigned long</code> variable.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1244</p>
1245</li>
1246<li>
1247<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1248Return value <code>0</code> indicates success and non-zero return
1249 value will invoke <code>usage_with_options()</code> and, thus, die.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1250</p>
1251</li>
1252<li>
1253<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1254If the user negates the option, <code>arg</code> is <code>NULL</code> and <code>unset</code> is 1.
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1255</p>
1256</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1257</ul></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1258</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1259</div>
1260<div class="sect1">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1261<h2 id="_sophisticated_option_parsing">Sophisticated option parsing</h2>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1262<div class="sectionbody">
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1263<div class="paragraph"><p>If you need, for example, option callbacks with optional arguments
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1264or without arguments at all, or if you need other special cases,
1265that are not handled by the macros above, you need to specify the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1266members of the <code>option</code> structure manually.</p></div>
Junio C Hamano97bcb482010-11-25 03:16:07[diff] [blame]1267<div class="paragraph"><p>This is not covered in this document, but well documented
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1268in <code>parse-options.h</code> itself.</p></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1269</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1270</div>
1271<div class="sect1">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1272<h2 id="_examples">Examples</h2>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1273<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1274<div class="paragraph"><p>See <code>test-parse-options.c</code> and
1275<code>builtin/add.c</code>,
1276<code>builtin/clone.c</code>,
1277<code>builtin/commit.c</code>,
1278<code>builtin/fetch.c</code>,
1279<code>builtin/fsck.c</code>,
1280<code>builtin/rm.c</code>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1281for real-world examples.</p></div>
Junio C Hamano4224f992008-06-23 07:14:08[diff] [blame]1282</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1283</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1284</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1285<div id="footnotes"><hr /></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1286<div id="footer">
1287<div id="footer-text">
Junio C Hamanof2a3a752016-05-23 22:54:39[diff] [blame]1288Last updated 2016-05-23 15:52:04 PDT
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1289</div>
1290</div>
1291</body>
1292</html>