| 1 |
package Perinci::CmdLine::Manual::Examples; # just to make podweaver happy |
| 2 |
|
| 3 |
use strict; |
| 4 |
|
| 5 |
# AUTHORITY |
| 6 |
# DATE |
| 7 |
our $DIST = 'Perinci-CmdLine'; # DIST |
| 8 |
# VERSION |
| 9 |
|
| 10 |
1; |
| 11 |
# ABSTRACT: Collection of examples |
| 12 |
|
| 13 |
__END__ |
| 14 |
|
| 15 |
=pod |
| 16 |
|
| 17 |
=encoding UTF-8 |
| 18 |
|
| 19 |
=head1 NAME |
| 20 |
|
| 21 |
Perinci::CmdLine::Manual::Examples - Collection of examples |
| 22 |
|
| 23 |
=head1 VERSION |
| 24 |
|
| 25 |
This document describes version 2.000.2 of Perinci::CmdLine::Manual::Examples (from Perl distribution Perinci-CmdLine), released on 2026-03-30. |
| 26 |
|
| 27 |
=head1 DESCRIPTION |
| 28 |
|
| 29 |
In the examples, L<Perinci::CmdLine::Any> is used to show examples that are |
| 30 |
applicable to either L<Perinci::CmdLine::Classic> or L<Perinci::CmdLine::Lite>. |
| 31 |
For examples that are more appropriate or only applicable to specific |
| 32 |
implementation, the specific module will be used. |
| 33 |
|
| 34 |
Perinci::CmdLine::Classic is hereby referred to as C<PC::Classic>, while |
| 35 |
Perinci::CmdLine as C<PC::Lite>. |
| 36 |
|
| 37 |
=head1 BASICS |
| 38 |
|
| 39 |
=head2 Simplest application |
| 40 |
|
| 41 |
Since Perinci::CmdLine is function- and metadata-based, you need to create at |
| 42 |
least one function and add some metadata for it. And you'll need to return the |
| 43 |
result as an enveloped response. The simplest is something like: |
| 44 |
|
| 45 |
#!perl |
| 46 |
use strict; |
| 47 |
use warnings; |
| 48 |
use Perinci::CmdLine::Any; |
| 49 |
|
| 50 |
our %SPEC; |
| 51 |
$SPEC{hello} = { |
| 52 |
v => 1.1, |
| 53 |
summary => 'Say hello', |
| 54 |
}; |
| 55 |
sub hello { |
| 56 |
[200, "OK", "Hello, world!"]; |
| 57 |
} |
| 58 |
|
| 59 |
Perinci::CmdLine::Any->new(url => '/main/hello')->run; |
| 60 |
|
| 61 |
The C<url> attribute specifies the location of the function in URL format (see |
| 62 |
L<Riap> for more details on the syntax of URL). It is basically a |
| 63 |
fully-qualified function name, with C<::> replaced with C</>. With this |
| 64 |
URL-based syntax, it is possible to use a remote and/or non-Perl function for |
| 65 |
the CLI application. |
| 66 |
|
| 67 |
The hash in C<$SPEC{hello}> is called a L<Rinci> metadata. The keys are called |
| 68 |
properties. There are two properties: C<v> (which is always required with the |
| 69 |
value of 1.1 to specify version) and C<summary> (which is actually optional, to |
| 70 |
describe the function). |
| 71 |
|
| 72 |
In this example, the function and its metadata is put inside the same script. |
| 73 |
You can of course put them in a separate Perl module, and use them with e.g. C<< |
| 74 |
url => '/Your/Module/func' >>. It is also worth mentioning that if you use the |
| 75 |
Perinci::CmdLine framework, your functions can also be used directly by other |
| 76 |
Perl modules/code since they are just regular Perl functions. |
| 77 |
|
| 78 |
The function returns a 3-element array containing HTTP-like status code, a |
| 79 |
status message, and the actual result. |
| 80 |
|
| 81 |
If you save the above script as C<hello> run it on the command-line: |
| 82 |
|
| 83 |
% ./hello |
| 84 |
Hello, world! |
| 85 |
|
| 86 |
Yup, not very interesting. You get help message for free: |
| 87 |
|
| 88 |
% ./hello --help |
| 89 |
% ./hello -h |
| 90 |
|
| 91 |
As well as some common options like C<--format> to return the result in a |
| 92 |
different format: |
| 93 |
|
| 94 |
% ./hello --json |
| 95 |
[200,"OK","Hello, world!"] |
| 96 |
|
| 97 |
% ./hello --format perl; # only in PC::Classic, not available in PC::Lite |
| 98 |
[200, "OK", "Hello, world!"] |
| 99 |
|
| 100 |
=head1 FUNCTION ARGUMENTS AND COMMAND-LINE OPTIONS |
| 101 |
|
| 102 |
=head2 Basics |
| 103 |
|
| 104 |
Function arguments map to command-line options. Example: |
| 105 |
|
| 106 |
#!perl |
| 107 |
use strict; |
| 108 |
use warnings; |
| 109 |
use Perinci::CmdLine::Any; |
| 110 |
|
| 111 |
our %SPEC; |
| 112 |
$SPEC{hello} = { |
| 113 |
v => 1.1, |
| 114 |
summary => 'Say hello', |
| 115 |
args => { |
| 116 |
name => { |
| 117 |
summary => 'Name to say hello to', |
| 118 |
}, |
| 119 |
}, |
| 120 |
}; |
| 121 |
sub hello { |
| 122 |
my %args = @_; |
| 123 |
[200, "OK", "Hello, $args{name}!"]; |
| 124 |
} |
| 125 |
|
| 126 |
Perinci::CmdLine::Any->new(url => '/main/hello')->run; |
| 127 |
|
| 128 |
When you run this: |
| 129 |
|
| 130 |
% ./hello --name Jimmy |
| 131 |
Hello, Jimmy! |
| 132 |
|
| 133 |
If you run C<./hello --help>, the option is now mentioned as well in the help |
| 134 |
message. |
| 135 |
|
| 136 |
Unknown arguments will result in an error: |
| 137 |
|
| 138 |
% ./hello --gender m |
| 139 |
ERROR 400: Unknown option '--gender' |
| 140 |
|
| 141 |
To specify that an argument is required, add C<req> property to the argument |
| 142 |
specification with a true value: |
| 143 |
|
| 144 |
args => { |
| 145 |
name => { |
| 146 |
summary => 'Name to say hello to', |
| 147 |
req => 1, |
| 148 |
}, |
| 149 |
}, |
| 150 |
|
| 151 |
So when you run the app: |
| 152 |
|
| 153 |
% ./hello |
| 154 |
ERROR 400: Missing required argument 'name' |
| 155 |
|
| 156 |
To specify that an argument can also be specified via positional command-line |
| 157 |
I<argument> instead of just command-line I<option>, add C<pos> property to the |
| 158 |
argument specification: |
| 159 |
|
| 160 |
args => { |
| 161 |
name => { |
| 162 |
summary => 'Name to say hello to', |
| 163 |
req => 1, |
| 164 |
pos => 0, |
| 165 |
}, |
| 166 |
}, |
| 167 |
|
| 168 |
So when you run the app you can specify: |
| 169 |
|
| 170 |
% ./hello --name Jimmy |
| 171 |
Hello, Jimmy! |
| 172 |
|
| 173 |
as well as: |
| 174 |
|
| 175 |
% ./hello Jimmy |
| 176 |
Hello, Jimmy! |
| 177 |
|
| 178 |
Extra arguments will also result in an error: |
| 179 |
|
| 180 |
% ./hello Jimmy Gideon |
| 181 |
ERROR 400: Extra argument 'Gideon' |
| 182 |
|
| 183 |
=head2 Argument schema (and more on text output formats) |
| 184 |
|
| 185 |
Following up from the previous example, here's another example with more |
| 186 |
arguments. Also note that I use PC::Classic since PC::Lite doesn't do schema |
| 187 |
validation. |
| 188 |
|
| 189 |
#!perl |
| 190 |
use 5.010; |
| 191 |
use strict; |
| 192 |
use warnings; |
| 193 |
use Perinci::CmdLine; |
| 194 |
|
| 195 |
our %SPEC; |
| 196 |
$SPEC{hello} = { |
| 197 |
v => 1.1, |
| 198 |
summary => 'Say hello', |
| 199 |
args => { |
| 200 |
name => { |
| 201 |
summary => 'Name(s) to say hello to', |
| 202 |
schema => [array => {of => 'str', min_len=>1}], |
| 203 |
req => 1, |
| 204 |
pos => 0, |
| 205 |
slurpy => 1, |
| 206 |
}, |
| 207 |
gender => { |
| 208 |
summary => 'The gender of the name(s)', |
| 209 |
schema => [str => {in => ['m','f']}], |
| 210 |
}, |
| 211 |
}, |
| 212 |
}; |
| 213 |
sub hello { |
| 214 |
my %args = @_; |
| 215 |
my $g = $args{gender}; |
| 216 |
my @res; |
| 217 |
for my $name (@{ $args{name} // [] }) { |
| 218 |
push @res, join("", |
| 219 |
"Hello, ", |
| 220 |
(!$g ? "" : $g eq 'm' ? "Mr. " : "Mrs. "), |
| 221 |
$name, '!', |
| 222 |
); |
| 223 |
} |
| 224 |
[200, "OK", \@res]; |
| 225 |
} |
| 226 |
Perinci::CmdLine->new(url => '/main/hello')->run; |
| 227 |
|
| 228 |
If you run this program: |
| 229 |
|
| 230 |
% ./hello Jimmy Sion Habil |
| 231 |
% ./hello --name Jimmy --name Sion --name Habil |
| 232 |
Hello, Jimmy! |
| 233 |
Hello, Sion! |
| 234 |
Hello, Habil! |
| 235 |
|
| 236 |
% ./hello --name-json '["Jimmy","Sion","Habil"]' --gender m |
| 237 |
Hello, Mr. Jimmy! |
| 238 |
Hello, Mr. Sion! |
| 239 |
Hello, Mr. Habil! |
| 240 |
|
| 241 |
Some things you might notice. First, there is a C<schema> property for each |
| 242 |
argument. C<name> is specified as having a type of array of strings. To set this |
| 243 |
argument from the CLI, you can either specify multiple times (e.g. C<--name |
| 244 |
NAME1 --name NAME2 ...>) or specify using JSON (i.e. C<--name-json JSONSTR>). |
| 245 |
|
| 246 |
Second, the C<name> argument specifies the C<slurpy> property. This is used in |
| 247 |
conjunction with the C<pos> property. It declares that the argument will gobble |
| 248 |
up command-line arguments from C<pos> to the end. So you can also specify the |
| 249 |
values of the C<name> argument with C<ARG1 ARG2 ...>. |
| 250 |
|
| 251 |
Third, if you specify value that does not validate, an error will be produced. |
| 252 |
|
| 253 |
% ./hello --name-json '[]' |
| 254 |
ERROR 400: Invalid value for argument 'name': Length must be at least 1 |
| 255 |
|
| 256 |
% ./hello --name Jimmy --name Sion --name Habil --gender x |
| 257 |
ERROR 400: Invalid value for argument 'gender': Must be one of ["m","f"] |
| 258 |
|
| 259 |
See L<Data::Sah> for more about the schema syntax. |
| 260 |
|
| 261 |
Fourth, you return the result as a data structure (an array) instead of directly |
| 262 |
printing the result using C<print()> or C<say()>. This is done to make your |
| 263 |
function more reusable outside the context of CLI. PC::Classic will format your |
| 264 |
data structure nicely using L<Data::Format::Pretty>. Your array will be printed |
| 265 |
as a multicolumn ANSI table by default, on interactive mode. If you pipe the |
| 266 |
output of your program, you will by default get a simpler text output. This can |
| 267 |
be chosen explicitly using the C<--format> common option. |
| 268 |
|
| 269 |
% ./hello Jimmy Sion Habil --format text; # will output pretty or simple depending on whether interactive |
| 270 |
% ./hello Jimmy Sion Habil --format text-simple; # will still output simple table even when interactive |
| 271 |
% ./hello Jimmy Sion Habil --format text-pretty; # will still output pretty table even when piped |
| 272 |
|
| 273 |
=head2 Short option aliases |
| 274 |
|
| 275 |
To add short options, you can use the C<cmdline_aliases> property in the |
| 276 |
argument specification: |
| 277 |
|
| 278 |
name => { |
| 279 |
... |
| 280 |
cmdline_aliases => { n => {} }, |
| 281 |
}, |
| 282 |
gender => { |
| 283 |
... |
| 284 |
cmdline_aliases => { g => {} }, |
| 285 |
}, |
| 286 |
|
| 287 |
Now instead of: |
| 288 |
|
| 289 |
% ./hello --name Jimmy --name Sion --name Habil --gender m |
| 290 |
|
| 291 |
you can also use: |
| 292 |
|
| 293 |
% ./hello -n Jimmy -n Sion -n Habil -g m |
| 294 |
|
| 295 |
=head2 More on command-line option aliases |
| 296 |
|
| 297 |
You are not limited to one alias, or one letter: |
| 298 |
|
| 299 |
gender => { |
| 300 |
... |
| 301 |
cmdline_aliases => { g => {}, sex => {} }, |
| 302 |
}, |
| 303 |
|
| 304 |
Now all these are equivalent: |
| 305 |
|
| 306 |
% ./hello ... --gender m |
| 307 |
% ./hello ... -g m |
| 308 |
% ./hello ... --sex m |
| 309 |
|
| 310 |
Suppose you want to create an alias C<-m> to mean C<--gender m> and C<-f> to |
| 311 |
mean C<--gender f> instead: |
| 312 |
|
| 313 |
gender => { |
| 314 |
... |
| 315 |
cmdline_aliases => { |
| 316 |
m => { schema=>'bool', code => sub {my $args=shift; $args->{gender} = 'm' } }, |
| 317 |
f => { schema=>'bool', code => sub {my $args=shift; $args->{gender} = 'f' } }, |
| 318 |
}, |
| 319 |
}, |
| 320 |
|
| 321 |
Now you can say: |
| 322 |
|
| 323 |
% ./hello Jimmy Sion -m |
| 324 |
Hello, Mr. Jimmy! |
| 325 |
Hello, Mr. Sion! |
| 326 |
|
| 327 |
% ./hello Nunung Misye -f |
| 328 |
Hello, Mrs. Nunung! |
| 329 |
Hello, Mrs. Misye! |
| 330 |
|
| 331 |
=head2 My function has some cmdline_aliases or cmdline_src defined but I want to change it! |
| 332 |
|
| 333 |
For example, your C<f1> function metadata might look like this: |
| 334 |
|
| 335 |
package Package::F1; |
| 336 |
our %SPEC; |
| 337 |
$SPEC{f1} = { |
| 338 |
v => 1.1, |
| 339 |
args => { |
| 340 |
foo => { |
| 341 |
cmdline_aliases => { f=> {} }, |
| 342 |
}, |
| 343 |
bar => { ... }, |
| 344 |
fee => { ... }, |
| 345 |
}, |
| 346 |
}; |
| 347 |
sub f1 { ... } |
| 348 |
1; |
| 349 |
|
| 350 |
And your command-line script C<f1>: |
| 351 |
|
| 352 |
#!perl |
| 353 |
use Perinci::CmdLine; |
| 354 |
Perinci::CmdLine->new(url => '/Package/F1/f1')->run; |
| 355 |
|
| 356 |
Now you want to create a command-line script interface for this function, but |
| 357 |
with C<-f> as an alias for C<--fee> instead of C<--foo>. This is best done by |
| 358 |
modifying the metadata and creating a wrapper function to do this, e.g. your |
| 359 |
command-line script C<f1> becomes: |
| 360 |
|
| 361 |
package main; |
| 362 |
use Perinci::CmdLine; |
| 363 |
use Package::F1; |
| 364 |
use Data::Clone; |
| 365 |
our %SPEC; |
| 366 |
$SPEC{f1} = clone $Package::F1::SPEC{f1}; |
| 367 |
delete $SPEC{f1}{args}{foo}{cmdline_aliases}; |
| 368 |
$SPEC{f1}{args}{fee}{cmdline_aliases} = {f=>{}}; |
| 369 |
*f1 = \&Package::F1::f1; |
| 370 |
Perinci::CmdLine->new(url => '/main/f1')->run; |
| 371 |
|
| 372 |
This also demonstrates the convenience of having the metadata as a data |
| 373 |
structure: you can manipulate it however you want. There is also a convenient |
| 374 |
helper function available in L<Perinci::Sub::Util> when you want to create a |
| 375 |
modified subroutine based on another: |
| 376 |
|
| 377 |
package main; |
| 378 |
use Perinci::CmdLine; |
| 379 |
use Perinci::Sub::Util qw(gen_modified_sub); |
| 380 |
|
| 381 |
gen_modified_sub( |
| 382 |
output_name => 'f1', |
| 383 |
base_name => 'Package::F1::f1', |
| 384 |
modify_args => { |
| 385 |
foo => sub { my $as = shift; delete $as->{cmdline_aliases} }, |
| 386 |
fee => sub { my $as = shift; $as->{cmdline_aliases} = {f=>{} }, |
| 387 |
}, |
| 388 |
); |
| 389 |
Perinci::CmdLine->new(url => '/main/f1')->run; |
| 390 |
|
| 391 |
=head2 Overriding common option |
| 392 |
|
| 393 |
Example: My function has argument named 'format', but it is blocked by common |
| 394 |
option '--format'! |
| 395 |
|
| 396 |
To add/remove/rename common options, see the documentation on C<common_opts> |
| 397 |
attribute. In this case, you want: |
| 398 |
|
| 399 |
delete $cmd->common_opts->{format}; |
| 400 |
#delete $cmd->common_opts->{format_options}; # you might also want this |
| 401 |
|
| 402 |
or perhaps rename it: |
| 403 |
|
| 404 |
$cmd->common_opts->{output_format} = $cmd->common_opts->{format}; |
| 405 |
delete $cmd->common_opts->{format}; |
| 406 |
|
| 407 |
=head1 INPUT |
| 408 |
|
| 409 |
=head2 Accepting input from STDIN (or files) |
| 410 |
|
| 411 |
If you specify 'cmdline_src' to 'stdin' to a 'str' argument, the argument's |
| 412 |
value will be retrieved from standard input if not specified. Example: |
| 413 |
|
| 414 |
use Perinci::CmdLine; |
| 415 |
$SPEC{cmd} = { |
| 416 |
v => 1.1, |
| 417 |
args => { |
| 418 |
arg => { |
| 419 |
schema => 'str*', |
| 420 |
cmdline_src => 'stdin', |
| 421 |
}, |
| 422 |
}, |
| 423 |
}; |
| 424 |
sub cmd { |
| 425 |
my %args = @_; |
| 426 |
[200, "OK", "arg is '$args{arg}'"]; |
| 427 |
} |
| 428 |
Perinci::CmdLine->new(url=>'/main/cmd')->run; |
| 429 |
|
| 430 |
When run from command line: |
| 431 |
|
| 432 |
% cat file.txt |
| 433 |
This is content of file.txt |
| 434 |
% cat file.txt | cmd |
| 435 |
arg is 'This is content of file.txt' |
| 436 |
|
| 437 |
If your function argument is an array, array of lines will be provided to your |
| 438 |
function. |
| 439 |
|
| 440 |
Note that this will glob the whole content of input into memory. If you want |
| 441 |
streaming, see the next section. |
| 442 |
|
| 443 |
=head2 Accept streaming input |
| 444 |
|
| 445 |
To accept streaming input, you specify one or more of your arguments as C<< |
| 446 |
stream=>1 >>. Also, these arguments need to specify their source either from |
| 447 |
file, STDIN, or STDIN/files, by setting C<< cmdline_src => |
| 448 |
file|stdin|stdin_or_files >>, because otherwise, just receiving value from |
| 449 |
command-line option like C<--arg val> is not very interesting :-). You will |
| 450 |
receive your function argument as a coderef which you can call repeatedly until |
| 451 |
input is exhausted (at the point of which the coderef will return undef). |
| 452 |
|
| 453 |
$SPEC{perl_wc} = { |
| 454 |
v => 1.1, |
| 455 |
args => { |
| 456 |
input => { |
| 457 |
schema => 'str*', |
| 458 |
stream => 1, |
| 459 |
cmdline_src => 'stdin_or_files', |
| 460 |
}, |
| 461 |
}, |
| 462 |
}; |
| 463 |
sub perl_wc { |
| 464 |
my %args = @_; |
| 465 |
my $input = $args{input}; |
| 466 |
|
| 467 |
my $chars = 0; |
| 468 |
my $words = 0; |
| 469 |
my $lines = 0; |
| 470 |
while (my $line = $input->()) { |
| 471 |
$lines++; |
| 472 |
$chars += length($line); |
| 473 |
chomp $line; |
| 474 |
my @w = split /[ \t]+/o, $line; $words += @w; |
| 475 |
} |
| 476 |
|
| 477 |
[200, "OK", {chars=>$chars, words=>$words, lines=>$lines}]; |
| 478 |
} |
| 479 |
|
| 480 |
When run: |
| 481 |
|
| 482 |
% ls -l | perl_wc |
| 483 |
+-------+-------+ |
| 484 |
| key | value | |
| 485 |
+-------+-------+ |
| 486 |
| chars | 1995 | |
| 487 |
| lines | 42 | |
| 488 |
| words | 61 | |
| 489 |
+-------+-------+ |
| 490 |
|
| 491 |
Note: by default you will get string/text input line-by-line, and for binary |
| 492 |
(C<buf>) per-64k. This will be configurable in the future. |
| 493 |
|
| 494 |
If argument type is not simple (e.g. an array or hash), then JSON stream input |
| 495 |
will be assumed. This means, each line of input will be parsed as JSON. |
| 496 |
|
| 497 |
=head1 OUTPUT |
| 498 |
|
| 499 |
=head2 Default output format |
| 500 |
|
| 501 |
TODO |
| 502 |
|
| 503 |
=head2 Removing borders |
| 504 |
|
| 505 |
By default, the text format produces bordered tables in interactive mode, e.g. |
| 506 |
if you have this program: |
| 507 |
|
| 508 |
$SPEC{foo} = {v=>1.1}; |
| 509 |
sub foo { |
| 510 |
[200, "OK", [[1,2], [3,4], [5,6]]]; |
| 511 |
} |
| 512 |
use Perinci::CmdLine::Any; |
| 513 |
Perinci::CmdLine::Any->new(url => '/main/foo')->run; |
| 514 |
|
| 515 |
and you run it, you will have: |
| 516 |
|
| 517 |
% foo |
| 518 |
+---+---+ |
| 519 |
| 1 | 2 | |
| 520 |
| 3 | 4 | |
| 521 |
| 5 | 6 | |
| 522 |
+---+---+ |
| 523 |
|
| 524 |
and if you use C<--format text-simple>, only then it will become a tab-separated |
| 525 |
format: |
| 526 |
|
| 527 |
% foo --format text-simple |
| 528 |
1 2 |
| 529 |
3 4 |
| 530 |
5 6 |
| 531 |
|
| 532 |
But if you don't like this formatting and want to default to simpler formatting |
| 533 |
by default, you can add C<cmdline.default_format> attribute to your function |
| 534 |
metadata: |
| 535 |
|
| 536 |
$SPEC{foo} = {v=>1.1, 'cmdline.default_format' => 'text-simple'}; |
| 537 |
|
| 538 |
Using this attribute, you can also default to JSON, and so on if you want. |
| 539 |
|
| 540 |
You can also do this on a per-result basis, by adding C<cmdline.default_format> |
| 541 |
attribute in your result metadata, e.g.: |
| 542 |
|
| 543 |
sub foo { |
| 544 |
[200, "OK", [[1,2], [3,4], [5,6]], {'cmdline.default_format'=>'text-simple'}]; |
| 545 |
} |
| 546 |
|
| 547 |
=head2 Streaming output |
| 548 |
|
| 549 |
To produce streaming output, set C<< stream=>1 >> in C<result> spec in function |
| 550 |
metadata. Then in your function, return a subroutine reference that will allow |
| 551 |
caller to read data from. |
| 552 |
|
| 553 |
$SPEC{nat} = { |
| 554 |
v => 1.1, |
| 555 |
summary => 'Generate an infinite sequence of natural numbers', |
| 556 |
args => {}, |
| 557 |
result => { |
| 558 |
stream => 1, |
| 559 |
schema => 'str*', |
| 560 |
}, |
| 561 |
}; |
| 562 |
sub nat { |
| 563 |
my $n = 1; |
| 564 |
[200, "OK", sub { $n++ }]; |
| 565 |
} |
| 566 |
|
| 567 |
If result type is not simple (e.g. an array or hash), then each record will be |
| 568 |
encoded into JSON, to produce JSON stream. |
| 569 |
|
| 570 |
If you want to return a file content as a stream (instead of slurping the whole |
| 571 |
content into memory): |
| 572 |
|
| 573 |
$SPEC{catfile} = { |
| 574 |
v => 1.1, |
| 575 |
summary => "Display file contents", |
| 576 |
args => { file => { schema => 'filename*', req=>1, pos=>0 } }, |
| 577 |
result => { stream => 1, schema => 'str*' }, |
| 578 |
}; |
| 579 |
sub catfile { |
| 580 |
my %args = @_; |
| 581 |
my $file = $args{file}; |
| 582 |
open my $fh, "<", $file or return [500, "Can't open file '$file': $!"]; |
| 583 |
[200, "OK", sub { scalar(<$fh>) }]; |
| 584 |
} |
| 585 |
|
| 586 |
=head2 Adding support for new format |
| 587 |
|
| 588 |
TODO |
| 589 |
|
| 590 |
=head2 Pager |
| 591 |
|
| 592 |
TODO |
| 593 |
|
| 594 |
=head2 Word wrapping |
| 595 |
|
| 596 |
If your table has long text that is better shown in a multi-line cell, you can |
| 597 |
do: |
| 598 |
|
| 599 |
% FORMAT_PRETTY_TABLE_BACKEND=Text::ANSITable your-app ... |
| 600 |
|
| 601 |
to use L<Text::ANSITable>, which by default wraps long text in table cells. |
| 602 |
|
| 603 |
=head1 CONFIGURATION |
| 604 |
|
| 605 |
=head2 Basics |
| 606 |
|
| 607 |
In the function-centric world of Perinci::CmdLine, configuration is just another |
| 608 |
way to supply values to function arguments (before being potentially overridden |
| 609 |
by command-line arguments). Configuration files are written in L<IOD> format, |
| 610 |
which is basically "INI with extra features". By default, configuration files |
| 611 |
are searched in C</etc> and then your home directory, with the name of |
| 612 |
I<program_name> + C<.conf>. So if you have: |
| 613 |
|
| 614 |
# ~/prog.conf |
| 615 |
foo=1 |
| 616 |
bar=2 |
| 617 |
|
| 618 |
and: |
| 619 |
|
| 620 |
# prog |
| 621 |
#!perl |
| 622 |
use Perinci::CmdLine::Any; |
| 623 |
$SPEC{prog} = { |
| 624 |
v => 1.1, |
| 625 |
args => { |
| 626 |
foo => {}, |
| 627 |
bar => {}, |
| 628 |
}, |
| 629 |
}; |
| 630 |
sub prog { |
| 631 |
my %args = @_; |
| 632 |
[200, "OK", "foo is $args{foo}, while bar is $args{bar}"]; |
| 633 |
} |
| 634 |
Perinci::CmdLine::Any->new(url=>'/main/prog')->run; |
| 635 |
|
| 636 |
When you run: |
| 637 |
|
| 638 |
% prog |
| 639 |
|
| 640 |
you'll get: |
| 641 |
|
| 642 |
foo is 1, while bar is 2 |
| 643 |
|
| 644 |
Multiple configuration files will be merged, so if you have: |
| 645 |
|
| 646 |
# /etc/prog.conf |
| 647 |
foo=1 |
| 648 |
bar=2 |
| 649 |
|
| 650 |
# ~/prog.conf |
| 651 |
foo=10 |
| 652 |
|
| 653 |
you'll get: |
| 654 |
|
| 655 |
foo is 10, while bar is 2 |
| 656 |
|
| 657 |
=head2 Configuration profiles |
| 658 |
|
| 659 |
Configuration file can store more than one set of arguments, through specially |
| 660 |
named sections, called profiles: |
| 661 |
|
| 662 |
# ~/prog.conf |
| 663 |
foo=1 |
| 664 |
bar=2 |
| 665 |
|
| 666 |
[profile=p1] |
| 667 |
foo=21 |
| 668 |
bar=22 |
| 669 |
|
| 670 |
[profile=p2] |
| 671 |
foo=31 |
| 672 |
bar=32 |
| 673 |
|
| 674 |
Running the program: |
| 675 |
|
| 676 |
% prog |
| 677 |
foo is 1, while bar is 2 |
| 678 |
% prog --config-profile p1 |
| 679 |
foo is 21, while bar is 22 |
| 680 |
% prog --config-profile p2 |
| 681 |
foo is 31, while bar is 32 |
| 682 |
|
| 683 |
=head2 Configuration with subcommands |
| 684 |
|
| 685 |
TODO |
| 686 |
|
| 687 |
=head2 Ignoring configuration files |
| 688 |
|
| 689 |
If you don't want to use any configuration files, you can use: |
| 690 |
|
| 691 |
% prog --noconfig ... |
| 692 |
|
| 693 |
=head2 DEBUGGING |
| 694 |
|
| 695 |
TODO |
| 696 |
|
| 697 |
=head2 REMOTE FUNCTION |
| 698 |
|
| 699 |
=head1 SHELL COMPLETION |
| 700 |
|
| 701 |
=head2 Custom completion |
| 702 |
|
| 703 |
By default, L<Perinci::Sub::Complete>'s C<complete_arg_val()> can employ some |
| 704 |
heuristics to complete argument values, e.g. from the C<in> clause or C<max> and |
| 705 |
C<min>: |
| 706 |
|
| 707 |
$SPEC{set_ticket_status} = { |
| 708 |
v => 1.1, |
| 709 |
args => { |
| 710 |
ticket_id => { ... }, |
| 711 |
status => { |
| 712 |
schema => ['str*', in => [qw/new open stalled resolved rejected/], |
| 713 |
}, |
| 714 |
}, |
| 715 |
} |
| 716 |
|
| 717 |
But if you want to supply custom completion, the L<Rinci::function> |
| 718 |
specification allows specifying a C<completion> property for your argument, for |
| 719 |
example: |
| 720 |
|
| 721 |
use Complete::Util qw(complete_array_elem); |
| 722 |
$SPEC{del_user} = { |
| 723 |
v => 1.1, |
| 724 |
args => { |
| 725 |
username => { |
| 726 |
schema => 'str*', |
| 727 |
req => 1, |
| 728 |
pos => 0, |
| 729 |
completion => sub { |
| 730 |
my %args = @_; |
| 731 |
|
| 732 |
# get list of users from database or whatever |
| 733 |
my @users = ...; |
| 734 |
complete_array_elem(array=>\@users, word=>$args{word}); |
| 735 |
}, |
| 736 |
}, |
| 737 |
... |
| 738 |
}, |
| 739 |
}; |
| 740 |
|
| 741 |
You can use completion in your command-line program: |
| 742 |
|
| 743 |
% del-user --username <tab> |
| 744 |
% del-user <tab> ; # since the 'username' argument has pos=0 |
| 745 |
|
| 746 |
=head2 My custom completion does not work, how do I debug it? |
| 747 |
|
| 748 |
Completion works by the shell invoking our (the same) program with C<COMP_LINE> |
| 749 |
and C<COMP_POINT> environment variables. You can do something like this to see |
| 750 |
debugging information: |
| 751 |
|
| 752 |
% COMP_LINE='myprog --arg x' COMP_POINT=13 PERL5OPT=-MLog::ger::App TRACE=1 myprog --arg x |
| 753 |
|
| 754 |
You can also use the L<testcomp> utility (included in the L<App::CompleteUtils> |
| 755 |
distribution) to help debug your custom completion: |
| 756 |
|
| 757 |
% testcomp myprog --arg x^ |
| 758 |
|
| 759 |
Place the C<^> caret character to simulate the position of the cursor when |
| 760 |
tab-completion is attempted. |
| 761 |
|
| 762 |
=head1 I18N |
| 763 |
|
| 764 |
=head1 OTHERS |
| 765 |
|
| 766 |
=head2 Modifying common options |
| 767 |
|
| 768 |
=head2 Customizing help message |
| 769 |
|
| 770 |
=head2 Dealing with binary data |
| 771 |
|
| 772 |
=head2 (Client) (Server) Dealing with binary data |
| 773 |
|
| 774 |
The choice as JSON as the network transport protocol for Riap (because it is the |
| 775 |
lowest common denominator across languages like JavaScript, PHP, Python, Ruby, |
| 776 |
Perl) makes dealing with binary data requires an extra step or two. The |
| 777 |
Perinci::CmdLine framework are equipped with some features to make this simpler |
| 778 |
and more convenient. |
| 779 |
|
| 780 |
First, to make a function that accepts binary data (in its arguments), you need |
| 781 |
to specify the argument type as C<buf>. To return binary data as result, you |
| 782 |
need to specify C<result>'s schema type as C<buf>. Example: |
| 783 |
|
| 784 |
package MyLib; |
| 785 |
our %SPEC; |
| 786 |
$SPEC{gzip} = { |
| 787 |
v => 1.1, |
| 788 |
summary => 'Gzip some data', |
| 789 |
args => { |
| 790 |
data => { |
| 791 |
summary => 'Data to compress', |
| 792 |
schema => 'buf*', |
| 793 |
req => 1, |
| 794 |
}, |
| 795 |
}, |
| 796 |
}; |
| 797 |
sub gzip { |
| 798 |
require IO::Compress::Gzip; |
| 799 |
|
| 800 |
my %args = @_; |
| 801 |
my $compressed; |
| 802 |
IO::Compress::Gzip::gzip($args{data} => $compressed) |
| 803 |
or return [500, "Compression failed"]; |
| 804 |
[200, "OK", $compressed]; |
| 805 |
} |
| 806 |
|
| 807 |
If you use this function in Perinci::CmdLine, you will get the command-line |
| 808 |
option C<--data-base64> in addition to the usual C<--data>. With |
| 809 |
C<--data-base64>, you can specify binary data including NUL bytes from the |
| 810 |
command-line. |
| 811 |
|
| 812 |
If you specify the argument as accepting data from stdin or files like this: |
| 813 |
|
| 814 |
args => { |
| 815 |
data => { |
| 816 |
summary => 'Data to compress', |
| 817 |
schema => 'buf*', |
| 818 |
req => 1, |
| 819 |
cmdline_src => 'stdin_or_files', |
| 820 |
}, |
| 821 |
}, |
| 822 |
|
| 823 |
you can pass binary data, e.g.: |
| 824 |
|
| 825 |
% yourprog < /some/bindata |
| 826 |
|
| 827 |
Perinci::CmdLine will take care of encoding this data to network server when you |
| 828 |
specify C<riap_version> attribute to 1.2. So this process is transparent to you. |
| 829 |
|
| 830 |
When outputting binary result, in the C<text> output formats, Perinci::CmdLine |
| 831 |
will also print the binary result from server as-is without any newline added. |
| 832 |
So you can pipe binary data to files/processes unmodified. |
| 833 |
|
| 834 |
=head1 SUBCOMMANDS |
| 835 |
|
| 836 |
=head2 Default subcommand |
| 837 |
|
| 838 |
A default subcommand can be defined. This subcommand is selected without user |
| 839 |
specifying it the first command-line argument. A real-world example of this is |
| 840 |
from L<File::Trash::Undoable>. The B<trash-u> command is by default selecting |
| 841 |
the C<trash> subcommand: |
| 842 |
|
| 843 |
% trash-u file1 file2 |
| 844 |
|
| 845 |
is equivalent to: |
| 846 |
|
| 847 |
% trash-u --cmd trash file1 file2 |
| 848 |
|
| 849 |
To select another subcommand other than C<trash>, an explicit option is |
| 850 |
needed: |
| 851 |
|
| 852 |
% trash-u --list-contents ; # select the list_contents subcommand |
| 853 |
% trash-u --cmd empty ; # select the empty subcommand |
| 854 |
|
| 855 |
This is done via something like: |
| 856 |
|
| 857 |
Perinci::CmdLine->new( |
| 858 |
subcommands => { |
| 859 |
trash => { url=>... }, |
| 860 |
empty => { url=>... }, |
| 861 |
list_contents => { url=>... }, |
| 862 |
}, |
| 863 |
default_subcommand => 'trash', |
| 864 |
)->run; |
| 865 |
|
| 866 |
=head2 Default subcommand (override via first command-line argument) |
| 867 |
|
| 868 |
There is also a choice to specify a default subcommand which is overrideable via |
| 869 |
first command-line argument. A real-world example of this is from |
| 870 |
L<App::GitUtils>. If the B<gu> command is specified without any argument: |
| 871 |
|
| 872 |
% gu |
| 873 |
|
| 874 |
then it is equivalent to: |
| 875 |
|
| 876 |
% gu info |
| 877 |
|
| 878 |
but user can specify other subcommands: |
| 879 |
|
| 880 |
% gu post-commit |
| 881 |
|
| 882 |
This is accomplished by setting: |
| 883 |
|
| 884 |
Perinci::CmdLine::Any->new( |
| 885 |
subcommands => { |
| 886 |
info => {...}, |
| 887 |
run_hooks => {...}, |
| 888 |
post_commit => {...}, |
| 889 |
... |
| 890 |
}, |
| 891 |
default_subcommand => 'info', |
| 892 |
get_subcommand_from_arg => 2, |
| 893 |
)->run; |
| 894 |
|
| 895 |
=head2 Dynamic list of subcommands |
| 896 |
|
| 897 |
TODO |
| 898 |
|
| 899 |
=head1 HOMEPAGE |
| 900 |
|
| 901 |
Please visit the project's homepage at L<https://metacpan.org/release/Perinci-CmdLine>. |
| 902 |
|
| 903 |
=head1 SOURCE |
| 904 |
|
| 905 |
Source repository is at L<https://github.com/perlancar/perl-Perinci-CmdLine>. |
| 906 |
|
| 907 |
=head1 SEE ALSO |
| 908 |
|
| 909 |
L<Perinci::CmdLine::Manual> |
| 910 |
|
| 911 |
L<Perinci::Examples> |
| 912 |
|
| 913 |
=head1 AUTHOR |
| 914 |
|
| 915 |
perlancar <[email protected]> |
| 916 |
|
| 917 |
=head1 CONTRIBUTING |
| 918 |
|
| 919 |
|
| 920 |
To contribute, you can send patches by email/via RT, or send pull requests on |
| 921 |
GitHub. |
| 922 |
|
| 923 |
Most of the time, you don't need to build the distribution yourself. You can |
| 924 |
simply modify the code, then test via: |
| 925 |
|
| 926 |
% prove -l |
| 927 |
|
| 928 |
If you want to build the distribution (e.g. to try to install it locally on your |
| 929 |
system), you can install L<Dist::Zilla>, |
| 930 |
L<Dist::Zilla::PluginBundle::Author::PERLANCAR>, |
| 931 |
L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other |
| 932 |
Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond |
| 933 |
that are considered a bug and can be reported to me. |
| 934 |
|
| 935 |
=head1 COPYRIGHT AND LICENSE |
| 936 |
|
| 937 |
This software is copyright (c) 2026 by perlancar <[email protected]>. |
| 938 |
|
| 939 |
This is free software; you can redistribute it and/or modify it under |
| 940 |
the same terms as the Perl 5 programming language system itself. |
| 941 |
|
| 942 |
=head1 BUGS |
| 943 |
|
| 944 |
Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-CmdLine> |
| 945 |
|
| 946 |
When submitting a bug or request, please include a test-file or a |
| 947 |
patch to an existing test-file that illustrates the bug or desired |
| 948 |
feature. |
| 949 |
|
| 950 |
=cut |