mirror of
https://github.com/jlengrand/picocli.git
synced 2026-03-10 08:41:17 +00:00
3707 lines
186 KiB
HTML
3707 lines
186 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="generator" content="Asciidoctor 2.0.10">
|
|
<title>Quick Guide</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
|
|
<style>
|
|
/* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
|
|
/* Uncomment @import statement to use as custom stylesheet */
|
|
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
|
|
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}
|
|
audio,video{display:inline-block}
|
|
audio:not([controls]){display:none;height:0}
|
|
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
|
|
a{background:none}
|
|
a:focus{outline:thin dotted}
|
|
a:active,a:hover{outline:0}
|
|
h1{font-size:2em;margin:.67em 0}
|
|
abbr[title]{border-bottom:1px dotted}
|
|
b,strong{font-weight:bold}
|
|
dfn{font-style:italic}
|
|
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
|
|
mark{background:#ff0;color:#000}
|
|
code,kbd,pre,samp{font-family:monospace;font-size:1em}
|
|
pre{white-space:pre-wrap}
|
|
q{quotes:"\201C" "\201D" "\2018" "\2019"}
|
|
small{font-size:80%}
|
|
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
|
|
sup{top:-.5em}
|
|
sub{bottom:-.25em}
|
|
img{border:0}
|
|
svg:not(:root){overflow:hidden}
|
|
figure{margin:0}
|
|
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
|
|
legend{border:0;padding:0}
|
|
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
|
|
button,input{line-height:normal}
|
|
button,select{text-transform:none}
|
|
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
|
|
button[disabled],html input[disabled]{cursor:default}
|
|
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
|
|
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
|
|
textarea{overflow:auto;vertical-align:top}
|
|
table{border-collapse:collapse;border-spacing:0}
|
|
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
|
|
html,body{font-size:100%}
|
|
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
|
|
a:hover{cursor:pointer}
|
|
img,object,embed{max-width:100%;height:auto}
|
|
object,embed{height:100%}
|
|
img{-ms-interpolation-mode:bicubic}
|
|
.left{float:left!important}
|
|
.right{float:right!important}
|
|
.text-left{text-align:left!important}
|
|
.text-right{text-align:right!important}
|
|
.text-center{text-align:center!important}
|
|
.text-justify{text-align:justify!important}
|
|
.hide{display:none}
|
|
img,object,svg{display:inline-block;vertical-align:middle}
|
|
textarea{height:auto;min-height:50px}
|
|
select{width:100%}
|
|
.center{margin-left:auto;margin-right:auto}
|
|
.stretch{width:100%}
|
|
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
|
|
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
|
|
a{color:#2156a5;text-decoration:underline;line-height:inherit}
|
|
a:hover,a:focus{color:#1d4b8f}
|
|
a img{border:0}
|
|
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
|
|
p aside{font-size:.875em;line-height:1.35;font-style:italic}
|
|
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
|
|
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
|
|
h1{font-size:2.125em}
|
|
h2{font-size:1.6875em}
|
|
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
|
|
h4,h5{font-size:1.125em}
|
|
h6{font-size:1em}
|
|
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
|
|
em,i{font-style:italic;line-height:inherit}
|
|
strong,b{font-weight:bold;line-height:inherit}
|
|
small{font-size:60%;line-height:inherit}
|
|
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
|
|
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
|
|
ul,ol{margin-left:1.5em}
|
|
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
|
|
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
|
|
ul.square{list-style-type:square}
|
|
ul.circle{list-style-type:circle}
|
|
ul.disc{list-style-type:disc}
|
|
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
|
|
dl dt{margin-bottom:.3125em;font-weight:bold}
|
|
dl dd{margin-bottom:1.25em}
|
|
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
|
|
abbr{text-transform:none}
|
|
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
|
|
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
|
|
blockquote cite::before{content:"\2014 \0020"}
|
|
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
|
|
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
|
|
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
|
|
h1{font-size:2.75em}
|
|
h2{font-size:2.3125em}
|
|
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
|
|
h4{font-size:1.4375em}}
|
|
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
|
|
table thead,table tfoot{background:#f7f8f7}
|
|
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
|
|
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
|
|
table tr.even,table tr.alt{background:#f8f8f7}
|
|
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
|
|
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
|
|
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
|
|
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
|
|
.clearfix::after,.float-group::after{clear:both}
|
|
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
|
|
:not(pre)>code.nobreak{word-wrap:normal}
|
|
:not(pre)>code.nowrap{white-space:nowrap}
|
|
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
|
|
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
|
|
pre>code{display:block}
|
|
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
|
|
em em{font-style:normal}
|
|
strong strong{font-weight:400}
|
|
.keyseq{color:rgba(51,51,51,.8)}
|
|
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
|
|
.keyseq kbd:first-child{margin-left:0}
|
|
.keyseq kbd:last-child{margin-right:0}
|
|
.menuseq,.menuref{color:#000}
|
|
.menuseq b:not(.caret),.menuref{font-weight:inherit}
|
|
.menuseq{word-spacing:-.02em}
|
|
.menuseq b.caret{font-size:1.25em;line-height:.8}
|
|
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
|
|
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
|
|
b.button::before{content:"[";padding:0 3px 0 2px}
|
|
b.button::after{content:"]";padding:0 2px 0 3px}
|
|
p a>code:hover{color:rgba(0,0,0,.9)}
|
|
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
|
|
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
|
|
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
|
|
#content{margin-top:1.25em}
|
|
#content::before{content:none}
|
|
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
|
|
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
|
|
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
|
|
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
|
|
#header .details span:first-child{margin-left:-.125em}
|
|
#header .details span.email a{color:rgba(0,0,0,.85)}
|
|
#header .details br{display:none}
|
|
#header .details br+span::before{content:"\00a0\2013\00a0"}
|
|
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
|
|
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
|
|
#header #revnumber{text-transform:capitalize}
|
|
#header #revnumber::after{content:"\00a0"}
|
|
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
|
|
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
|
|
#toc>ul{margin-left:.125em}
|
|
#toc ul.sectlevel0>li>a{font-style:italic}
|
|
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
|
|
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
|
|
#toc li{line-height:1.3334;margin-top:.3334em}
|
|
#toc a{text-decoration:none}
|
|
#toc a:active{text-decoration:underline}
|
|
#toctitle{color:#7a2518;font-size:1.2em}
|
|
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
|
|
body.toc2{padding-left:15em;padding-right:0}
|
|
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
|
|
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
|
|
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
|
|
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
|
|
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
|
|
body.toc2.toc-right{padding-left:0;padding-right:15em}
|
|
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
|
|
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
|
|
#toc.toc2{width:20em}
|
|
#toc.toc2 #toctitle{font-size:1.375em}
|
|
#toc.toc2>ul{font-size:.95em}
|
|
#toc.toc2 ul ul{padding-left:1.25em}
|
|
body.toc2.toc-right{padding-left:0;padding-right:20em}}
|
|
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
|
|
#content #toc>:first-child{margin-top:0}
|
|
#content #toc>:last-child{margin-bottom:0}
|
|
#footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em}
|
|
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
|
|
#content{margin-bottom:.625em}
|
|
.sect1{padding-bottom:.625em}
|
|
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
|
|
.sect1{padding-bottom:1.25em}}
|
|
.sect1:last-child{padding-bottom:0}
|
|
.sect1+.sect1{border-top:1px solid #e7e7e9}
|
|
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
|
|
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
|
|
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
|
|
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
|
|
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
|
|
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
|
|
details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em}
|
|
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
|
|
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
|
|
.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
|
|
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
|
|
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
|
|
.admonitionblock>table td.icon{text-align:center;width:80px}
|
|
.admonitionblock>table td.icon img{max-width:none}
|
|
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
|
|
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
|
|
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
|
|
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
|
|
.exampleblock>.content>:first-child{margin-top:0}
|
|
.exampleblock>.content>:last-child{margin-bottom:0}
|
|
.sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}
|
|
.sidebarblock>:first-child{margin-top:0}
|
|
.sidebarblock>:last-child{margin-bottom:0}
|
|
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
|
|
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
|
|
.literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
|
|
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
|
|
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
|
|
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
|
|
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
|
|
.listingblock>.content{position:relative}
|
|
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
|
|
.listingblock:hover code[data-lang]::before{display:block}
|
|
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
|
|
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
|
|
.listingblock pre.highlightjs{padding:0}
|
|
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
|
|
.listingblock pre.prettyprint{border-width:0}
|
|
.prettyprint{background:#f7f7f8}
|
|
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
|
|
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
|
|
pre.prettyprint li code[data-lang]::before{opacity:1}
|
|
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
|
|
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
|
|
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
|
|
table.linenotable td.code{padding-left:.75em}
|
|
table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em}
|
|
pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em}
|
|
pre.pygments .lineno::before{content:"";margin-right:-.125em}
|
|
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
|
|
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
|
|
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
|
|
.quoteblock blockquote{margin:0;padding:0;border:0}
|
|
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
|
|
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
|
|
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
|
|
.verseblock{margin:0 1em 1.25em}
|
|
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
|
|
.verseblock pre strong{font-weight:400}
|
|
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
|
|
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
|
|
.quoteblock .attribution br,.verseblock .attribution br{display:none}
|
|
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
|
|
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
|
|
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
|
|
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
|
|
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
|
|
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
|
|
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
|
|
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
|
|
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
|
|
table.tableblock{max-width:100%;border-collapse:separate}
|
|
p.tableblock:last-child{margin-bottom:0}
|
|
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
|
|
td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0}
|
|
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
|
|
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
|
|
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
|
|
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
|
|
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
|
|
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
|
|
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
|
|
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
|
|
table.frame-all{border-width:1px}
|
|
table.frame-sides{border-width:0 1px}
|
|
table.frame-topbot,table.frame-ends{border-width:1px 0}
|
|
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7}
|
|
th.halign-left,td.halign-left{text-align:left}
|
|
th.halign-right,td.halign-right{text-align:right}
|
|
th.halign-center,td.halign-center{text-align:center}
|
|
th.valign-top,td.valign-top{vertical-align:top}
|
|
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
|
|
th.valign-middle,td.valign-middle{vertical-align:middle}
|
|
table thead th,table tfoot th{font-weight:bold}
|
|
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
|
|
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
|
|
p.tableblock>code:only-child{background:none;padding:0}
|
|
p.tableblock{font-size:1em}
|
|
ol{margin-left:1.75em}
|
|
ul li ol{margin-left:1.5em}
|
|
dl dd{margin-left:1.125em}
|
|
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
|
|
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
|
|
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
|
|
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
|
|
ul.unstyled,ol.unstyled{margin-left:0}
|
|
ul.checklist{margin-left:.625em}
|
|
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
|
|
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
|
|
ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
|
|
ul.inline>li{margin-left:1.25em}
|
|
.unstyled dl dt{font-weight:400;font-style:normal}
|
|
ol.arabic{list-style-type:decimal}
|
|
ol.decimal{list-style-type:decimal-leading-zero}
|
|
ol.loweralpha{list-style-type:lower-alpha}
|
|
ol.upperalpha{list-style-type:upper-alpha}
|
|
ol.lowerroman{list-style-type:lower-roman}
|
|
ol.upperroman{list-style-type:upper-roman}
|
|
ol.lowergreek{list-style-type:lower-greek}
|
|
.hdlist>table,.colist>table{border:0;background:none}
|
|
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
|
|
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
|
|
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
|
|
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
|
|
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
|
|
.colist td:not([class]):first-child img{max-width:none}
|
|
.colist td:not([class]):last-child{padding:.25em 0}
|
|
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
|
|
.imageblock.left{margin:.25em .625em 1.25em 0}
|
|
.imageblock.right{margin:.25em 0 1.25em .625em}
|
|
.imageblock>.title{margin-bottom:0}
|
|
.imageblock.thumb,.imageblock.th{border-width:6px}
|
|
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
|
|
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
|
|
.image.left{margin-right:.625em}
|
|
.image.right{margin-left:.625em}
|
|
a.image{text-decoration:none;display:inline-block}
|
|
a.image object{pointer-events:none}
|
|
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
|
|
sup.footnote a,sup.footnoteref a{text-decoration:none}
|
|
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
|
|
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
|
|
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
|
|
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
|
|
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
|
|
#footnotes .footnote:last-of-type{margin-bottom:0}
|
|
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
|
|
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
|
|
.gist .file-data>table td.line-data{width:99%}
|
|
div.unbreakable{page-break-inside:avoid}
|
|
.big{font-size:larger}
|
|
.small{font-size:smaller}
|
|
.underline{text-decoration:underline}
|
|
.overline{text-decoration:overline}
|
|
.line-through{text-decoration:line-through}
|
|
.aqua{color:#00bfbf}
|
|
.aqua-background{background:#00fafa}
|
|
.black{color:#000}
|
|
.black-background{background:#000}
|
|
.blue{color:#0000bf}
|
|
.blue-background{background:#0000fa}
|
|
.fuchsia{color:#bf00bf}
|
|
.fuchsia-background{background:#fa00fa}
|
|
.gray{color:#606060}
|
|
.gray-background{background:#7d7d7d}
|
|
.green{color:#006000}
|
|
.green-background{background:#007d00}
|
|
.lime{color:#00bf00}
|
|
.lime-background{background:#00fa00}
|
|
.maroon{color:#600000}
|
|
.maroon-background{background:#7d0000}
|
|
.navy{color:#000060}
|
|
.navy-background{background:#00007d}
|
|
.olive{color:#606000}
|
|
.olive-background{background:#7d7d00}
|
|
.purple{color:#600060}
|
|
.purple-background{background:#7d007d}
|
|
.red{color:#bf0000}
|
|
.red-background{background:#fa0000}
|
|
.silver{color:#909090}
|
|
.silver-background{background:#bcbcbc}
|
|
.teal{color:#006060}
|
|
.teal-background{background:#007d7d}
|
|
.white{color:#bfbfbf}
|
|
.white-background{background:#fafafa}
|
|
.yellow{color:#bfbf00}
|
|
.yellow-background{background:#fafa00}
|
|
span.icon>.fa{cursor:default}
|
|
a span.icon>.fa{cursor:inherit}
|
|
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
|
|
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
|
|
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
|
|
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
|
|
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
|
|
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
|
|
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
|
|
.conum[data-value] *{color:#fff!important}
|
|
.conum[data-value]+b{display:none}
|
|
.conum[data-value]::after{content:attr(data-value)}
|
|
pre .conum[data-value]{position:relative;top:-.125em}
|
|
b.conum *{color:inherit!important}
|
|
.conum:not([data-value]):empty{display:none}
|
|
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
|
|
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
|
|
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
|
|
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
|
|
p{margin-bottom:1.25rem}
|
|
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
|
|
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
|
|
.print-only{display:none!important}
|
|
@page{margin:1.25cm .75cm}
|
|
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
|
|
html{font-size:80%}
|
|
a{color:inherit!important;text-decoration:underline!important}
|
|
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
|
|
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
|
|
abbr[title]::after{content:" (" attr(title) ")"}
|
|
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
|
|
thead{display:table-header-group}
|
|
svg{max-width:100%}
|
|
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
|
|
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
|
|
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
|
|
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
|
|
body.book #header{text-align:center}
|
|
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
|
|
body.book #header .details{border:0!important;display:block;padding:0!important}
|
|
body.book #header .details span:first-child{margin-left:0!important}
|
|
body.book #header .details br{display:block}
|
|
body.book #header .details br+span::before{content:none!important}
|
|
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
|
|
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
|
|
.listingblock code[data-lang]::before{display:block}
|
|
#footer{padding:0 .9375em}
|
|
.hide-on-print{display:none!important}
|
|
.print-only{display:block!important}
|
|
.hide-for-print{display:none!important}
|
|
.show-for-print{display:inherit!important}}
|
|
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
|
|
.sect1{padding:0!important}
|
|
.sect1+.sect1{border:0}
|
|
#footer{background:none}
|
|
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
|
|
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
|
|
</style>
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
|
|
<script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous" ></script>
|
|
<script>
|
|
/*!
|
|
* clipboard.js v2.0.6
|
|
* https://clipboardjs.com/
|
|
*
|
|
* Licensed MIT © Zeno Rocha
|
|
*/
|
|
(function webpackUniversalModuleDefinition(root, factory) {
|
|
if(typeof exports === 'object' && typeof module === 'object')
|
|
module.exports = factory();
|
|
else if(typeof define === 'function' && define.amd)
|
|
define([], factory);
|
|
else if(typeof exports === 'object')
|
|
exports["ClipboardJS"] = factory();
|
|
else
|
|
root["ClipboardJS"] = factory();
|
|
})(this, function() {
|
|
return /******/ (function(modules) { // webpackBootstrap
|
|
/******/ // The module cache
|
|
/******/ var installedModules = {};
|
|
/******/
|
|
/******/ // The require function
|
|
/******/ function __webpack_require__(moduleId) {
|
|
/******/
|
|
/******/ // Check if module is in cache
|
|
/******/ if(installedModules[moduleId]) {
|
|
/******/ return installedModules[moduleId].exports;
|
|
/******/ }
|
|
/******/ // Create a new module (and put it into the cache)
|
|
/******/ var module = installedModules[moduleId] = {
|
|
/******/ i: moduleId,
|
|
/******/ l: false,
|
|
/******/ exports: {}
|
|
/******/ };
|
|
/******/
|
|
/******/ // Execute the module function
|
|
/******/ modules[moduleId].call(module.exports, module, module.exports, __webpack_require__);
|
|
/******/
|
|
/******/ // Flag the module as loaded
|
|
/******/ module.l = true;
|
|
/******/
|
|
/******/ // Return the exports of the module
|
|
/******/ return module.exports;
|
|
/******/ }
|
|
/******/
|
|
/******/
|
|
/******/ // expose the modules object (__webpack_modules__)
|
|
/******/ __webpack_require__.m = modules;
|
|
/******/
|
|
/******/ // expose the module cache
|
|
/******/ __webpack_require__.c = installedModules;
|
|
/******/
|
|
/******/ // define getter function for harmony exports
|
|
/******/ __webpack_require__.d = function(exports, name, getter) {
|
|
/******/ if(!__webpack_require__.o(exports, name)) {
|
|
/******/ Object.defineProperty(exports, name, { enumerable: true, get: getter });
|
|
/******/ }
|
|
/******/ };
|
|
/******/
|
|
/******/ // define __esModule on exports
|
|
/******/ __webpack_require__.r = function(exports) {
|
|
/******/ if(typeof Symbol !== 'undefined' && Symbol.toStringTag) {
|
|
/******/ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
|
|
/******/ }
|
|
/******/ Object.defineProperty(exports, '__esModule', { value: true });
|
|
/******/ };
|
|
/******/
|
|
/******/ // create a fake namespace object
|
|
/******/ // mode & 1: value is a module id, require it
|
|
/******/ // mode & 2: merge all properties of value into the ns
|
|
/******/ // mode & 4: return value when already ns object
|
|
/******/ // mode & 8|1: behave like require
|
|
/******/ __webpack_require__.t = function(value, mode) {
|
|
/******/ if(mode & 1) value = __webpack_require__(value);
|
|
/******/ if(mode & 8) return value;
|
|
/******/ if((mode & 4) && typeof value === 'object' && value && value.__esModule) return value;
|
|
/******/ var ns = Object.create(null);
|
|
/******/ __webpack_require__.r(ns);
|
|
/******/ Object.defineProperty(ns, 'default', { enumerable: true, value: value });
|
|
/******/ if(mode & 2 && typeof value != 'string') for(var key in value) __webpack_require__.d(ns, key, function(key) { return value[key]; }.bind(null, key));
|
|
/******/ return ns;
|
|
/******/ };
|
|
/******/
|
|
/******/ // getDefaultExport function for compatibility with non-harmony modules
|
|
/******/ __webpack_require__.n = function(module) {
|
|
/******/ var getter = module && module.__esModule ?
|
|
/******/ function getDefault() { return module['default']; } :
|
|
/******/ function getModuleExports() { return module; };
|
|
/******/ __webpack_require__.d(getter, 'a', getter);
|
|
/******/ return getter;
|
|
/******/ };
|
|
/******/
|
|
/******/ // Object.prototype.hasOwnProperty.call
|
|
/******/ __webpack_require__.o = function(object, property) { return Object.prototype.hasOwnProperty.call(object, property); };
|
|
/******/
|
|
/******/ // __webpack_public_path__
|
|
/******/ __webpack_require__.p = "";
|
|
/******/
|
|
/******/
|
|
/******/ // Load entry module and return exports
|
|
/******/ return __webpack_require__(__webpack_require__.s = 6);
|
|
/******/ })
|
|
/************************************************************************/
|
|
/******/ ([
|
|
/* 0 */
|
|
/***/ (function(module, exports) {
|
|
|
|
function select(element) {
|
|
var selectedText;
|
|
|
|
if (element.nodeName === 'SELECT') {
|
|
element.focus();
|
|
|
|
selectedText = element.value;
|
|
}
|
|
else if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {
|
|
var isReadOnly = element.hasAttribute('readonly');
|
|
|
|
if (!isReadOnly) {
|
|
element.setAttribute('readonly', '');
|
|
}
|
|
|
|
element.select();
|
|
element.setSelectionRange(0, element.value.length);
|
|
|
|
if (!isReadOnly) {
|
|
element.removeAttribute('readonly');
|
|
}
|
|
|
|
selectedText = element.value;
|
|
}
|
|
else {
|
|
if (element.hasAttribute('contenteditable')) {
|
|
element.focus();
|
|
}
|
|
|
|
var selection = window.getSelection();
|
|
var range = document.createRange();
|
|
|
|
range.selectNodeContents(element);
|
|
selection.removeAllRanges();
|
|
selection.addRange(range);
|
|
|
|
selectedText = selection.toString();
|
|
}
|
|
|
|
return selectedText;
|
|
}
|
|
|
|
module.exports = select;
|
|
|
|
|
|
/***/ }),
|
|
/* 1 */
|
|
/***/ (function(module, exports) {
|
|
|
|
function E () {
|
|
// Keep this empty so it's easier to inherit from
|
|
// (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)
|
|
}
|
|
|
|
E.prototype = {
|
|
on: function (name, callback, ctx) {
|
|
var e = this.e || (this.e = {});
|
|
|
|
(e[name] || (e[name] = [])).push({
|
|
fn: callback,
|
|
ctx: ctx
|
|
});
|
|
|
|
return this;
|
|
},
|
|
|
|
once: function (name, callback, ctx) {
|
|
var self = this;
|
|
function listener () {
|
|
self.off(name, listener);
|
|
callback.apply(ctx, arguments);
|
|
};
|
|
|
|
listener._ = callback
|
|
return this.on(name, listener, ctx);
|
|
},
|
|
|
|
emit: function (name) {
|
|
var data = [].slice.call(arguments, 1);
|
|
var evtArr = ((this.e || (this.e = {}))[name] || []).slice();
|
|
var i = 0;
|
|
var len = evtArr.length;
|
|
|
|
for (i; i < len; i++) {
|
|
evtArr[i].fn.apply(evtArr[i].ctx, data);
|
|
}
|
|
|
|
return this;
|
|
},
|
|
|
|
off: function (name, callback) {
|
|
var e = this.e || (this.e = {});
|
|
var evts = e[name];
|
|
var liveEvents = [];
|
|
|
|
if (evts && callback) {
|
|
for (var i = 0, len = evts.length; i < len; i++) {
|
|
if (evts[i].fn !== callback && evts[i].fn._ !== callback)
|
|
liveEvents.push(evts[i]);
|
|
}
|
|
}
|
|
|
|
// Remove event from queue to prevent memory leak
|
|
// Suggested by https://github.com/lazd
|
|
// Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910
|
|
|
|
(liveEvents.length)
|
|
? e[name] = liveEvents
|
|
: delete e[name];
|
|
|
|
return this;
|
|
}
|
|
};
|
|
|
|
module.exports = E;
|
|
module.exports.TinyEmitter = E;
|
|
|
|
|
|
/***/ }),
|
|
/* 2 */
|
|
/***/ (function(module, exports, __webpack_require__) {
|
|
|
|
var is = __webpack_require__(3);
|
|
var delegate = __webpack_require__(4);
|
|
|
|
/**
|
|
* Validates all params and calls the right
|
|
* listener function based on its target type.
|
|
*
|
|
* @param {String|HTMLElement|HTMLCollection|NodeList} target
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @return {Object}
|
|
*/
|
|
function listen(target, type, callback) {
|
|
if (!target && !type && !callback) {
|
|
throw new Error('Missing required arguments');
|
|
}
|
|
|
|
if (!is.string(type)) {
|
|
throw new TypeError('Second argument must be a String');
|
|
}
|
|
|
|
if (!is.fn(callback)) {
|
|
throw new TypeError('Third argument must be a Function');
|
|
}
|
|
|
|
if (is.node(target)) {
|
|
return listenNode(target, type, callback);
|
|
}
|
|
else if (is.nodeList(target)) {
|
|
return listenNodeList(target, type, callback);
|
|
}
|
|
else if (is.string(target)) {
|
|
return listenSelector(target, type, callback);
|
|
}
|
|
else {
|
|
throw new TypeError('First argument must be a String, HTMLElement, HTMLCollection, or NodeList');
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Adds an event listener to a HTML element
|
|
* and returns a remove listener function.
|
|
*
|
|
* @param {HTMLElement} node
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @return {Object}
|
|
*/
|
|
function listenNode(node, type, callback) {
|
|
node.addEventListener(type, callback);
|
|
|
|
return {
|
|
destroy: function() {
|
|
node.removeEventListener(type, callback);
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Add an event listener to a list of HTML elements
|
|
* and returns a remove listener function.
|
|
*
|
|
* @param {NodeList|HTMLCollection} nodeList
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @return {Object}
|
|
*/
|
|
function listenNodeList(nodeList, type, callback) {
|
|
Array.prototype.forEach.call(nodeList, function(node) {
|
|
node.addEventListener(type, callback);
|
|
});
|
|
|
|
return {
|
|
destroy: function() {
|
|
Array.prototype.forEach.call(nodeList, function(node) {
|
|
node.removeEventListener(type, callback);
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Add an event listener to a selector
|
|
* and returns a remove listener function.
|
|
*
|
|
* @param {String} selector
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @return {Object}
|
|
*/
|
|
function listenSelector(selector, type, callback) {
|
|
return delegate(document.body, selector, type, callback);
|
|
}
|
|
|
|
module.exports = listen;
|
|
|
|
|
|
/***/ }),
|
|
/* 3 */
|
|
/***/ (function(module, exports) {
|
|
|
|
/**
|
|
* Check if argument is a HTML element.
|
|
*
|
|
* @param {Object} value
|
|
* @return {Boolean}
|
|
*/
|
|
exports.node = function(value) {
|
|
return value !== undefined
|
|
&& value instanceof HTMLElement
|
|
&& value.nodeType === 1;
|
|
};
|
|
|
|
/**
|
|
* Check if argument is a list of HTML elements.
|
|
*
|
|
* @param {Object} value
|
|
* @return {Boolean}
|
|
*/
|
|
exports.nodeList = function(value) {
|
|
var type = Object.prototype.toString.call(value);
|
|
|
|
return value !== undefined
|
|
&& (type === '[object NodeList]' || type === '[object HTMLCollection]')
|
|
&& ('length' in value)
|
|
&& (value.length === 0 || exports.node(value[0]));
|
|
};
|
|
|
|
/**
|
|
* Check if argument is a string.
|
|
*
|
|
* @param {Object} value
|
|
* @return {Boolean}
|
|
*/
|
|
exports.string = function(value) {
|
|
return typeof value === 'string'
|
|
|| value instanceof String;
|
|
};
|
|
|
|
/**
|
|
* Check if argument is a function.
|
|
*
|
|
* @param {Object} value
|
|
* @return {Boolean}
|
|
*/
|
|
exports.fn = function(value) {
|
|
var type = Object.prototype.toString.call(value);
|
|
|
|
return type === '[object Function]';
|
|
};
|
|
|
|
|
|
/***/ }),
|
|
/* 4 */
|
|
/***/ (function(module, exports, __webpack_require__) {
|
|
|
|
var closest = __webpack_require__(5);
|
|
|
|
/**
|
|
* Delegates event to a selector.
|
|
*
|
|
* @param {Element} element
|
|
* @param {String} selector
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @param {Boolean} useCapture
|
|
* @return {Object}
|
|
*/
|
|
function _delegate(element, selector, type, callback, useCapture) {
|
|
var listenerFn = listener.apply(this, arguments);
|
|
|
|
element.addEventListener(type, listenerFn, useCapture);
|
|
|
|
return {
|
|
destroy: function() {
|
|
element.removeEventListener(type, listenerFn, useCapture);
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Delegates event to a selector.
|
|
*
|
|
* @param {Element|String|Array} [elements]
|
|
* @param {String} selector
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @param {Boolean} useCapture
|
|
* @return {Object}
|
|
*/
|
|
function delegate(elements, selector, type, callback, useCapture) {
|
|
// Handle the regular Element usage
|
|
if (typeof elements.addEventListener === 'function') {
|
|
return _delegate.apply(null, arguments);
|
|
}
|
|
|
|
// Handle Element-less usage, it defaults to global delegation
|
|
if (typeof type === 'function') {
|
|
// Use `document` as the first parameter, then apply arguments
|
|
// This is a short way to .unshift `arguments` without running into deoptimizations
|
|
return _delegate.bind(null, document).apply(null, arguments);
|
|
}
|
|
|
|
// Handle Selector-based usage
|
|
if (typeof elements === 'string') {
|
|
elements = document.querySelectorAll(elements);
|
|
}
|
|
|
|
// Handle Array-like based usage
|
|
return Array.prototype.map.call(elements, function (element) {
|
|
return _delegate(element, selector, type, callback, useCapture);
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Finds closest match and invokes callback.
|
|
*
|
|
* @param {Element} element
|
|
* @param {String} selector
|
|
* @param {String} type
|
|
* @param {Function} callback
|
|
* @return {Function}
|
|
*/
|
|
function listener(element, selector, type, callback) {
|
|
return function(e) {
|
|
e.delegateTarget = closest(e.target, selector);
|
|
|
|
if (e.delegateTarget) {
|
|
callback.call(element, e);
|
|
}
|
|
}
|
|
}
|
|
|
|
module.exports = delegate;
|
|
|
|
|
|
/***/ }),
|
|
/* 5 */
|
|
/***/ (function(module, exports) {
|
|
|
|
var DOCUMENT_NODE_TYPE = 9;
|
|
|
|
/**
|
|
* A polyfill for Element.matches()
|
|
*/
|
|
if (typeof Element !== 'undefined' && !Element.prototype.matches) {
|
|
var proto = Element.prototype;
|
|
|
|
proto.matches = proto.matchesSelector ||
|
|
proto.mozMatchesSelector ||
|
|
proto.msMatchesSelector ||
|
|
proto.oMatchesSelector ||
|
|
proto.webkitMatchesSelector;
|
|
}
|
|
|
|
/**
|
|
* Finds the closest parent that matches a selector.
|
|
*
|
|
* @param {Element} element
|
|
* @param {String} selector
|
|
* @return {Function}
|
|
*/
|
|
function closest (element, selector) {
|
|
while (element && element.nodeType !== DOCUMENT_NODE_TYPE) {
|
|
if (typeof element.matches === 'function' &&
|
|
element.matches(selector)) {
|
|
return element;
|
|
}
|
|
element = element.parentNode;
|
|
}
|
|
}
|
|
|
|
module.exports = closest;
|
|
|
|
|
|
/***/ }),
|
|
/* 6 */
|
|
/***/ (function(module, __webpack_exports__, __webpack_require__) {
|
|
|
|
"use strict";
|
|
__webpack_require__.r(__webpack_exports__);
|
|
|
|
// EXTERNAL MODULE: ./node_modules/select/src/select.js
|
|
var src_select = __webpack_require__(0);
|
|
var select_default = /*#__PURE__*/__webpack_require__.n(src_select);
|
|
|
|
// CONCATENATED MODULE: ./src/clipboard-action.js
|
|
var _typeof = typeof Symbol === "function" && typeof Symbol.iterator === "symbol" ? function (obj) { return typeof obj; } : function (obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; };
|
|
|
|
var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }();
|
|
|
|
function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
|
|
|
|
|
|
|
|
/**
|
|
* Inner class which performs selection from either `text` or `target`
|
|
* properties and then executes copy or cut operations.
|
|
*/
|
|
|
|
var clipboard_action_ClipboardAction = function () {
|
|
/**
|
|
* @param {Object} options
|
|
*/
|
|
function ClipboardAction(options) {
|
|
_classCallCheck(this, ClipboardAction);
|
|
|
|
this.resolveOptions(options);
|
|
this.initSelection();
|
|
}
|
|
|
|
/**
|
|
* Defines base properties passed from constructor.
|
|
* @param {Object} options
|
|
*/
|
|
|
|
|
|
_createClass(ClipboardAction, [{
|
|
key: 'resolveOptions',
|
|
value: function resolveOptions() {
|
|
var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
|
|
|
|
this.action = options.action;
|
|
this.container = options.container;
|
|
this.emitter = options.emitter;
|
|
this.target = options.target;
|
|
this.text = options.text;
|
|
this.trigger = options.trigger;
|
|
|
|
this.selectedText = '';
|
|
}
|
|
|
|
/**
|
|
* Decides which selection strategy is going to be applied based
|
|
* on the existence of `text` and `target` properties.
|
|
*/
|
|
|
|
}, {
|
|
key: 'initSelection',
|
|
value: function initSelection() {
|
|
if (this.text) {
|
|
this.selectFake();
|
|
} else if (this.target) {
|
|
this.selectTarget();
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Creates a fake textarea element, sets its value from `text` property,
|
|
* and makes a selection on it.
|
|
*/
|
|
|
|
}, {
|
|
key: 'selectFake',
|
|
value: function selectFake() {
|
|
var _this = this;
|
|
|
|
var isRTL = document.documentElement.getAttribute('dir') == 'rtl';
|
|
|
|
this.removeFake();
|
|
|
|
this.fakeHandlerCallback = function () {
|
|
return _this.removeFake();
|
|
};
|
|
this.fakeHandler = this.container.addEventListener('click', this.fakeHandlerCallback) || true;
|
|
|
|
this.fakeElem = document.createElement('textarea');
|
|
// Prevent zooming on iOS
|
|
this.fakeElem.style.fontSize = '12pt';
|
|
// Reset box model
|
|
this.fakeElem.style.border = '0';
|
|
this.fakeElem.style.padding = '0';
|
|
this.fakeElem.style.margin = '0';
|
|
// Move element out of screen horizontally
|
|
this.fakeElem.style.position = 'absolute';
|
|
this.fakeElem.style[isRTL ? 'right' : 'left'] = '-9999px';
|
|
// Move element to the same position vertically
|
|
var yPosition = window.pageYOffset || document.documentElement.scrollTop;
|
|
this.fakeElem.style.top = yPosition + 'px';
|
|
|
|
this.fakeElem.setAttribute('readonly', '');
|
|
this.fakeElem.value = this.text;
|
|
|
|
this.container.appendChild(this.fakeElem);
|
|
|
|
this.selectedText = select_default()(this.fakeElem);
|
|
this.copyText();
|
|
}
|
|
|
|
/**
|
|
* Only removes the fake element after another click event, that way
|
|
* a user can hit `Ctrl+C` to copy because selection still exists.
|
|
*/
|
|
|
|
}, {
|
|
key: 'removeFake',
|
|
value: function removeFake() {
|
|
if (this.fakeHandler) {
|
|
this.container.removeEventListener('click', this.fakeHandlerCallback);
|
|
this.fakeHandler = null;
|
|
this.fakeHandlerCallback = null;
|
|
}
|
|
|
|
if (this.fakeElem) {
|
|
this.container.removeChild(this.fakeElem);
|
|
this.fakeElem = null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Selects the content from element passed on `target` property.
|
|
*/
|
|
|
|
}, {
|
|
key: 'selectTarget',
|
|
value: function selectTarget() {
|
|
this.selectedText = select_default()(this.target);
|
|
this.copyText();
|
|
}
|
|
|
|
/**
|
|
* Executes the copy operation based on the current selection.
|
|
*/
|
|
|
|
}, {
|
|
key: 'copyText',
|
|
value: function copyText() {
|
|
var succeeded = void 0;
|
|
|
|
try {
|
|
succeeded = document.execCommand(this.action);
|
|
} catch (err) {
|
|
succeeded = false;
|
|
}
|
|
|
|
this.handleResult(succeeded);
|
|
}
|
|
|
|
/**
|
|
* Fires an event based on the copy operation result.
|
|
* @param {Boolean} succeeded
|
|
*/
|
|
|
|
}, {
|
|
key: 'handleResult',
|
|
value: function handleResult(succeeded) {
|
|
this.emitter.emit(succeeded ? 'success' : 'error', {
|
|
action: this.action,
|
|
text: this.selectedText,
|
|
trigger: this.trigger,
|
|
clearSelection: this.clearSelection.bind(this)
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Moves focus away from `target` and back to the trigger, removes current selection.
|
|
*/
|
|
|
|
}, {
|
|
key: 'clearSelection',
|
|
value: function clearSelection() {
|
|
if (this.trigger) {
|
|
this.trigger.focus();
|
|
}
|
|
document.activeElement.blur();
|
|
window.getSelection().removeAllRanges();
|
|
}
|
|
|
|
/**
|
|
* Sets the `action` to be performed which can be either 'copy' or 'cut'.
|
|
* @param {String} action
|
|
*/
|
|
|
|
}, {
|
|
key: 'destroy',
|
|
|
|
|
|
/**
|
|
* Destroy lifecycle.
|
|
*/
|
|
value: function destroy() {
|
|
this.removeFake();
|
|
}
|
|
}, {
|
|
key: 'action',
|
|
set: function set() {
|
|
var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'copy';
|
|
|
|
this._action = action;
|
|
|
|
if (this._action !== 'copy' && this._action !== 'cut') {
|
|
throw new Error('Invalid "action" value, use either "copy" or "cut"');
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Gets the `action` property.
|
|
* @return {String}
|
|
*/
|
|
,
|
|
get: function get() {
|
|
return this._action;
|
|
}
|
|
|
|
/**
|
|
* Sets the `target` property using an element
|
|
* that will be have its content copied.
|
|
* @param {Element} target
|
|
*/
|
|
|
|
}, {
|
|
key: 'target',
|
|
set: function set(target) {
|
|
if (target !== undefined) {
|
|
if (target && (typeof target === 'undefined' ? 'undefined' : _typeof(target)) === 'object' && target.nodeType === 1) {
|
|
if (this.action === 'copy' && target.hasAttribute('disabled')) {
|
|
throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');
|
|
}
|
|
|
|
if (this.action === 'cut' && (target.hasAttribute('readonly') || target.hasAttribute('disabled'))) {
|
|
throw new Error('Invalid "target" attribute. You can\'t cut text from elements with "readonly" or "disabled" attributes');
|
|
}
|
|
|
|
this._target = target;
|
|
} else {
|
|
throw new Error('Invalid "target" value, use a valid Element');
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Gets the `target` property.
|
|
* @return {String|HTMLElement}
|
|
*/
|
|
,
|
|
get: function get() {
|
|
return this._target;
|
|
}
|
|
}]);
|
|
|
|
return ClipboardAction;
|
|
}();
|
|
|
|
/* harmony default export */ var clipboard_action = (clipboard_action_ClipboardAction);
|
|
// EXTERNAL MODULE: ./node_modules/tiny-emitter/index.js
|
|
var tiny_emitter = __webpack_require__(1);
|
|
var tiny_emitter_default = /*#__PURE__*/__webpack_require__.n(tiny_emitter);
|
|
|
|
// EXTERNAL MODULE: ./node_modules/good-listener/src/listen.js
|
|
var listen = __webpack_require__(2);
|
|
var listen_default = /*#__PURE__*/__webpack_require__.n(listen);
|
|
|
|
// CONCATENATED MODULE: ./src/clipboard.js
|
|
var clipboard_typeof = typeof Symbol === "function" && typeof Symbol.iterator === "symbol" ? function (obj) { return typeof obj; } : function (obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; };
|
|
|
|
var clipboard_createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }();
|
|
|
|
function clipboard_classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
|
|
|
|
function _possibleConstructorReturn(self, call) { if (!self) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return call && (typeof call === "object" || typeof call === "function") ? call : self; }
|
|
|
|
function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function, not " + typeof superClass); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, enumerable: false, writable: true, configurable: true } }); if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass; }
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
* Base class which takes one or more elements, adds event listeners to them,
|
|
* and instantiates a new `ClipboardAction` on each click.
|
|
*/
|
|
|
|
var clipboard_Clipboard = function (_Emitter) {
|
|
_inherits(Clipboard, _Emitter);
|
|
|
|
/**
|
|
* @param {String|HTMLElement|HTMLCollection|NodeList} trigger
|
|
* @param {Object} options
|
|
*/
|
|
function Clipboard(trigger, options) {
|
|
clipboard_classCallCheck(this, Clipboard);
|
|
|
|
var _this = _possibleConstructorReturn(this, (Clipboard.__proto__ || Object.getPrototypeOf(Clipboard)).call(this));
|
|
|
|
_this.resolveOptions(options);
|
|
_this.listenClick(trigger);
|
|
return _this;
|
|
}
|
|
|
|
/**
|
|
* Defines if attributes would be resolved using internal setter functions
|
|
* or custom functions that were passed in the constructor.
|
|
* @param {Object} options
|
|
*/
|
|
|
|
|
|
clipboard_createClass(Clipboard, [{
|
|
key: 'resolveOptions',
|
|
value: function resolveOptions() {
|
|
var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
|
|
|
|
this.action = typeof options.action === 'function' ? options.action : this.defaultAction;
|
|
this.target = typeof options.target === 'function' ? options.target : this.defaultTarget;
|
|
this.text = typeof options.text === 'function' ? options.text : this.defaultText;
|
|
this.container = clipboard_typeof(options.container) === 'object' ? options.container : document.body;
|
|
}
|
|
|
|
/**
|
|
* Adds a click event listener to the passed trigger.
|
|
* @param {String|HTMLElement|HTMLCollection|NodeList} trigger
|
|
*/
|
|
|
|
}, {
|
|
key: 'listenClick',
|
|
value: function listenClick(trigger) {
|
|
var _this2 = this;
|
|
|
|
this.listener = listen_default()(trigger, 'click', function (e) {
|
|
return _this2.onClick(e);
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Defines a new `ClipboardAction` on each click event.
|
|
* @param {Event} e
|
|
*/
|
|
|
|
}, {
|
|
key: 'onClick',
|
|
value: function onClick(e) {
|
|
var trigger = e.delegateTarget || e.currentTarget;
|
|
|
|
if (this.clipboardAction) {
|
|
this.clipboardAction = null;
|
|
}
|
|
|
|
this.clipboardAction = new clipboard_action({
|
|
action: this.action(trigger),
|
|
target: this.target(trigger),
|
|
text: this.text(trigger),
|
|
container: this.container,
|
|
trigger: trigger,
|
|
emitter: this
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Default `action` lookup function.
|
|
* @param {Element} trigger
|
|
*/
|
|
|
|
}, {
|
|
key: 'defaultAction',
|
|
value: function defaultAction(trigger) {
|
|
return getAttributeValue('action', trigger);
|
|
}
|
|
|
|
/**
|
|
* Default `target` lookup function.
|
|
* @param {Element} trigger
|
|
*/
|
|
|
|
}, {
|
|
key: 'defaultTarget',
|
|
value: function defaultTarget(trigger) {
|
|
var selector = getAttributeValue('target', trigger);
|
|
|
|
if (selector) {
|
|
return document.querySelector(selector);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns the support of the given action, or all actions if no action is
|
|
* given.
|
|
* @param {String} [action]
|
|
*/
|
|
|
|
}, {
|
|
key: 'defaultText',
|
|
|
|
|
|
/**
|
|
* Default `text` lookup function.
|
|
* @param {Element} trigger
|
|
*/
|
|
value: function defaultText(trigger) {
|
|
return getAttributeValue('text', trigger);
|
|
}
|
|
|
|
/**
|
|
* Destroy lifecycle.
|
|
*/
|
|
|
|
}, {
|
|
key: 'destroy',
|
|
value: function destroy() {
|
|
this.listener.destroy();
|
|
|
|
if (this.clipboardAction) {
|
|
this.clipboardAction.destroy();
|
|
this.clipboardAction = null;
|
|
}
|
|
}
|
|
}], [{
|
|
key: 'isSupported',
|
|
value: function isSupported() {
|
|
var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ['copy', 'cut'];
|
|
|
|
var actions = typeof action === 'string' ? [action] : action;
|
|
var support = !!document.queryCommandSupported;
|
|
|
|
actions.forEach(function (action) {
|
|
support = support && !!document.queryCommandSupported(action);
|
|
});
|
|
|
|
return support;
|
|
}
|
|
}]);
|
|
|
|
return Clipboard;
|
|
}(tiny_emitter_default.a);
|
|
|
|
/**
|
|
* Helper function to retrieve attribute value.
|
|
* @param {String} suffix
|
|
* @param {Element} element
|
|
*/
|
|
|
|
|
|
function getAttributeValue(suffix, element) {
|
|
var attribute = 'data-clipboard-' + suffix;
|
|
|
|
if (!element.hasAttribute(attribute)) {
|
|
return;
|
|
}
|
|
|
|
return element.getAttribute(attribute);
|
|
}
|
|
|
|
/* harmony default export */ var clipboard = __webpack_exports__["default"] = (clipboard_Clipboard);
|
|
|
|
/***/ })
|
|
/******/ ])["default"];
|
|
});
|
|
</script>
|
|
<!-- Foldable TOC -->
|
|
|
|
<style>
|
|
#tocbot a.toc-link.node-name--H1{ font-style: italic }
|
|
@media screen{
|
|
#tocbot > ul.toc-list{ margin-bottom: 0.5em; margin-left: 0.125em }
|
|
#tocbot ul.sectlevel0, #tocbot a.toc-link.node-name--H1 + ul{
|
|
padding-left: 0 }
|
|
#tocbot a.toc-link{ height:100% }
|
|
.is-collapsible{ max-height:3000px; overflow:hidden; }
|
|
.is-collapsed{ max-height:0 }
|
|
.is-active-link{ font-weight:700 }
|
|
}
|
|
@media print{
|
|
#tocbot a.toc-link.node-name--H4{ display:none }
|
|
}
|
|
</style>
|
|
|
|
<!-- Copy to clipboard button in sourc code listings -->
|
|
|
|
<style>
|
|
.listingblock:hover .clipboard {
|
|
display: block;
|
|
}
|
|
|
|
.clipboard {
|
|
display: none;
|
|
border: 0;
|
|
font-size: .75em;
|
|
text-transform: uppercase;
|
|
font-weight: 500;
|
|
padding: 6px;
|
|
color: #999;
|
|
position: absolute;
|
|
top: .425rem;
|
|
right: .5rem;
|
|
background: transparent;
|
|
}
|
|
|
|
code + .clipboard {
|
|
top: -0.05rem !important;
|
|
right: 3rem !important;
|
|
}
|
|
|
|
.clipboard:hover, .clipboard:focus, .clipboard:active {
|
|
outline: 0;
|
|
background-color: #eee9e6;
|
|
}
|
|
</style>
|
|
<script>
|
|
$(function() {
|
|
|
|
var pre = document.getElementsByTagName('pre');
|
|
for (var i = 0; i < pre.length; i++) {
|
|
var b = document.createElement('input');
|
|
b.setAttribute('role', 'button');
|
|
b.setAttribute('type', 'button');
|
|
b.value = 'Copy';
|
|
b.className = 'clipboard';
|
|
|
|
if (pre[i].childNodes.length === 1 && pre[i].childNodes[0].nodeType === 3) {
|
|
var div = document.createElement('div');
|
|
div.textContent = pre[i].textContent;
|
|
pre[i].textContent = '';
|
|
pre[i].appendChild(div);
|
|
}
|
|
pre[i].appendChild(b);
|
|
}
|
|
|
|
new ClipboardJS('.clipboard', {
|
|
text: function(b) {
|
|
return b.parentNode.innerText;
|
|
}
|
|
}).on('success', function(e) {
|
|
e.clearSelection();
|
|
e.trigger.value = 'Copied';
|
|
setTimeout(function() {
|
|
e.trigger.value = 'Copy';
|
|
}, 2000);
|
|
});
|
|
});
|
|
</script>
|
|
<style>
|
|
|
|
.hidden {
|
|
|
|
display: none;
|
|
|
|
}
|
|
|
|
|
|
|
|
.switch {
|
|
|
|
border-width: 1px 1px 0 1px;
|
|
|
|
border-style: solid;
|
|
|
|
border-color: #7a2518;
|
|
|
|
display: inline-block;
|
|
|
|
}
|
|
|
|
|
|
|
|
.switch--item {
|
|
|
|
padding: 10px;
|
|
|
|
background-color: #ffffff;
|
|
|
|
color: #7a2518;
|
|
|
|
display: inline-block;
|
|
|
|
cursor: pointer;
|
|
|
|
}
|
|
|
|
|
|
|
|
.switch--item.selected {
|
|
|
|
background-color: #7a2519;
|
|
|
|
color: #ffffff;
|
|
|
|
}
|
|
|
|
|
|
|
|
</style>
|
|
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
|
|
|
|
<script type="text/javascript">
|
|
|
|
function addBlockSwitches() {
|
|
|
|
$('.primary').each(function() {
|
|
|
|
primary = $(this);
|
|
|
|
createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected");
|
|
|
|
primary.children('.title').remove();
|
|
|
|
});
|
|
|
|
$('.secondary').each(function(idx, node) {
|
|
|
|
secondary = $(node);
|
|
|
|
primary = findPrimary(secondary);
|
|
|
|
switchItem = createSwitchItem(secondary, primary.children('.switch'));
|
|
|
|
switchItem.content.addClass('hidden');
|
|
|
|
findPrimary(secondary).append(switchItem.content);
|
|
|
|
secondary.remove();
|
|
|
|
});
|
|
|
|
}
|
|
|
|
|
|
|
|
function createBlockSwitch(primary) {
|
|
|
|
blockSwitch = $('<div class="switch"></div>');
|
|
|
|
primary.prepend(blockSwitch);
|
|
|
|
return blockSwitch;
|
|
|
|
}
|
|
|
|
|
|
|
|
function findPrimary(secondary) {
|
|
|
|
candidate = secondary.prev();
|
|
|
|
while (!candidate.is('.primary')) {
|
|
|
|
candidate = candidate.prev();
|
|
|
|
}
|
|
|
|
return candidate;
|
|
|
|
}
|
|
|
|
|
|
|
|
function createSwitchItem(block, blockSwitch) {
|
|
|
|
blockName = block.children('.title').text();
|
|
|
|
content = block.children('.content').first().append(block.next('.colist'));
|
|
|
|
item = $('<div class="switch--item">' + blockName + '</div>');
|
|
|
|
item.on('click', '', content, function(e) {
|
|
|
|
$(this).addClass('selected');
|
|
|
|
$(this).siblings().removeClass('selected');
|
|
|
|
e.data.siblings('.content').addClass('hidden');
|
|
|
|
e.data.removeClass('hidden');
|
|
|
|
});
|
|
|
|
blockSwitch.append(item);
|
|
|
|
return {'item': item, 'content': content};
|
|
|
|
}
|
|
|
|
|
|
|
|
$(addBlockSwitches);
|
|
|
|
|
|
|
|
</script>
|
|
|
|
|
|
</head>
|
|
<body class="article toc2 toc-left">
|
|
<div id="header">
|
|
<h1>Quick Guide</h1>
|
|
<div class="details">
|
|
<span id="revnumber">version 4.5.2,</span>
|
|
<span id="revdate">2020-10-14</span>
|
|
</div>
|
|
<div id="toc" class="toc2">
|
|
<div id="toctitle">Features</div>
|
|
<ul class="sectlevel1">
|
|
<li><a href="#_what_is_picocli">1. What is picocli</a></li>
|
|
<li><a href="#_basic_example">2. Basic example</a></li>
|
|
<li><a href="#_subcommands_example">3. Subcommands Example</a></li>
|
|
<li><a href="#_options_and_parameters">4. Options and Parameters</a></li>
|
|
<li><a href="#_strongly_typed_everything">5. Strongly Typed Everything</a></li>
|
|
<li><a href="#_required_arguments">6. Required Arguments</a></li>
|
|
<li><a href="#_multiple_values">7. Multiple Values</a></li>
|
|
<li><a href="#_help_options">8. Help Options</a></li>
|
|
<li><a href="#_version_help">9. Version Help</a></li>
|
|
<li><a href="#_usage_help">10. Usage Help</a></li>
|
|
<li><a href="#_ansi_colors_and_styles">11. ANSI Colors and Styles</a></li>
|
|
<li><a href="#_subcommands">12. Subcommands</a></li>
|
|
<li><a href="#_reuse">13. Reuse</a></li>
|
|
<li><a href="#_executing_commands">14. Executing Commands</a></li>
|
|
<li><a href="#_tracing">15. Tracing</a></li>
|
|
<li><a href="#_tab_autocomplete">16. TAB Autocomplete</a></li>
|
|
<li><a href="#_more">17. More</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div id="content">
|
|
<div id="preamble">
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>This is the Quick Guide. For more detail, see the full user manual at <a href="http://picocli.info">http://picocli.info</a>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_what_is_picocli"><a class="anchor" href="#_what_is_picocli"></a>1. What is picocli</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Picocli is a one-file framework for creating Java command line applications with almost zero code.
|
|
Picocli aims to be the easiest way to create rich command line applications that can run on and off the JVM.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more.
|
|
It generates highly customizable usage help messages with <a href="#_ansi_colors_and_styles">ANSI colors and styles</a>.
|
|
Picocli-based applications can have <a href="autocomplete.html">command line TAB completion</a> showing available options, option parameters and subcommands, for any level of nested subcommands.
|
|
Picocli-based applications can be ahead-of-time compiled to a <span class="image"><img src="https://www.graalvm.org/resources/img/logo-colored.svg" alt="GraalVM"></span>
|
|
<a href="https://picocli.info/#_graalvm_native_image">native image</a>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli <a href="https://picocli.info/#_generate_man_page_documentation">generates beautiful documentation</a> for your application (HTML, PDF and Unix man pages).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<div class="title">Example usage help message</div>
|
|
<p><span class="image"><img src="images/ExampleUsageANSI.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-note" title="Note"></i>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>This document uses picocli’s annotation API.
|
|
For applications that cannot use the annotations, there is also a <a href="picocli-programmatic-api.html">programmatic API</a> for defining what options and positional parameters to expect, and for handling parse results.
|
|
The programmatic API is not covered in this Quick Guide.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_basic_example"><a class="anchor" href="#_basic_example"></a>2. <a id="_example_applications"></a><a id="Basic_example_ASCIIArt"></a>Basic example</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Below we show a small but fully functional example picocli-based command line application: <code>ASCIIArt</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>ASCIIArt</code> converts one or more arguments into ASCII art and prints them out. It can be used as follows:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Invoking the command</div>
|
|
<div class="content">
|
|
<pre>$ java -cp "myapp.jar;picocli-4.5.2-SNAPSHOT.jar" ASCIIArt --font-size=9 Hello picocli
|
|
# # # # # # #
|
|
# # # # #
|
|
# # *** # # **** #*** # **# **** **# # #
|
|
##### *** # # **** #*** # ** **** ** # #
|
|
# # *#* # # * * # * # * * * * # #
|
|
# # ** # # **** #*** # ** **** ** # #
|
|
# # **# # # **** #*** # **# **** **# # #
|
|
#
|
|
*</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>The user manual has details on <a href="https://picocli.info/#_packaging_your_application">packaging your CLI application</a> so that users can invoke it simply with:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>ASCIIArt --font-size=9 Hello picocli</pre>
|
|
</div>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_asciiart_source_code_explained"><a class="anchor" href="#_asciiart_source_code_explained"></a>2.1. ASCIIArt source code explained</h3>
|
|
<div class="listingblock">
|
|
<div class="title">ASCIIArt source code, shortened</div>
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Command</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Option</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Parameters</span>;
|
|
<span class="comment">// some exports omitted for the sake of brevity</span>
|
|
|
|
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">ASCIIArt</span><span class="delimiter">"</span></span>, version = <span class="string"><span class="delimiter">"</span><span class="content">ASCIIArt 1.0</span><span class="delimiter">"</span></span>, mixinStandardHelpOptions = <span class="predefined-constant">true</span>) <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="directive">public</span> <span class="type">class</span> <span class="class">ASCIIArt</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> { <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">"</span><span class="content">-s</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--font-size</span><span class="delimiter">"</span></span> }, description = <span class="string"><span class="delimiter">"</span><span class="content">Font size</span><span class="delimiter">"</span></span>) <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="type">int</span> fontSize = <span class="integer">19</span>;
|
|
|
|
<span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">"</span><span class="content"><word></span><span class="delimiter">"</span></span>, defaultValue = <span class="string"><span class="delimiter">"</span><span class="content">Hello, picocli</span><span class="delimiter">"</span></span>, <i class="conum" data-value="4"></i><b>(4)</b>
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">Words to be translated into ASCII art.</span><span class="delimiter">"</span></span>)
|
|
<span class="directive">private</span> <span class="predefined-type">String</span><span class="type">[]</span> words = { <span class="string"><span class="delimiter">"</span><span class="content">Hello,</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">picocli</span><span class="delimiter">"</span></span> }; <i class="conum" data-value="5"></i><b>(5)</b>
|
|
|
|
<span class="annotation">@Override</span>
|
|
<span class="directive">public</span> <span class="type">void</span> run() { <i class="conum" data-value="6"></i><b>(6)</b>
|
|
<span class="comment">// The business logic of the command goes here...</span>
|
|
<span class="comment">// In this case, code for generation of ASCII art graphics</span>
|
|
<span class="comment">// (omitted for the sake of brevity).</span>
|
|
}
|
|
|
|
<span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
|
|
<span class="type">int</span> exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> ASCIIArt()).execute(args); <i class="conum" data-value="7"></i><b>(7)</b>
|
|
<span class="predefined-type">System</span>.exit(exitCode); <i class="conum" data-value="8"></i><b>(8)</b>
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Let’s break it down into small steps:</p>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<table>
|
|
<tr>
|
|
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
|
<td>Create a class that implements <code>Runnable</code> or <code>Callable</code>. This is your command.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
|
<td>Annotate the class with <code>@Command</code> and give it a name. The <a href="#_mixin_standard_help_options">mixinStandardHelpOptions</a> attribute adds <code>--help</code> and <code>--version</code> options to your application.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
|
<td>For each option in your application, add an <code>@Option</code>-annotated field to your command class. This example shows how you can give the options names and a description, there are many other attributes.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
|
<td>For each positional parameter, add a <code>@Parameters</code>-annotated field to your command class.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
|
<td>Picocli will convert the command line arguments to strongly typed values and will inject these values into the annotated fields.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
|
<td>Define your business logic in the <code>run</code> or <code>call</code> method of your class. This method is called after parsing is successfully completed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="7"></i><b>7</b></td>
|
|
<td>In the <code>main</code> method of your class, use the <code>CommandLine.execute</code> method bootstrap your application.
|
|
This will parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="8"></i><b>8</b></td>
|
|
<td>The <code>CommandLine.execute</code> method returns an exit code. Your application can call <code>System.exit</code> with this exit code to signal success or failure to the calling process.</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This is the basic skeleton of almost any picocli application.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
See the <a href="http://picocli.info/">reference manual</a> for more variations, like using the annotations on methods.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Like any professional command line application, <code>ASCIIArt</code> has <code>--help</code> and <code>--version</code> options.
|
|
The <code>--help</code> option shows the user how to use the application.
|
|
Picocli generates this usage help message automatically:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Usage help message of our <code>ASCIIArt</code> command</div>
|
|
<div class="content">
|
|
<pre>$ ASCIIArt --help
|
|
Usage: ASCIIArt [-hV] [-s=<fontsize>] [<word>...]
|
|
[<word>...] Words to be translated into ASCII art.
|
|
-s, --font-size=<fontSize> Font size
|
|
-h, --help Show this help message and exit.
|
|
-V, --version Print version information and exit.</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_asciiart_execution_try_it"><a class="anchor" href="#_asciiart_execution_try_it"></a>2.2. ASCIIArt execution: try it!</h3>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-note" title="Note"></i>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>The content below shows the source code of the <code>ASCIIArt</code> example, embedded in the page using technology provided by <a href="https://www.jdoodle.com">jdoodle.com</a> that allows online execution.
|
|
If the content is not displaying correctly, try opening <a href="https://www.jdoodle.com/embed/v0/2nfL?stdin=1&arg=1">this link</a> in a separate browser tab.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Execute the <code>ASCIIArt</code> example by clicking the blue <code>Execute</code> button below.</p>
|
|
</div>
|
|
<div data-pym-src="https://www.jdoodle.com/embed/v0/2nfL?stdin=1&arg=1"></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_subcommands_example"><a class="anchor" href="#_subcommands_example"></a>3. <a id="Subcommands_Example_ISOCodeResolver"></a>Subcommands Example</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Below we show another small but fully functional example picocli-based command line application which explains the use of subcommands: <code>ISOCodeResolver</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This application has two subcommands, <code>language</code> and <code>country</code>, that resolve languages or country codes following the ISO standards (ISO-3166-1 for country codes, and ISO-639-1/639-2 for language codes).
|
|
The application can be used as follows:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Resolving two letter language codes</div>
|
|
<div class="content">
|
|
<pre>$ java -cp "myapp.jar;picocli-4.5.2-SNAPSHOT.jar" ISOCodeResolver language de cs en sd se
|
|
de: German
|
|
cs: Czech
|
|
en: English
|
|
sd: Sindhi
|
|
se: Northern Sami</pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Resolving two letter country codes</div>
|
|
<div class="content">
|
|
<pre>$ java -cp "myapp.jar;picocli-4.5.2-SNAPSHOT.jar" ISOCodeResolver country cn fr th ro no
|
|
CN: China
|
|
FR: France
|
|
TH: Thailand
|
|
RO: Romania
|
|
NO: Norway</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>The user manual has details on <a href="https://picocli.info/#_packaging_your_application">packaging your CLI application</a> so that users can invoke these commands simply with:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>ISOCodeResolver language de cs en sd se</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>and</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>ISOCodeResolver country cn fr th ro no</pre>
|
|
</div>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_isocoderesolver_source_code_explained"><a class="anchor" href="#_isocoderesolver_source_code_explained"></a>3.1. ISOCodeResolver source code explained</h3>
|
|
<div class="listingblock">
|
|
<div class="title">ISOCodeResolver source code</div>
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Command</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Model.CommandSpec</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Parameters</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.ParameterException</span>;
|
|
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Spec</span>;
|
|
<span class="keyword">import</span> <span class="include">java.util.Locale</span>;
|
|
|
|
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">ISOCodeResolver</span><span class="delimiter">"</span></span>,
|
|
subcommands = { SubcommandAsClass.class, CommandLine.HelpCommand.class }, <i class="conum" data-value="2"></i><b>(2)</b>
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">Resolves ISO country codes (ISO-3166-1) or language codes (ISO 639-1/-2)</span><span class="delimiter">"</span></span>)
|
|
<span class="directive">public</span> <span class="type">class</span> <span class="class">ISOCodeResolver</span> { <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="annotation">@Spec</span> CommandSpec spec;
|
|
|
|
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">country</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">Resolves ISO country codes (ISO-3166-1)</span><span class="delimiter">"</span></span>) <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="type">void</span> subCommandViaMethod(
|
|
<span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">"</span><span class="content">1..*</span><span class="delimiter">"</span></span>, paramLabel = <span class="string"><span class="delimiter">"</span><span class="content"><countryCode></span><span class="delimiter">"</span></span>,
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">country code(s) to be resolved</span><span class="delimiter">"</span></span>) <span class="predefined-type">String</span><span class="type">[]</span> countryCodes) {
|
|
|
|
<span class="keyword">for</span> (<span class="predefined-type">String</span> code : countryCodes) {
|
|
<span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">"</span><span class="content">%s: %s</span><span class="delimiter">"</span></span>,
|
|
code.toUpperCase(), <span class="keyword">new</span> <span class="predefined-type">Locale</span>(<span class="string"><span class="delimiter">"</span><span class="delimiter">"</span></span>, code).getDisplayCountry());
|
|
}
|
|
}
|
|
|
|
<span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
|
|
<span class="type">int</span> exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> ISOCodeResolver()).execute(args); <i class="conum" data-value="5"></i><b>(5)</b>
|
|
<span class="predefined-type">System</span>.exit(exitCode); <i class="conum" data-value="6"></i><b>(6)</b>
|
|
}
|
|
}
|
|
|
|
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">language</span><span class="delimiter">"</span></span>,
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">Resolves one ore more ISO language codes (ISO-639-1 or 639-2)</span><span class="delimiter">"</span></span>) <i class="conum" data-value="4"></i><b>(4)</b>
|
|
<span class="type">class</span> <span class="class">SubcommandAsClass</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
|
|
|
|
<span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">"</span><span class="content">1..*</span><span class="delimiter">"</span></span>, paramLabel = <span class="string"><span class="delimiter">"</span><span class="content"><languageCode></span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">language code(s)</span><span class="delimiter">"</span></span>)
|
|
<span class="directive">private</span> <span class="predefined-type">String</span><span class="type">[]</span> languageCodes;
|
|
|
|
<span class="annotation">@Override</span>
|
|
<span class="directive">public</span> <span class="type">void</span> run() {
|
|
<span class="keyword">for</span> (<span class="predefined-type">String</span> code : languageCodes) {
|
|
<span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">"</span><span class="content">%s: %s</span><span class="delimiter">"</span></span>,
|
|
code.toLowerCase(), <span class="keyword">new</span> <span class="predefined-type">Locale</span>(code).getDisplayLanguage());
|
|
}
|
|
}
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Let’s break it down into small steps:</p>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<table>
|
|
<tr>
|
|
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
|
<td>When the top-level command does not implement <code>Runnable</code> or <code>Callable</code>, users must specify a subcommand (subcommands become mandatory).
|
|
This is optional: simply implement <code>Runnable</code> or <code>Callable</code> if the parent command can be executed by itself without subcommands in your application.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
|
<td>Annotate the class with <code>@Command</code> and give it a name.
|
|
Note that we also specify the <a href="https://picocli.info/apidocs/picocli/CommandLine.HelpCommand.html">CommandLine.HelpCommand</a> class as subcommand in the annotation, to add the built-in <code>help</code> subcommand.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
|
<td>Custom subcommands can be added to the top-level command in two ways.
|
|
The easiest way is to add a <code>@Command</code>-annotated method to the command class.
|
|
For each option and positional parameter of the subcommand, add a method argument, and annotate these method arguments with the <code>@Option</code> or <code>@Parameters</code> annotation.
|
|
In the example above, once the user invokes the subcommand <code>country</code>, the associated method <code>subCommandViaMethod</code> gets called.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
|
<td>In larger applications, it is common to create a separate <code>@Command</code>-annotated class for each subcommand.
|
|
In the example above, the <code>SubcommandAsClass</code> class represents the <code>language</code> subcommand.
|
|
Once the user invokes this subcommand, the overridden <code>run</code> method of this class is called.
|
|
To register the subcommand, specify the subcommand class in the <code>subcommands</code> attribute of the <code>@Command</code> annotation of the parent command (subcommands = { SubcommandAsClass.class, …​ } ❷).</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
|
<td>In the <code>main</code> method of our <code>ISOCodeResolver</code> class, we use the <code>CommandLine.execute</code> method to bootstrap our application.
|
|
This will parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic of the associated subcommands.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
|
<td>The <code>CommandLine.execute</code> method returns an exit code.
|
|
The application can call <code>System.exit</code> with this exit code to signal success or failure to the calling process.</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This is the basic skeleton of an picocli application with subcommands.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
See the <a href="https://picocli.info/#_subcommands/">Subcommands chapter</a> of the reference manual for more details and aspects of subcommands.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In addition to the two user defined subcommands, the <code>ISOCodeResolver</code> app offers a <code>help</code> subcommand, which prints the usage help message to the console.
|
|
Picocli generates this usage help message automatically:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Usage help message of our <code>ISOCodeResolver</code> command</div>
|
|
<div class="content">
|
|
<pre>$ ISOCodeResolver help
|
|
Usage: ISOCodeResolver [COMMAND]
|
|
Resolves ISO country codes (ISO-3166-1) or language codes (ISO-639-1/-2)
|
|
Commands:
|
|
help Displays help information about the specified command
|
|
country Resolves ISO country codes (ISO-3166-1)
|
|
language Resolves one ore more ISO language codes (ISO-639-1 or 639-2)</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_isocoderesolver_execution_try_it"><a class="anchor" href="#_isocoderesolver_execution_try_it"></a>3.2. ISOCodeResolver execution: try it!</h3>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-note" title="Note"></i>
|
|
</td>
|
|
<td class="content">
|
|
<div class="paragraph">
|
|
<p>The content below shows the source code of the <code>ISOCodeResolver</code> example, embedded in the page using technology provided by <a href="https://www.jdoodle.com">jdoodle.com</a> that allows online execution.
|
|
If the content is not displaying correctly, try opening <a href="https://www.jdoodle.com/embed/v0/2mpW?stdin=1&arg=1">this link</a> in a separate browser tab.</p>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Execute the <code>ISOCodeResolver</code> example by clicking the blue <code>Execute</code> button below.</p>
|
|
</div>
|
|
<div data-pym-src="https://www.jdoodle.com/embed/v0/2mpW?stdin=1&arg=1"></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_options_and_parameters"><a class="anchor" href="#_options_and_parameters"></a>4. Options and Parameters</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Command line arguments can be separated into <em>options</em> and <em>positional parameters</em>.
|
|
Options have a name, positional parameters are usually the values that follow the options,
|
|
but they may be mixed.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><span class="image"><img src="images/OptionsAndParameters2.png" alt="Example command with annotated @Option and @Parameters"></span></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli has separate annotations for options and positional parameters.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_options"><a class="anchor" href="#_options"></a>4.1. Options</h3>
|
|
<div class="paragraph">
|
|
<p>An option must have one or more <code>names</code>.
|
|
Option names commonly start with <code>-</code> or <code>--</code>, but picocli lets you use any option name you want.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The below example shows options with one or more names, options that take an option parameter, and a <a href="#_help_options">help</a> option.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Tar</span> {
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-c</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">create a new archive</span><span class="delimiter">"</span></span>)
|
|
<span class="type">boolean</span> create;
|
|
|
|
<span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">"</span><span class="content">-f</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--file</span><span class="delimiter">"</span></span> }, paramLabel = <span class="string"><span class="delimiter">"</span><span class="content">ARCHIVE</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">the archive file</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">File</span> archive;
|
|
|
|
<span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">"</span><span class="content">FILE</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">one ore more files to archive</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">File</span><span class="type">[]</span> files;
|
|
|
|
<span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">"</span><span class="content">-h</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--help</span><span class="delimiter">"</span></span> }, usageHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">"</span><span class="content">display a help message</span><span class="delimiter">"</span></span>)
|
|
<span class="directive">private</span> <span class="type">boolean</span> helpRequested;
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli matches the option names to set the field values.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">"</span><span class="content">-c</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--file</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">result.tar</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">file1.txt</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">file2.txt</span><span class="delimiter">"</span></span> };
|
|
Tar tar = <span class="keyword">new</span> Tar();
|
|
<span class="keyword">new</span> CommandLine(tar).parseArgs(args);
|
|
|
|
<span class="keyword">assert</span> !tar.helpRequested;
|
|
<span class="keyword">assert</span> tar.create;
|
|
<span class="keyword">assert</span> tar.archive.equals(<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">result.tar</span><span class="delimiter">"</span></span>));
|
|
<span class="keyword">assert</span> <span class="predefined-type">Arrays</span>.equals(tar.files, <span class="keyword">new</span> <span class="predefined-type">File</span><span class="type">[]</span> {<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">file1.txt</span><span class="delimiter">"</span></span>), <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">file2.txt</span><span class="delimiter">"</span></span>)});</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli supports <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02">POSIX clustered short options</a>:
|
|
one or more single-character options without option-arguments, followed by at most one option with an option-argument, can be grouped behind one ‘-’ dash.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example, for the <code>Tar</code> example above, the following command line invocations are equivalent:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Example commands with clustered short options</div>
|
|
<div class="content">
|
|
<pre>tar -c -f result.tar f1.txt f2.txt
|
|
tar -cf result.tar f1.txt f2.txt
|
|
tar -cfresult.tar f1.txt f2.txt</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_interactive_password_options"><a class="anchor" href="#_interactive_password_options"></a>4.2. Interactive (Password) Options</h3>
|
|
<div class="paragraph">
|
|
<p>For options and positional parameters marked as <code>interactive</code>, the user is prompted to enter a value on the console.
|
|
When running on Java 6 or higher, picocli will use the <a href="https://docs.oracle.com/javase/8/docs/api/java/io/Console.html#readPassword-java.lang.String-java.lang.Object…​-"><code>Console.readPassword</code></a> API so that user input is not echoed to the console.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The user manual has an <a href="http://picocli.info/#_interactive_password_options">example</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_positional_parameters"><a class="anchor" href="#_positional_parameters"></a>4.3. Positional Parameters</h3>
|
|
<div class="paragraph">
|
|
<p>Any command line arguments that are not subcommands, options or option parameters are interpreted as positional parameters.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Use the (zero-based) <code>index</code> attribute to specify exactly which parameters to capture.
|
|
Omitting the <code>index</code> attribute means the field captures <em>all</em> positional parameters.
|
|
Array or collection fields can capture multiple values.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>index</code> attribute accepts <em>range</em> values, so an annotation like <code>@Parameters(index = "2..4")</code> captures the arguments at index 2, 3 and 4. Range values can be <em>open-ended</em>. For example, <code>@Parameters(index = "3..*")</code> captures all arguments from index 3 and up.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">PositionalDemo</span> {
|
|
<span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span>) <span class="predefined-type">InetAddress</span> host;
|
|
<span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) <span class="type">int</span> port;
|
|
<span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">"</span><span class="content">2..*</span><span class="delimiter">"</span></span>) <span class="predefined-type">List</span><<span class="predefined-type">File</span>> files;
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli initializes fields with the values at the specified index in the arguments array.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">12345</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">file1.txt</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">file2.txt</span><span class="delimiter">"</span></span> };
|
|
PositionalDemo params = CommandLine.populateCommand(<span class="keyword">new</span> PositionalDemo(), args);
|
|
|
|
<span class="keyword">assert</span> params.host.getHostName().equals(<span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>);
|
|
<span class="keyword">assert</span> params.port == <span class="integer">12345</span>;
|
|
<span class="keyword">assert</span> params.files.equals(<span class="predefined-type">Arrays</span>.asList(<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">file1.txt</span><span class="delimiter">"</span></span>), <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">file2.txt</span><span class="delimiter">"</span></span>)));</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The user manual has more details about options and positional parameters, as well as the <code>--</code> <a href="http://picocli.info/#_double_dash_code_code">end-of-options delimiter</a> and parameter files (<a href="http://picocli.info/#AtFiles"><code>@</code>-files</a>).</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_strongly_typed_everything"><a class="anchor" href="#_strongly_typed_everything"></a>5. Strongly Typed Everything</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>When command line options and positional parameters are mapped to the annotated fields,
|
|
the text value is converted to the type of the annotated field.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_type_conversion"><a class="anchor" href="#_type_conversion"></a>5.1. Type Conversion</h3>
|
|
<div class="paragraph">
|
|
<p>Out of the box, picocli can convert command line argument strings to a number of common data types.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See the user manual for the full list of <a href="http://picocli.info/#_built_in_types">built-in types</a>, but in general all primitive types and their Object equivalent,
|
|
any enum, and common classes like <code>File</code>, <code>Date</code>, <code>URL</code>, <code>BigDecimal</code>, regex <code>Pattern</code> etc. can be used as is.
|
|
Applications running on Java 7 can use <code>Path</code>, and on Java 8 the new <code>java.time</code> classes can be used.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>You can also use a <a href="http://picocli.info/#_custom_type_converters">custom type converter</a> to handle data types other than the above built-in ones.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_collections_and_maps"><a class="anchor" href="#_collections_and_maps"></a>5.2. Collections and Maps</h3>
|
|
<div class="paragraph">
|
|
<p>If an option or positional parameter can have multiple values, the field type must be an array, a <code>Collection</code> or a <code>Map</code>.
|
|
Any <code>Collection</code> subclass like <code>List</code>, <code>Set</code>, or <code>Queue</code> can be used.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A common requirement is to have options with key-value pairs similar to Java’s system properties, like <code>-Dkey=value</code>.
|
|
To achieve this, all you need to do is use a <code>Map</code> field.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>Map</code> fields may have any type for their key and value
|
|
as long as a <a href="#_strongly_typed_everything">type converter</a> is registered for both the key and the value type.
|
|
Key and value types are inferred from the map’s generic type parameters.
|
|
For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MapDemo</span> {
|
|
<span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">"</span><span class="content">-u</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--timeUnit</span><span class="delimiter">"</span></span>});
|
|
<span class="predefined-type">Map</span><java.util.concurrent.TimeUnit, <span class="predefined-type">Long</span>> timeout;
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The following command line would result in four key-value entries in the map:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="bash"><command> -uDAYS=3 -u HOURS=23 -u=MINUTES=59 --timeUnit=SECONDS=13</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_required_arguments"><a class="anchor" href="#_required_arguments"></a>6. Required Arguments</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_required_options"><a class="anchor" href="#_required_options"></a>6.1. Required Options</h3>
|
|
<div class="paragraph">
|
|
<p>Options can be marked <code>required</code> to make it mandatory for the user to specify them on the command line. When a required option is not specified, a <code>MissingParameterException</code> is thrown from the <code>parse</code> method. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-n</span><span class="delimiter">"</span></span>, required = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">"</span><span class="content">mandatory number</span><span class="delimiter">"</span></span>)
|
|
<span class="type">int</span> number;</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_required_parameters"><a class="anchor" href="#_required_parameters"></a>6.2. Required Parameters</h3>
|
|
<div class="paragraph">
|
|
<p>Use the <code>arity</code> attribute to make <code>@Parameters</code> mandatory:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">"</span><span class="content">1..*</span><span class="delimiter">"</span></span>, descriptions = <span class="string"><span class="delimiter">"</span><span class="content">at least one File</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">List</span><<span class="predefined-type">File</span>> files;</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_multiple_values"><a class="anchor" href="#_multiple_values"></a>7. Multiple Values</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Multi-valued options and positional parameters are annotated fields that can capture multiple values from the command line.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_repeated_options"><a class="anchor" href="#_repeated_options"></a>7.1. Repeated Options</h3>
|
|
<div class="paragraph">
|
|
<p>The simplest way to create a multi-valued option is to declare an annotated field whose type is an array, collection or a map.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-option</span><span class="delimiter">"</span></span>)
|
|
<span class="type">int</span><span class="type">[]</span> values;</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Users may specify the same option multiple times. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><command> -option 111 -option 222 -option 333</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Each value is appended to the array or collection.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_split_regex"><a class="anchor" href="#_split_regex"></a>7.2. Split Regex</h3>
|
|
<div class="paragraph">
|
|
<p>Options and parameters may also specify a <code>split</code> regular expression used to split each option parameter into smaller substrings.
|
|
Each of these substrings is converted to the type of the collection or array. See <a href="#_collections_and_maps">Collections and Maps</a>.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-option</span><span class="delimiter">"</span></span>, split = <span class="string"><span class="delimiter">"</span><span class="content">,</span><span class="delimiter">"</span></span>)
|
|
<span class="type">int</span><span class="type">[]</span> values;</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A single command line argument like the following will be split up and three <code>int</code> values are added to the array:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>-option 111,222,333</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_arity"><a class="anchor" href="#_arity"></a>7.3. Arity</h3>
|
|
<div class="paragraph">
|
|
<p>Sometimes you want to define an option that requires more than one option parameter <em>for each option occurrence</em> on the command line.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>arity</code> attribute lets you control exactly how many parameters to consume for each option occurrence.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>arity</code> attribute can specify an exact number of required parameters, or a <em>range</em> with a minimum and a maximum number of parameters.
|
|
The maximum can be an exact upper bound, or it can be <code>"*"</code> to denote <em>any number</em> of parameters. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">ArityDemo</span> {
|
|
<span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">"</span><span class="content">1..3</span><span class="delimiter">"</span></span>, descriptions = <span class="string"><span class="delimiter">"</span><span class="content">one to three Files</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">File</span><span class="type">[]</span> files;
|
|
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-f</span><span class="delimiter">"</span></span>, arity = <span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">exactly two floating point numbers</span><span class="delimiter">"</span></span>)
|
|
<span class="type">double</span><span class="type">[]</span> doubles;
|
|
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-s</span><span class="delimiter">"</span></span>, arity = <span class="string"><span class="delimiter">"</span><span class="content">1..*</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">at least one string</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">String</span><span class="type">[]</span> strings;
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A <code>MissingParameterException</code> is thrown when fewer than the miminum number of parameters is specified on the command line.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_default_arity"><a class="anchor" href="#_default_arity"></a>7.3.1. Default Arity</h4>
|
|
<div class="paragraph">
|
|
<p>If no <code>arity</code> is specified, the number of parameters depends on the field’s type.
|
|
The user manual has more details on <a href="http://picocli.info/#_default_arity">arity</a>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_help_options"><a class="anchor" href="#_help_options"></a>8. Help Options</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_mixin_standard_help_options"><a class="anchor" href="#_mixin_standard_help_options"></a>8.1. Mixin Standard Help Options</h3>
|
|
<div class="paragraph">
|
|
<p>When the <code>mixinStandardHelpOptions</code> command attribute is set to <code>true</code>, picocli adds a <a href="#_reuse">mixin</a> to the
|
|
command that adds <a href="#_custom_help_options"><code>usageHelp</code></a> and <a href="#_custom_help_options"><code>versionHelp</code></a> options to the command. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">"</span><span class="content">auto help demo - picocli 3.0</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">AutoHelpDemo</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
|
|
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">--option</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">Some option.</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">String</span> option;
|
|
|
|
<span class="annotation">@Override</span> <span class="directive">public</span> <span class="type">void</span> run() { ... }
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The usage help message for the above example looks like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: <main class> [-hV] [--option=<option>]
|
|
--option=<option> Some option.
|
|
-h, --help Show this help message and exit.
|
|
-V, --version Print version information and exit.</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_custom_help_options"><a class="anchor" href="#_custom_help_options"></a>8.2. Custom Help Options</h3>
|
|
<div class="paragraph">
|
|
<p>Applications can define custom help options by setting attribute <code>versionHelp = true</code>, <code>usageHelp = true</code> or <code>help = true</code>.
|
|
If one of the arguments specified on the command line is a "help" option, picocli will not throw a <code>MissingParameterException</code> when required options are missing.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">"</span><span class="content">-V</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--version</span><span class="delimiter">"</span></span>}, versionHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">"</span><span class="content">display version info</span><span class="delimiter">"</span></span>)
|
|
<span class="type">boolean</span> versionInfoRequested;
|
|
|
|
<span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">"</span><span class="content">?</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">-h</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--help</span><span class="delimiter">"</span></span>}, usageHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">"</span><span class="content">display this help message</span><span class="delimiter">"</span></span>)
|
|
<span class="type">boolean</span> usageHelpRequested;</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Use these attributes for options that request the usage help message or version information to be shown on the console.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>CommandLine</code> class offers two methods that allow external components to detect whether
|
|
usage help or version information was requested (without inspecting the annotated domain object):</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>CommandLine.isUsageHelpRequested()</code> returns <code>true</code> if the parser matched an option annotated with <code>usageHelp=true</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>CommandLine.isVersionHelpRequested()</code> returns <code>true</code> if the parser matched an option annotated with <code>versionHelp=true</code></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> App());
|
|
commandLine.parseArgs(args);
|
|
<span class="keyword">if</span> (commandLine.isUsageHelpRequested()) {
|
|
commandLine.usage(<span class="predefined-type">System</span>.out);
|
|
<span class="keyword">return</span>;
|
|
} <span class="keyword">else</span> <span class="keyword">if</span> (commandLine.isVersionHelpRequested()) {
|
|
commandLine.printVersionHelp(<span class="predefined-type">System</span>.out);
|
|
<span class="keyword">return</span>;
|
|
}
|
|
<span class="comment">// ... run App's business logic</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See also the chapter <a href="http://picocli.info/#_printing_help_automatically">Printing Help Automatically</a> of the user manual.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_version_help"><a class="anchor" href="#_version_help"></a>9. Version Help</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_static_version_information"><a class="anchor" href="#_static_version_information"></a>9.1. Static Version Information</h3>
|
|
<div class="paragraph">
|
|
<p>Applications can specify version information in the <code>version</code> attribute of the <code>@Command</code> annotation.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = <span class="string"><span class="delimiter">"</span><span class="content">1.0</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">VersionedCommand</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>CommandLine.printVersionHelp(PrintStream)</code> method extracts the version information from this
|
|
annotation and prints it to the specified <code>PrintStream</code>.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> VersionedCommand());
|
|
<span class="comment">//...</span>
|
|
commandLine.printVersionHelp(<span class="predefined-type">System</span>.out);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>version</code> may specify multiple Strings, and may contain <a href="#_usage_help_with_styles_and_colors">markup</a> to show ANSI styles and colors. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = {
|
|
<span class="string"><span class="delimiter">"</span><span class="content">@|yellow Versioned Command 1.0|@</span><span class="delimiter">"</span></span>,
|
|
<span class="string"><span class="delimiter">"</span><span class="content">@|blue Build 12345|@</span><span class="delimiter">"</span></span>,
|
|
<span class="string"><span class="delimiter">"</span><span class="content">@|red,bg(white) (c) 2017|@</span><span class="delimiter">"</span></span> })
|
|
<span class="type">class</span> <span class="class">VersionedCommand</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The markup will be rendered as ANSI escape codes on supported systems.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><span class="image"><img src="images/VersionInfoWithColors.png" alt="Screenshot of version information containing markup with Ansi styles and colors"></span></p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_dynamic_version_information"><a class="anchor" href="#_dynamic_version_information"></a>9.2. Dynamic Version Information</h3>
|
|
<div class="paragraph">
|
|
<p>The <code>@Command</code> annotation supports a <code>versionProvider</code> attribute.
|
|
Applications may specify a <code>IVersionProvider</code> implementation in this attribute, and picocli will instantiate this class
|
|
and invoke it to collect version information.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The GitHub project has an
|
|
<a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/VersionProviderDemo2.java">example</a>
|
|
implementation that gets the version from the manifest file and another
|
|
<a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/VersionProviderDemo1.java">example</a>
|
|
that gets version information from a build-generated version properties file.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_usage_help"><a class="anchor" href="#_usage_help"></a>10. Usage Help</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_example_usage_message"><a class="anchor" href="#_example_usage_message"></a>10.1. Example Usage Message</h3>
|
|
<div class="paragraph">
|
|
<p>Picocli makes it easy for your application to generate a usage help message like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: cat [-AbeEnstTuv] [--help] [--version] [FILE...]
|
|
Concatenate FILE(s), or standard input, to standard output.
|
|
FILE Files whose contents to display
|
|
-A, --show-all equivalent to -vET
|
|
-b, --number-nonblank number nonempty output lines, overrides -n
|
|
-e equivalent to -vET
|
|
-E, --show-ends display $ at end of each line
|
|
-n, --number number all output lines
|
|
-s, --squeeze-blank suppress repeated empty output lines
|
|
-t equivalent to -vT
|
|
-T, --show-tabs display TAB characters as ^I
|
|
-u (ignored)
|
|
-v, --show-nonprinting use ^ and M- notation, except for LDF and TAB
|
|
--help display this help and exit
|
|
--version output version information and exit
|
|
Copyright(c) 2019</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The usage help message is generated from annotation attributes, like below:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">cat</span><span class="delimiter">"</span></span>, footer = <span class="string"><span class="delimiter">"</span><span class="content">Copyright(c) 2019</span><span class="delimiter">"</span></span>,
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">Concatenate FILE(s), or standard input, to standard output.</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">Cat</span> {
|
|
|
|
<span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">"</span><span class="content">FILE</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">Files whose contents to display</span><span class="delimiter">"</span></span>)
|
|
<span class="predefined-type">List</span><<span class="predefined-type">File</span>> files;
|
|
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">--help</span><span class="delimiter">"</span></span>, usageHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">"</span><span class="content">display this help and exit</span><span class="delimiter">"</span></span>)
|
|
<span class="type">boolean</span> help;
|
|
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-t</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">equivalent to -vT</span><span class="delimiter">"</span></span>) <span class="type">boolean</span> t;
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-e</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">equivalent to -vET</span><span class="delimiter">"</span></span>) <span class="type">boolean</span> e;
|
|
<span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">"</span><span class="content">-A</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">--show-all</span><span class="delimiter">"</span></span>}, description = <span class="string"><span class="delimiter">"</span><span class="content">equivalent to -vET</span><span class="delimiter">"</span></span>) <span class="type">boolean</span> all;
|
|
|
|
<span class="comment">// ...</span>
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_usage_help_message_elements"><a class="anchor" href="#_usage_help_message_elements"></a>10.2. Usage Help Message Elements</h3>
|
|
<div class="paragraph">
|
|
<p>The various elements of the usage help message are easily customized with annotations.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_command_name"><a class="anchor" href="#_command_name"></a>10.2.1. Command Name</h4>
|
|
<div class="paragraph">
|
|
<p>In the above example, the program name is taken from the <code>name</code> attribute of the <code>Command</code> annotation:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">cat</span><span class="delimiter">"</span></span>)</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Without a <code>name</code> attribute, picocli will show a generic <code><main class></code> in the synopsis:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: <main class> [-AbeEnstTuv] [--help] [--version] [FILE...]</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_parameter_labels"><a class="anchor" href="#_parameter_labels"></a>10.2.2. Parameter Labels</h4>
|
|
<div class="paragraph">
|
|
<p>Non-boolean options require a value. The usage help should explain this, and picocli shows the option parameter
|
|
in the synopsis and in the option list. By default, the field name is shown in <code><</code> and <code>></code> fish brackets.
|
|
Use the <code>paramLabel</code> attribute to display a different name. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: <main class> [-f=FILE] [-n=<number>] NUM <host>
|
|
NUM number param
|
|
host the host
|
|
-f= FILE a file
|
|
-n= <number> number option</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Some annotated fields in the below example class have a <code>paramLabel</code> attribute and others don’t:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>()
|
|
<span class="type">class</span> <span class="class">ParamLabels</span> {
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-f</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">a file</span><span class="delimiter">"</span></span>, paramLabel = <span class="string"><span class="delimiter">"</span><span class="content">FILE</span><span class="delimiter">"</span></span>) <span class="predefined-type">File</span> f;
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-n</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">number option</span><span class="delimiter">"</span></span>) <span class="type">int</span> number;
|
|
<span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">number param</span><span class="delimiter">"</span></span>, paramLabel = <span class="string"><span class="delimiter">"</span><span class="content">NUM</span><span class="delimiter">"</span></span>) <span class="type">int</span> n;
|
|
<span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">the host</span><span class="delimiter">"</span></span>) <span class="predefined-type">InetAddress</span> host;
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_unsorted_option_list"><a class="anchor" href="#_unsorted_option_list"></a>10.2.3. Unsorted Option List</h4>
|
|
<div class="paragraph">
|
|
<p>By default the options list displays options in alphabetical order. Use the <code>sortOptions = false</code> attribute to display options in the order they are declared in your class.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(sortOptions = <span class="predefined-constant">false</span>)</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_abbreviated_synopsis"><a class="anchor" href="#_abbreviated_synopsis"></a>10.2.4. Abbreviated Synopsis</h4>
|
|
<div class="paragraph">
|
|
<p>If a command is very complex and has many options, it is sometimes desirable to suppress details from the synopsis with the <code>abbreviateSynopsis</code> attribute. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(abbreviateSynopsis = <span class="predefined-constant">true</span>)
|
|
<span class="type">class</span> <span class="class">App</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This shows the below synopsis.
|
|
Positional parameters are not abbreviated.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: <main class> [OPTIONS] [<files>...]</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_custom_synopsis"><a class="anchor" href="#_custom_synopsis"></a>10.2.5. Custom Synopsis</h4>
|
|
<div class="paragraph">
|
|
<p>For even more control of the synopsis, use the <code>customSynopsis</code> attribute to specify one ore more synopsis lines. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: ln [OPTION]... [-T] TARGET LINK_NAME (1st form)
|
|
or: ln [OPTION]... TARGET (2nd form)
|
|
or: ln [OPTION]... TARGET... DIRECTORY (3rd form)
|
|
or: ln [OPTION]... -t DIRECTORY TARGET... (4th form)</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To produce a synopsis like the above, specify the literal text in the <code>customSynopsis</code> attribute:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(synopsisHeading = <span class="string"><span class="delimiter">"</span><span class="delimiter">"</span></span>, customSynopsis = {
|
|
<span class="string"><span class="delimiter">"</span><span class="content">Usage: ln [OPTION]... [-T] TARGET LINK_NAME (1st form)</span><span class="delimiter">"</span></span>,
|
|
<span class="string"><span class="delimiter">"</span><span class="content"> or: ln [OPTION]... TARGET (2nd form)</span><span class="delimiter">"</span></span>,
|
|
<span class="string"><span class="delimiter">"</span><span class="content"> or: ln [OPTION]... TARGET... DIRECTORY (3rd form)</span><span class="delimiter">"</span></span>,
|
|
<span class="string"><span class="delimiter">"</span><span class="content"> or: ln [OPTION]... -t DIRECTORY TARGET... (4th form)</span><span class="delimiter">"</span></span>,
|
|
})
|
|
<span class="type">class</span> <span class="class">Ln</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_header_and_footer"><a class="anchor" href="#_header_and_footer"></a>10.2.6. Header and Footer</h4>
|
|
<div class="paragraph">
|
|
<p>The <code>header</code> will be shown at the top of the usage help message (before the synopsis). The first header line is also the line shown in the subcommand list if your command has subcommands (see <a href="#_usage_help_for_subcommands">Usage Help for Subcommands</a>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Use the <code>footer</code> attribute to specify one or more lines to show below the generated usage help message.
|
|
Each element of the attribute String array is displayed on a separate line.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>headerHeading</code> and <code>footerHeading</code> may contain format specifiers. See <a href="#_section_headings">Section Headings</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_section_headings"><a class="anchor" href="#_section_headings"></a>10.2.7. Section Headings</h4>
|
|
<div class="paragraph">
|
|
<p>Section headers can be used to make usage message layout appear more spacious. Section headings may contain embedded line separator (<code>%n</code>) format specifiers:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">commit</span><span class="delimiter">"</span></span>,
|
|
sortOptions = <span class="predefined-constant">false</span>,
|
|
headerHeading = <span class="string"><span class="delimiter">"</span><span class="content">Usage:%n%n</span><span class="delimiter">"</span></span>,
|
|
synopsisHeading = <span class="string"><span class="delimiter">"</span><span class="content">%n</span><span class="delimiter">"</span></span>,
|
|
descriptionHeading = <span class="string"><span class="delimiter">"</span><span class="content">%nDescription:%n%n</span><span class="delimiter">"</span></span>,
|
|
parameterListHeading = <span class="string"><span class="delimiter">"</span><span class="content">%nParameters:%n</span><span class="delimiter">"</span></span>,
|
|
optionListHeading = <span class="string"><span class="delimiter">"</span><span class="content">%nOptions:%n</span><span class="delimiter">"</span></span>,
|
|
header = <span class="string"><span class="delimiter">"</span><span class="content">Record changes to the repository.</span><span class="delimiter">"</span></span>,
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">Stores the current contents of the index in a new commit </span><span class="delimiter">"</span></span> +
|
|
<span class="string"><span class="delimiter">"</span><span class="content">along with a log message from the user describing the changes.</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">GitCommit</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The usage help message generated from this class is shown below in <a href="https://picocli.info/#_expanded_example">Expanded Example</a> in the user manual.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_option_parameter_separators"><a class="anchor" href="#_option_parameter_separators"></a>10.2.8. Option-Parameter Separators</h4>
|
|
<div class="paragraph">
|
|
<p>The separator displayed between options and option parameters (<code>=</code> by default)
|
|
in the synopsis and the option list can be configured with the <code>separator</code> attribute.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(separator = <span class="string"><span class="delimiter">"</span><span class="content">:</span><span class="delimiter">"</span></span>)</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_hidden_options_and_parameters"><a class="anchor" href="#_hidden_options_and_parameters"></a>10.2.9. Hidden Options and Parameters</h4>
|
|
<div class="paragraph">
|
|
<p>Options and Parameters with the <code>hidden</code> attribute set to <code>true</code> will not be shown in the usage help message.
|
|
See the <a href="https://picocli.info/#_hidden_options_and_parameters">user manual</a> for details.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_show_default_values"><a class="anchor" href="#_show_default_values"></a>10.2.10. Show Default Values</h4>
|
|
<div class="paragraph">
|
|
<p>The <a href="http://picocli.info/#_default_values">default value</a> for an option or positional parameter
|
|
can be embedded in the description by specifying the variable <code>${DEFAULT-VALUE}</code> in the description text.
|
|
See the <a href="https://picocli.info/#_show_default_values">user manual</a> for details.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Similarly, it is possible to embed the completion candidates in the description for an option or positional parameter by
|
|
specifying the variable <code>${COMPLETION-CANDIDATES}</code> in the description text.
|
|
See the <a href="https://picocli.info/#_show_default_values">user manual</a> for details.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_required_option_marker"><a class="anchor" href="#_required_option_marker"></a>10.2.11. Required-Option Marker</h4>
|
|
<div class="paragraph">
|
|
<p>Required options can be marked in the option list by the character specified with the <code>requiredOptionMarker</code> attribute.
|
|
See the <a href="https://picocli.info/#_required_option_marker">user manual</a> for details.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_usage_width"><a class="anchor" href="#_usage_width"></a>10.2.12. Usage Width</h4>
|
|
<div class="paragraph">
|
|
<p>The default width of the usage help message is 80 characters.
|
|
System property <code>picocli.usage.width</code> can be used to specify a custom width.
|
|
The minimum width that can be configured is 55 characters.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The width can also be set programmatically via the <code>CommandLine::setUsageHelpWidth</code> and <code>UsageMessageSpec::width</code> methods.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_ansi_colors_and_styles"><a class="anchor" href="#_ansi_colors_and_styles"></a>11. ANSI Colors and Styles</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_colorized_example"><a class="anchor" href="#_colorized_example"></a>11.1. Colorized Example</h3>
|
|
<div class="paragraph">
|
|
<p>Below shows the same usage help message as shown in the <a href="https://picocli.info/#_expanded_example">Expanded Example</a> in the user manual, with ANSI escape codes enabled.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><span class="image"><img src="images/UsageHelpWithStyle.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_usage_help_with_styles_and_colors"><a class="anchor" href="#_usage_help_with_styles_and_colors"></a>11.2. Usage Help with Styles and Colors</h3>
|
|
<div class="paragraph">
|
|
<p>You can use colors and styles in the descriptions, header and footer
|
|
of the usage help message.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Picocli supports a custom markup notation for mixing colors and styles in text,
|
|
following a convention introduced by <a href="https://github.com/fusesource/jansi">Jansi</a>, where
|
|
<code>@|</code> starts a styled section, and <code>|@</code> ends it.
|
|
Immediately following the <code>@|</code> is a comma-separated list of colors and styles, so <code>@|STYLE1[,STYLE2]…​ text|@</code>.
|
|
For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(description = <span class="string"><span class="delimiter">"</span><span class="content">Custom @|bold,underline styles|@ and @|fg(red) colors|@.</span><span class="delimiter">"</span></span>)</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><span class="image"><img src="images/DescriptionWithColors.png" alt="Description with Ansi styles and colors"></span></p>
|
|
</div>
|
|
<table class="tableblock frame-all grid-cols stretch">
|
|
<caption class="title">Table 1. Pre-defined styles and colors that can be used in descriptions and headers using the <code>@|STYLE1[,STYLE2]…​ text|@</code> notation</caption>
|
|
<colgroup>
|
|
<col style="width: 50%;">
|
|
<col style="width: 50%;">
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th class="tableblock halign-left valign-top">Pre-defined Styles</th>
|
|
<th class="tableblock halign-left valign-top">Pre-defined Colors</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">bold</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">black</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">faint</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">red</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">underline</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">green</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">italic</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">yellow</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">blink</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">blue</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">reverse</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">magenta</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">reset</p></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">cyan</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="tableblock halign-left valign-top"></td>
|
|
<td class="tableblock halign-left valign-top"><p class="tableblock">white</p></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="paragraph">
|
|
<p>Colors are applied as <em>foreground</em> colors by default.
|
|
You can set <em>background</em> colors by specifying <code>bg(<color>)</code>.
|
|
For example, <code>@|bg(red) text with red background|@</code>.
|
|
Similarly, <code>fg(<color>)</code> explicitly sets the foreground color.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The example below shows how this markup can be used to add colors and styles to the headings and descriptions of a usage help message:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">commit</span><span class="delimiter">"</span></span>,
|
|
sortOptions = <span class="predefined-constant">false</span>,
|
|
headerHeading = <span class="string"><span class="delimiter">"</span><span class="content">@|bold,underline Usage|@:%n%n</span><span class="delimiter">"</span></span>,
|
|
synopsisHeading = <span class="string"><span class="delimiter">"</span><span class="content">%n</span><span class="delimiter">"</span></span>,
|
|
descriptionHeading = <span class="string"><span class="delimiter">"</span><span class="content">%n@|bold,underline Description|@:%n%n</span><span class="delimiter">"</span></span>,
|
|
parameterListHeading = <span class="string"><span class="delimiter">"</span><span class="content">%n@|bold,underline Parameters|@:%n</span><span class="delimiter">"</span></span>,
|
|
optionListHeading = <span class="string"><span class="delimiter">"</span><span class="content">%n@|bold,underline Options|@:%n</span><span class="delimiter">"</span></span>,
|
|
header = <span class="string"><span class="delimiter">"</span><span class="content">Record changes to the repository.</span><span class="delimiter">"</span></span>,
|
|
description = <span class="string"><span class="delimiter">"</span><span class="content">Stores the current contents of the index in a new commit </span><span class="delimiter">"</span></span> +
|
|
<span class="string"><span class="delimiter">"</span><span class="content">along with a log message from the user describing the changes.</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">GitCommit</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock caution">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-caution" title="Caution"></i>
|
|
</td>
|
|
<td class="content">
|
|
Markup styles cannot be nested, for example: <code>@|bold this @|underline that|@|@</code> will not work. You can achieve the same by combining styles, for example: <code>@|bold this|@ @|bold,underline that|@</code> will work fine.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_more_colors"><a class="anchor" href="#_more_colors"></a>11.2.1. More Colors</h4>
|
|
<div class="paragraph">
|
|
<p>There are only eight pre-defined named colors, but most terminals support a 256 color indexed palette.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See the <a href="https://picocli.info/#_more_colors">More Colors</a> section of the user manual for using these colors as foreground or background colors.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><span class="image"><img src="images/256colors.png" alt="256 color indexed palette"></span></p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_color_scheme_for_fixed_elements"><a class="anchor" href="#_color_scheme_for_fixed_elements"></a>11.2.2. Color Scheme for Fixed Elements</h4>
|
|
<div class="paragraph">
|
|
<p>Picocli uses a default color scheme for options, parameters and commands.
|
|
There are no annotations to modify this color scheme, but it can be changed programmatically and with system properties.
|
|
For details, see the <a href="https://picocli.info/#_configuring_fixed_elements">Color Scheme</a> section of the user manual.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_supported_platforms"><a class="anchor" href="#_supported_platforms"></a>11.3. Supported Platforms</h3>
|
|
<div class="paragraph">
|
|
<p>Picocli will only emit ANSI escape codes on supported platforms.
|
|
This includes most Unix and Linux platforms.
|
|
See the <a href="https://picocli.info/#_supported_platforms">Windows</a> section of the user manual for the various options available to add coloring support to the Windows command console.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_forcing_ansi_onoff"><a class="anchor" href="#_forcing_ansi_onoff"></a>11.4. Forcing ANSI On/Off</h3>
|
|
<div class="paragraph">
|
|
<p>You can force picocli to either always use ANSI codes or never use ANSI codes regardless of the platform:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Setting system property <code>picocli.ansi</code> to <code>true</code> forces picocli to use ANSI codes; setting <code>picocli.ansi</code> to <code>false</code> forces picocli to <strong>not</strong> use ANSI codes. This may be a useful facility for users of your command line application.</p>
|
|
</li>
|
|
<li>
|
|
<p>You can decide to force disable or force enable ANSI escape codes programmatically by specifying <code>Ansi.ON</code> or <code>Ansi.OFF</code> when invoking <code>CommandLine.usage</code>.
|
|
This overrides the value of system property <code>picocli.ansi</code>. For example:</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine.Help.Ansi</span>;
|
|
|
|
App app = CommandLine.usage(<span class="keyword">new</span> App(), <span class="predefined-type">System</span>.out, Ansi.OFF, args);</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_subcommands"><a class="anchor" href="#_subcommands"></a>12. Subcommands</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_registering_subcommands"><a class="anchor" href="#_registering_subcommands"></a>12.1. Registering Subcommands</h3>
|
|
<div class="paragraph">
|
|
<p>Subcommands can be registered programmatically or declaratively</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_programmatically"><a class="anchor" href="#_programmatically"></a>12.1.1. Programmatically</h4>
|
|
<div class="paragraph">
|
|
<p>Subcommands can be registered with the <code>CommandLine.addSubcommand</code> method.
|
|
You pass in the name of the command and the annotated object to populate with the subcommand options.
|
|
The specified name is used by the parser to recognize subcommands in the command line arguments.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">status</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitStatus())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">commit</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitCommit())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">add</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitAdd())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">branch</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitBranch())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">checkout</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitCheckout())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">clone</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitClone())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">diff</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitDiff())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">merge</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitMerge())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">push</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitPush())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">rebase</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitRebase())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">tag</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitTag());</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock caution">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-caution" title="Caution"></i>
|
|
</td>
|
|
<td class="content">
|
|
<em>Note on custom type converters:</em> custom type converters are registered only with the subcommands and nested
|
|
sub-subcommands that were added <em>before</em> the custom type was registered.
|
|
To ensure a custom type converter is available to all subcommands, register the type converter last, after
|
|
adding subcommands.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_declaratively"><a class="anchor" href="#_declaratively"></a>12.1.2. Declaratively</h4>
|
|
<div class="paragraph">
|
|
<p>Subcommands can be registered declaratively with the <code>@Command</code> annotation’s <code>subcommands</code> attribute.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">git</span><span class="delimiter">"</span></span>, subcommands = {
|
|
GitStatus.class,
|
|
GitCommit.class,
|
|
GitAdd.class,
|
|
GitBranch.class,
|
|
GitCheckout.class,
|
|
GitClone.class,
|
|
GitDiff.class,
|
|
GitMerge.class,
|
|
GitPush.class,
|
|
GitRebase.class,
|
|
GitTag.class
|
|
})
|
|
<span class="directive">public</span> <span class="type">class</span> <span class="class">Git</span> { ... }</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The declared subcommands are automatically instantiated and added when the <code>new CommandLine(new Git())</code> instance is constructed.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Subcommands referenced in a <code>subcommands</code> attribute <em>must</em> have a <code>@Command</code> annotation with a <code>name</code> attribute, or an exception is thrown from the <code>CommandLine</code> constructor.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_nesting_subcommands"><a class="anchor" href="#_nesting_subcommands"></a>12.1.3. Nesting Subcommands</h4>
|
|
<div class="paragraph">
|
|
<p>Subcommands can be nested to any arbitrary level of depth. See the <a href="https://picocli.info/#_nested_sub_subcommands">Nested sub-Subcommands</a> section of the user manual for details.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_parsing_subcommands"><a class="anchor" href="#_parsing_subcommands"></a>12.2. Parsing Subcommands</h3>
|
|
<div class="paragraph">
|
|
<p>For this example, we assume we created an alias <code>git</code> that invokes our Java application. This could also be a script or a function that calls our Java program:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="bash">alias git='java picocli.Demo$Git'</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Next, we call our command with some arguments like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="bash">git --git-dir=/home/rpopma/picocli status -sb -uno</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Where <code>git</code> (actually <code>java picocli.Demo$Git</code>) is the top-level command, followed by a global option and a subcommand <code>status</code> with its own options.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Setting up the parser and parsing the command line could look like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
|
|
<span class="comment">// Set up the parser</span>
|
|
CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git());
|
|
|
|
<span class="comment">// add subcommands programmatically (not necessary if the parent command</span>
|
|
<span class="comment">// declaratively registers the subcommands via annotation)</span>
|
|
commandLine.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">status</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitStatus())
|
|
.addSubcommand(<span class="string"><span class="delimiter">"</span><span class="content">commit</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> GitCommit())
|
|
...
|
|
|
|
<span class="comment">// Invoke the parse method to parse the arguments</span>
|
|
List<CommandLine> parsed = commandLine.parse(args);
|
|
handleParseResult(parsed);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>CommandLine.parse</code> method returns a List with the recognized commands. The top-level command (the Java class invoked by <code>git</code> in this example) is always the first element in the returned list.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The returned List also contains all matched subcommands. Your application needs to inspect this list to see what subcommand was invoked and take appropriate action. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">private</span> <span class="type">void</span> handleParseResult(<span class="predefined-type">List</span><CommandLine> parsed) {
|
|
<span class="keyword">assert</span> parsed.size() == <span class="integer">2</span> : <span class="string"><span class="delimiter">"</span><span class="content">1 command and 1 subcommand found</span><span class="delimiter">"</span></span>
|
|
|
|
<span class="keyword">assert</span> parsed.get(<span class="integer">0</span>).getCommand().getClass() == Git.class : <span class="string"><span class="delimiter">"</span><span class="content">main command</span><span class="delimiter">"</span></span>
|
|
<span class="keyword">assert</span> parsed.get(<span class="integer">1</span>).getCommand().getClass() == GitStatus.class : <span class="string"><span class="delimiter">"</span><span class="content">subcommand</span><span class="delimiter">"</span></span>
|
|
|
|
Git git = (Git) parsed.get(<span class="integer">0</span>).getCommand();
|
|
<span class="keyword">assert</span> git.gitDir.equals(<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">/home/rpopma/picocli</span><span class="delimiter">"</span></span>));
|
|
|
|
GitStatus gitstatus = (GitStatus) parsed.get(<span class="integer">1</span>).getCommand();
|
|
<span class="keyword">assert</span> gitstatus.shortFormat : <span class="string"><span class="delimiter">"</span><span class="content">git status -s</span><span class="delimiter">"</span></span>
|
|
<span class="keyword">assert</span> gitstatus.branchInfo : <span class="string"><span class="delimiter">"</span><span class="content">git status -b</span><span class="delimiter">"</span></span>
|
|
<span class="keyword">assert</span> !gitstatus.showIgnored : <span class="string"><span class="delimiter">"</span><span class="content">git status --showIgnored not specified</span><span class="delimiter">"</span></span>
|
|
<span class="keyword">assert</span> gitstatus.mode == GitStatusMode.no : <span class="string"><span class="delimiter">"</span><span class="content">git status -u=no</span><span class="delimiter">"</span></span>
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>As of Picocli 4.0, you may use the <a href="#_executing_commands"><code>execute</code> method</a> to reduce error handling and other boilerplate code in your application.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_parentcommand_annotation"><a class="anchor" href="#_parentcommand_annotation"></a>12.3. <code>@ParentCommand</code> Annotation</h3>
|
|
<div class="paragraph">
|
|
<p>In command line applications with subcommands, options of the top level command are often intended as "global" options that apply to all the subcommands.
|
|
The <code>@ParentCommand</code> annotation makes it easy for subcommands to access their parent command options: subcommand fields annotated with <code>@ParentCommand</code> are initialized with a reference to the parent command.
|
|
The user manual has an example showing <a href="https://picocli.info/#parentcommand-annotation">how to use the <code>@ParentCommand</code> annotation</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_usage_help_for_subcommands"><a class="anchor" href="#_usage_help_for_subcommands"></a>12.4. Usage Help for Subcommands</h3>
|
|
<div class="paragraph">
|
|
<p>After registering subcommands, calling the <code>commandLine.usage</code> method will show a usage help message that includes all subcommands in the order they were registered. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>Usage: git [-hV] [--git-dir=<gitDir>]
|
|
Git is a fast, scalable, distributed revision control system with an unusually
|
|
rich command set that provides both high-level operations and full access to
|
|
internals.
|
|
--git-dir=<gitDir> Set the path to the repository.
|
|
-h, --help Show this help message and exit.
|
|
-V, --version Print version information and exit.
|
|
|
|
Commands:
|
|
|
|
The most commonly used git commands are:
|
|
help Displays help information about the specified command
|
|
status Show the working tree status.
|
|
commit Record changes to the repository.
|
|
add Add file contents to the index.
|
|
branch List, create, or delete branches.
|
|
checkout Checkout a branch or paths to the working tree.
|
|
clone Clone a repository into a new directory.
|
|
diff Show changes between commits, commit and working tree, etc.
|
|
merge Join two or more development histories together.
|
|
push Update remote refs along with associated objects.
|
|
rebase Forward-port local commits to the updated upstream head.
|
|
tag Create, list, delete or verify a tag object signed with GPG.</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The description for the subcommand in the list is taken from the subcommand’s first <a href="#_header_and_footer">header line</a>, or, if the subcommand does not have a <code>header</code> annotation, from the <code>description</code>.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_hidden_subcommands"><a class="anchor" href="#_hidden_subcommands"></a>12.4.1. Hidden Subcommands</h4>
|
|
<div class="paragraph">
|
|
<p>Commands with the <code>hidden</code> attribute set to <code>true</code> will not be shown in the usage help message of their parent command.
|
|
See the <a href="https://picocli.info/#_hidden_subcommands">Hidden Subcommands</a> section of the user manual for details.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_help_subcommands"><a class="anchor" href="#_help_subcommands"></a>12.4.2. Help Subcommands</h4>
|
|
<div class="paragraph">
|
|
<p>Picocli has a <a href="https://picocli.info/#_built_in_help_subcommand">built-in Help subcommand</a>,
|
|
but see the <a href="https://picocli.info/#_help_subcommands">Help Subcommands</a> section of the user manual if you’re interested in creating a custom <code>help</code> command.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_reuse"><a class="anchor" href="#_reuse"></a>13. Reuse</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>You may find yourself defining the same options, parameters or command attributes in many command line applications.
|
|
To reduce duplication, picocli supports both subclassing and mixins as ways to reuse such options and attributes.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>One way to reuse the above option and attributes is to extend the class. Picocli will walk the class hierarchy to check for annotations, so <code>@Options</code>, <code>@Parameters</code> and <code>@Command</code> attributes declared on a superclass are available in all subclasses.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A command can also include a mixin by annotating a field with <code>@Mixin</code>. All picocli annotations found in the mixin class
|
|
are added to the command that has a field annotated with <code>@Mixin</code>. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">zip</span><span class="delimiter">"</span></span>, description = <span class="string"><span class="delimiter">"</span><span class="content">Example reuse with @Mixin annotation.</span><span class="delimiter">"</span></span>)
|
|
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyCommand</span> {
|
|
|
|
<span class="comment">// adds the options defined in ReusableOptions to this command</span>
|
|
<span class="annotation">@Mixin</span>
|
|
<span class="directive">private</span> ReusableOptions myMixin;
|
|
...
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <a href="https://picocli.info/#_reuse">Reuse</a> section of the user manual has more extensive examples.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_executing_commands"><a class="anchor" href="#_executing_commands"></a>14. Executing Commands</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>When executing a command, parsing the command line is the first step. A robust real-world application needs to handle a number of scenarios:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>User input was invalid: show an error describing the problem and show the usage help</p>
|
|
</li>
|
|
<li>
|
|
<p>User requested usage help: show help message and exit</p>
|
|
</li>
|
|
<li>
|
|
<p>User requested version help: show version information and exit</p>
|
|
</li>
|
|
<li>
|
|
<p>None of the above: run the business logic (potentially for a subcommand)</p>
|
|
</li>
|
|
<li>
|
|
<p>Business logic may throw an exception: handle or rethrow exception</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>As of Picocli 4.0, you may make use of the <code>Commandline.execute</code> method which handles all of the above scenarios in a single line of code:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>With the <code>execute</code> method, application code can be <strong>extremely compact</strong>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><table class="CodeRay"><tr>
|
|
<td class="line-numbers"><pre>1
|
|
2
|
|
3
|
|
4
|
|
5
|
|
6
|
|
7
|
|
8
|
|
9
|
|
10
|
|
11
|
|
12
|
|
13
|
|
14
|
|
15
|
|
</pre></td>
|
|
<td class="code"><pre><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">myapp</span><span class="delimiter">"</span></span>, mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">"</span><span class="content">1.0</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">MyApp</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span><<span class="predefined-type">Integer</span>> {
|
|
|
|
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">"</span><span class="content">-x</span><span class="delimiter">"</span></span>) <span class="type">int</span> x;
|
|
|
|
<span class="annotation">@Override</span>
|
|
<span class="directive">public</span> <span class="predefined-type">Integer</span> call() { <span class="comment">// business logic</span>
|
|
<span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">"</span><span class="content">x=%s%n</span><span class="delimiter">"</span></span>, x);
|
|
<span class="keyword">return</span> <span class="integer">123</span>; <span class="comment">// exit code</span>
|
|
}
|
|
|
|
<span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) { <span class="comment">// bootstrap the application</span>
|
|
<span class="predefined-type">System</span>.exit(<span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args));
|
|
}
|
|
}</pre></td>
|
|
</tr></table></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Despite being only 15 lines long, this is a full-fledged application, with <a href="#_mixin_standard_help_options"><code>--help</code> and <code>--version</code></a> options in addition to the <code>-x</code> option.
|
|
The <code>execute</code> method will show the usage help or version information if requested by the user, and invalid user input will result
|
|
in a helpful <a href="#_handling_errors">error message</a>. If the user input was valid, the business logic is invoked.
|
|
Finally, the <code>execute</code> method returns an <a href="#_exit_code">exit status code</a> that can be used to call <code>System.exit</code> if desired.</p>
|
|
</div>
|
|
<div class="admonitionblock important">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-important" title="Important"></i>
|
|
</td>
|
|
<td class="content">
|
|
A command is executable if its user object implements <code>Runnable</code> or <code>Callable</code>, or is a <code>@Command</code>-annotated <code>Method</code>. Examples follow below.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-note" title="Note"></i>
|
|
</td>
|
|
<td class="content">
|
|
The <code>execute</code> method replaces the older <code>run</code>, <code>call</code>, <code>invoke</code> and <code>parseWithHandlers</code> methods.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <a href="https://picocli.info/#_diy_command_execution">DIY Command Execution</a> section of the user manual shows an example of the boilerplate code that can be omitted with the <code>execute</code> method.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_exit_code"><a class="anchor" href="#_exit_code"></a>14.1. Exit Code</h3>
|
|
<div class="paragraph">
|
|
<p>Many command line applications return an <a href="https://en.wikipedia.org/wiki/Exit_status">exit code</a> to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>CommandLine.execute</code> method introduced in picocli 4.0 returns an <code>int</code>, and applications can use this return value to call <code>System.exit</code> if desired. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
|
|
<span class="type">int</span> exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);
|
|
<span class="predefined-type">System</span>.exit(exitCode);
|
|
}</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock caution">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-caution" title="Caution"></i>
|
|
</td>
|
|
<td class="content">
|
|
Older versions of picocli had some limited exit code support where picocli would call <code>System.exit</code>, but this is now deprecated.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_generating_an_exit_code"><a class="anchor" href="#_generating_an_exit_code"></a>14.2. Generating an Exit Code</h3>
|
|
<div class="paragraph">
|
|
<p><code>@Command</code>-annotated classes that implement <code>Callable</code> and <code>@Command</code>-<a href="https://picocli.info/#command-methods">annotated methods</a> can simply return an <code>int</code> or <code>Integer</code>, and this value will be returned from <code>CommandLine.execute</code>. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">greet</span><span class="delimiter">"</span></span>)
|
|
<span class="type">class</span> <span class="class">Greet</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span><<span class="predefined-type">Integer</span>> {
|
|
<span class="directive">public</span> <span class="predefined-type">Integer</span> call() {
|
|
<span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">"</span><span class="content">hi</span><span class="delimiter">"</span></span>);
|
|
<span class="keyword">return</span> <span class="integer">1</span>;
|
|
}
|
|
|
|
<span class="comment">// define a "shout" subcommand with a @Command-annotated method</span>
|
|
<span class="annotation">@Command</span>
|
|
<span class="type">int</span> shout() {
|
|
<span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">"</span><span class="content">HI!</span><span class="delimiter">"</span></span>);
|
|
<span class="keyword">return</span> <span class="integer">2</span>;
|
|
}
|
|
}
|
|
|
|
<span class="keyword">assert</span> <span class="integer">1</span> == <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Greet()).execute();
|
|
<span class="keyword">assert</span> <span class="integer">2</span> == <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Greet()).execute(<span class="string"><span class="delimiter">"</span><span class="content">shout</span><span class="delimiter">"</span></span>);</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Commands with a user object that implements <code>Runnable</code> can implement the <code>IExitCodeGenerator</code> interface to generate an exit code.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_exception_exit_codes"><a class="anchor" href="#_exception_exit_codes"></a>14.3. Exception Exit Codes</h3>
|
|
<div class="paragraph">
|
|
<p>By default, the <code>execute</code> method returns <code>CommandLine.ExitCode.OK</code> (<code>0</code>) on success, <code>CommandLine.ExitCode.SOFTWARE</code> (<code>1</code>) when an exception occurred in the Runnable, Callable or command method, and <code>CommandLine.ExitCode.USAGE</code> (<code>2</code>) for invalid input. (These are common values according to <a href="https://stackoverflow.com/questions/1101957/are-there-any-standard-exit-status-codes-in-linux/40484670#40484670">this StackOverflow answer</a>). This can be customized with the <code>@Command</code> annotation. For example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(exitCodeOnInvalidInput = <span class="integer">123</span>,
|
|
exitCodeOnExecutionException = <span class="integer">456</span>)</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Additionally, applications can configure a <code>IExitCodeExceptionMapper</code> to map a specific exception to an exit code.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_execution_configuration"><a class="anchor" href="#_execution_configuration"></a>14.4. Execution Configuration</h3>
|
|
<div class="paragraph">
|
|
<p>While the <code>execute</code> method allows to run the CLI app in one single line of code, the various steps of the command execution are highly configurable.
|
|
The following methods can be used to configure the behaviour of the <code>execute</code> method, you may make use of them to adapt the command execution to your needs:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>get/setOut</p>
|
|
</li>
|
|
<li>
|
|
<p>get/setErr</p>
|
|
</li>
|
|
<li>
|
|
<p>get/setColorScheme</p>
|
|
</li>
|
|
<li>
|
|
<p>get/setExecutionStrategy</p>
|
|
</li>
|
|
<li>
|
|
<p>get/setParameterExceptionHandler</p>
|
|
</li>
|
|
<li>
|
|
<p>get/setExecutionExceptionHandler</p>
|
|
</li>
|
|
<li>
|
|
<p>get/setExitCodeExceptionMapper</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="admonitionblock caution">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-caution" title="Caution"></i>
|
|
</td>
|
|
<td class="content">
|
|
The above methods are not applicable with (and ignored by) other entry points like <code>parse</code>, <code>parseArgs</code>, <code>populateCommand</code>, <code>run</code>, <code>call</code>, <code>invoke</code>, <code>parseWithHandler</code> and <code>parseWithHandlers</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_handling_errors"><a class="anchor" href="#_handling_errors"></a>14.5. Handling Errors</h3>
|
|
<div class="paragraph">
|
|
<p>Internally, the <code>execute</code> method parses the specified user input and populates the options and positional parameters defined by the annotations.
|
|
When the user specified invalid input, this is handled by the <code>IParameterExceptionHandler</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>After parsing the user input, the business logic of the command is invoked: the <code>run</code>, <code>call</code> or <code>@Command</code>-annotated method.
|
|
When an exception is thrown by the business logic, this is handled by the <code>IExecutionExceptionHandler</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In most cases, the default handlers are sufficient. Customization of the default handlers in explained in depth in the <a href="https://picocli.info/#_handling_errors">handling errors</a> section of the user manual.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_migration"><a class="anchor" href="#_migration"></a>14.6. Migration</h3>
|
|
<div class="paragraph">
|
|
<p>Older versions of picocli supported <code>run</code>, <code>call</code>, <code>invoke</code> and <code>parseWithHandlers</code> convenience methods that were similar to <code>execute</code> but had limited support for parser configuration and and limited support for exit codes.
|
|
These methods are deprecated as of picocli 4.0.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <a href="https://picocli.info/#_migration">migration</a> section of the user manual assists you in migrating existing code to the newly introduced <code>execute</code> API.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_tracing"><a class="anchor" href="#_tracing"></a>15. Tracing</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Picocli supports parser tracing to facilitate troubleshooting.
|
|
System property <code>picocli.trace</code> controls the trace level. Supported levels are <code>OFF</code>, <code>WARN</code>, <code>INFO</code>, and <code>DEBUG</code>. The default trace level is <code>WARN</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Specifying system property <code>-Dpicocli.trace</code> without a value will set the trace level to <code>INFO</code>.</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>DEBUG: Shows details of the decisions made by the parser during command line parsing.</p>
|
|
</li>
|
|
<li>
|
|
<p>INFO: Shows a high-level overview of what happens during command line parsing.</p>
|
|
</li>
|
|
<li>
|
|
<p>WARN: The default. Shows warnings instead of errors when lenient parsing is enabled:
|
|
when single-value options were specified multiple times (and <code>CommandLine.overwrittenOptionsAllowed</code> is <code>true</code>),
|
|
or when command line arguments could not be matched as an option or positional parameter
|
|
(and <code>CommandLine.unmatchedArgumentsAllowed</code> is <code>true</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p>OFF: Suppresses all tracing including warnings.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="CodeRay highlight"><code data-lang="bash"># create a custom 'mygit' command that invokes picocli.Demo$Git with tracing switched on
|
|
alias mygit='java -Dpicocli.trace -cp picocli-all.jar picocli.Demo$Git'
|
|
|
|
# invoke our command with some parameters
|
|
mygit --git-dir=/home/rpopma/picocli commit -m "Fixed typos" -- src1.java src2.java src3.java</code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Output:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre>[picocli INFO] Parsing 8 command line args [--git-dir=/home/rpopma/picocli, commit, -m, "Fixed typos", --, src1.java, src2.java, src3.java]
|
|
[picocli INFO] Setting File field 'Git.gitDir' to '\home\rpopma\picocli' for option --git-dir
|
|
[picocli INFO] Adding [Fixed typos] to List<String> field 'GitCommit.message' for option -m
|
|
[picocli INFO] Found end-of-options delimiter '--'. Treating remainder as positional parameters.
|
|
[picocli INFO] Adding [src1.java] to List<String> field 'GitCommit.files' for args[0..*]
|
|
[picocli INFO] Adding [src2.java] to List<String> field 'GitCommit.files' for args[0..*]
|
|
[picocli INFO] Adding [src3.java] to List<String> field 'GitCommit.files' for args[0..*]</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_tab_autocomplete"><a class="anchor" href="#_tab_autocomplete"></a>16. TAB Autocomplete</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Picocli-based applications can now have command line completion in Bash or Zsh Unix shells.
|
|
See the <a href="autocomplete.html">Autocomplete for Java Command Line Applications</a> manual for how to generate an autocompletion script tailored to your application.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_more"><a class="anchor" href="#_more"></a>17. More</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>To keep this Quick Guide short (or at least, short-ish) some things had to be left out. Here are some quick links in case you are interested:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="https://picocli.info/#_picocli_in_other_languages">Picocli in Other Languages</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="https://picocli.info/#_usage_help_api">Usage Help API</a> for customizing the usage help message layout</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="https://picocli.info/#_tips_tricks">Tips & Tricks</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="https://remkop.github.io/picocli/apidocs">API Javadoc</a></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Don’t forget to star <span class="icon"><i class="fa fa-star-o"></i></span> the <a href="https://github.com/remkop/picocli">project on GitHub</a> if you like it!
|
|
Your stars keep me going! :-)</p>
|
|
</div>
|
|
<script src="https://www.jdoodle.com/assets/jdoodle-pym.min.js" type="text/javascript"></script>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footer">
|
|
<div id="footer-text">
|
|
Version 4.5.2<br>
|
|
Last updated 2020-11-01 20:55:20 +0900
|
|
</div>
|
|
</div>
|
|
<style>
|
|
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
|
|
pre.CodeRay{background:#f7f7f8}
|
|
.CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0}
|
|
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
|
|
.CodeRay .line-numbers strong{color:#000}
|
|
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
|
|
table.CodeRay td{vertical-align:top;line-height:inherit}
|
|
table.CodeRay td.line-numbers{text-align:right}
|
|
table.CodeRay td.code{padding:0 0 0 .75em}
|
|
.CodeRay .debug{color:#fff !important;background:#000080 !important}
|
|
.CodeRay .annotation{color:#007}
|
|
.CodeRay .attribute-name{color:#000080}
|
|
.CodeRay .attribute-value{color:#700}
|
|
.CodeRay .binary{color:#509}
|
|
.CodeRay .comment{color:#998;font-style:italic}
|
|
.CodeRay .char{color:#04d}
|
|
.CodeRay .char .content{color:#04d}
|
|
.CodeRay .char .delimiter{color:#039}
|
|
.CodeRay .class{color:#458;font-weight:bold}
|
|
.CodeRay .complex{color:#a08}
|
|
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
|
|
.CodeRay .color{color:#099}
|
|
.CodeRay .class-variable{color:#369}
|
|
.CodeRay .decorator{color:#b0b}
|
|
.CodeRay .definition{color:#099}
|
|
.CodeRay .delimiter{color:#000}
|
|
.CodeRay .doc{color:#970}
|
|
.CodeRay .doctype{color:#34b}
|
|
.CodeRay .doc-string{color:#d42}
|
|
.CodeRay .escape{color:#666}
|
|
.CodeRay .entity{color:#800}
|
|
.CodeRay .error{color:#808}
|
|
.CodeRay .exception{color:inherit}
|
|
.CodeRay .filename{color:#099}
|
|
.CodeRay .function{color:#900;font-weight:bold}
|
|
.CodeRay .global-variable{color:#008080}
|
|
.CodeRay .hex{color:#058}
|
|
.CodeRay .integer,.CodeRay .float{color:#099}
|
|
.CodeRay .include{color:#555}
|
|
.CodeRay .inline{color:#000}
|
|
.CodeRay .inline .inline{background:#ccc}
|
|
.CodeRay .inline .inline .inline{background:#bbb}
|
|
.CodeRay .inline .inline-delimiter{color:#d14}
|
|
.CodeRay .inline-delimiter{color:#d14}
|
|
.CodeRay .important{color:#555;font-weight:bold}
|
|
.CodeRay .interpreted{color:#b2b}
|
|
.CodeRay .instance-variable{color:#008080}
|
|
.CodeRay .label{color:#970}
|
|
.CodeRay .local-variable{color:#963}
|
|
.CodeRay .octal{color:#40e}
|
|
.CodeRay .predefined{color:#369}
|
|
.CodeRay .preprocessor{color:#579}
|
|
.CodeRay .pseudo-class{color:#555}
|
|
.CodeRay .directive{font-weight:bold}
|
|
.CodeRay .type{font-weight:bold}
|
|
.CodeRay .predefined-type{color:inherit}
|
|
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
|
|
.CodeRay .key{color:#808}
|
|
.CodeRay .key .delimiter{color:#606}
|
|
.CodeRay .key .char{color:#80f}
|
|
.CodeRay .value{color:#088}
|
|
.CodeRay .regexp .delimiter{color:#808}
|
|
.CodeRay .regexp .content{color:#808}
|
|
.CodeRay .regexp .modifier{color:#808}
|
|
.CodeRay .regexp .char{color:#d14}
|
|
.CodeRay .regexp .function{color:#404;font-weight:bold}
|
|
.CodeRay .string{color:#d20}
|
|
.CodeRay .string .string .string{background:#ffd0d0}
|
|
.CodeRay .string .content{color:#d14}
|
|
.CodeRay .string .char{color:#d14}
|
|
.CodeRay .string .delimiter{color:#d14}
|
|
.CodeRay .shell{color:#d14}
|
|
.CodeRay .shell .delimiter{color:#d14}
|
|
.CodeRay .symbol{color:#990073}
|
|
.CodeRay .symbol .content{color:#a60}
|
|
.CodeRay .symbol .delimiter{color:#630}
|
|
.CodeRay .tag{color:#008080}
|
|
.CodeRay .tag-special{color:#d70}
|
|
.CodeRay .variable{color:#036}
|
|
.CodeRay .insert{background:#afa}
|
|
.CodeRay .delete{background:#faa}
|
|
.CodeRay .change{color:#aaf;background:#007}
|
|
.CodeRay .head{color:#f8f;background:#505}
|
|
.CodeRay .insert .insert{color:#080}
|
|
.CodeRay .delete .delete{color:#800}
|
|
.CodeRay .change .change{color:#66f}
|
|
.CodeRay .head .head{color:#f4f}
|
|
</style>
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/tocbot/3.0.7/tocbot.min.js"></script>
|
|
<script>
|
|
/* Tocbot dynamic TOC, works with tocbot 3.0.7 */
|
|
var oldtoc = document.getElementById('toctitle').nextElementSibling;
|
|
var newtoc = document.createElement('div');
|
|
newtoc.setAttribute('id', 'tocbot');
|
|
newtoc.setAttribute('class', 'js-toc');
|
|
oldtoc.parentNode.replaceChild(newtoc, oldtoc);
|
|
tocbot.init({ contentSelector: '#content',
|
|
headingSelector: 'h1, h2, h3, h4',
|
|
smoothScroll: false,
|
|
collapseDepth: 2 });
|
|
var handleTocOnResize = function() {
|
|
var width = window.innerWidth
|
|
|| document.documentElement.clientWidth
|
|
|| document.body.clientWidth;
|
|
if (width < 768) {
|
|
tocbot.refresh({ contentSelector: '#content',
|
|
headingSelector: 'h1, h2, h3, h4',
|
|
collapseDepth: 6,
|
|
activeLinkClass: 'ignoreactive',
|
|
throttleTimeout: 1000,
|
|
smoothScroll: false });
|
|
}
|
|
else {
|
|
tocbot.refresh({ contentSelector: '#content',
|
|
headingSelector: 'h1, h2, h3, h4',
|
|
smoothScroll: false,
|
|
collapseDepth: 2 });
|
|
}
|
|
};
|
|
window.addEventListener('resize', handleTocOnResize);
|
|
handleTocOnResize();
|
|
</script>
|
|
</body>
|
|
</html> |