Debian Codegraph @

lib/Perinci/CmdLine/Manual/HowTo/99Examples.pod

raw
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