-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
1022 lines (909 loc) · 16.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Building Command-line Applications in Perl</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<script src="remark/remark.js" type="text/javascript">
{
"highlightStyle": "solarized_light",
"highlightLanguage": "no-highlight"
}
</script>
<style type="text/css" media="screen">
/*
SOLARIZED HEX 16/8 TERMCOL XTERM/HEX L*A*B RGB HSB
--------- ------- ---- ------- ----------- ---------- ----------- -----------
base03 #002b36 8/4 brblack 234 #1c1c1c 15 -12 -12 0 43 54 193 100 21
base02 #073642 0/4 black 235 #262626 20 -12 -12 7 54 66 192 90 26
base01 #586e75 10/7 brgreen 240 #585858 45 -07 -07 88 110 117 194 25 46
base00 #657b83 11/7 bryellow 241 #626262 50 -07 -07 101 123 131 195 23 51
base0 #839496 12/6 brblue 244 #808080 60 -06 -03 131 148 150 186 13 59
base1 #93a1a1 14/4 brcyan 245 #8a8a8a 65 -05 -02 147 161 161 180 9 63
base2 #eee8d5 7/7 white 254 #e4e4e4 92 -00 10 238 232 213 44 11 93
base3 #fdf6e3 15/7 brwhite 230 #ffffd7 97 00 10 253 246 227 44 10 99
yellow #b58900 3/3 yellow 136 #af8700 60 10 65 181 137 0 45 100 71
orange #cb4b16 9/3 brred 166 #d75f00 50 50 55 203 75 22 18 89 80
red #dc322f 1/1 red 160 #d70000 50 65 45 220 50 47 1 79 86
magenta #d33682 5/5 magenta 125 #af005f 50 65 -05 211 54 130 331 74 83
violet #6c71c4 13/5 brmagenta 61 #5f5faf 50 15 -45 108 113 196 237 45 77
blue #268bd2 4/4 blue 33 #0087ff 55 -10 -45 38 139 210 205 82 82
cyan #2aa198 6/6 cyan 37 #00afaf 60 -35 -05 42 161 152 175 74 63
green #859900 2/2 green 64 #5f8700 60 -20 65 133 153 0 68 100 60
*/
body {
font-size: 1.3em;
}
.slide .inverse {
color: #839496; /* base0 */
background-color: #002b36; /* base03 */
}
.slide {
color: #657b83; /* base00 */
background-color: #fdf6e3; /* base3 */
}
.slide pre, .slide code {
color: #586e75; /* base01 */
background-color: #eee8d5; /* base2 */
}
.slide .inverse pre, .slide .inverse code {
color: #93a1a1; /* base1 */
background-color: #073642; /* base02 */
}
a:link, a:visited, a:hover, a:active {
color: #268bd2; /* blue */
}
.footnote {
position: absolute;
bottom: 3em;
}
.footnote.right {
right: 3em;
}
.code {
font-family: Monaco, monospace;
}
</style>
</head>
<body>
<textarea id="source">
name: title
layout: true
class: center, middle, inverse
---
# Building Command-Line Apps
.footnote.right[[Chicago Perl Mongers](http://chicago.pm.org)]
---
layout: false
class: center, middle
# You're working with text
---
class: center, middle
layout: true
---
# You like the command-line
efficient and friendly
---
# You don't need a GUI
---
class: center, middle
# Shell scripts aren't strong enough
• poor scalability
• bytestreams aren't everything
---
class: center, middle
# Perl is an elegant solution
for a more civilized age
---
class: center, middle
# TIMTOWTDI
There Is More Than One Way To Do It
---
template: title
# Core Parts
---
# Input
• Arguments: `<argument>`
• Options: `[--option] [-h] [-R3]`
• Standard Input: `STDIN`
---
# Output
• Standard Output: `STDOUT`
• Standard Error: `STDERR`
• Exit Code: (0-255)
---
# User Documentation
---
# Code Organization
---
template: title
# Basic Scripts
---
layout: false
class: middle
.center[
# Start off right
]
```perl
use strict;
use warnings;
```
---
class: middle
.center[
# Arguments
## .code[@ARGV]
]
```perl
use strict;
use warnings;
use feature qw( say );
say "Hello, $ARGV[0]!";
```
```
$ perl greet.pl Chicago
Hello, Chicago!
```
---
class: middle
.center[
# Options
## .code[Getopt::Long]
]
```perl
use feature qw( say );
use Getopt::Long;
my %opt = (
greeting => 'Hello',
);
GetOptions( \%opt,
'greeting:s',
);
say "$opt{greeting}, $ARGV[0]!";
```
```
$ perl greet.pl Chicago
Hello, Chicago!
$ perl greet.pl --greeting Goodbye Cleveland
Goodbye, Cleveland!
```
---
class: middle
.center[
# Option Options
]
```perl
use Getopt::Long;
my %opt;
GetOptions( \%opt,
'boolean', # --boolean
'increment+', # --increment --increment --increment
'toggle!', # --toggle || --no-toggle
'required=s', # --required "Value"
'optional:s', # --optional "Value" || --optional
'multiple=s@', # --multiple "Foo" --multiple "Bar"
'pairs=s%', # --pairs foo=1 --pairs bar=1
'name|n', # --name || -n
);
```
---
class: center middle
# GetOptions edits @ARGV
Leaves what it doesn't know about: your arguments
---
class: middle center
---
class: middle
.center[
# Standard Input
]
```perl
use feature qw( say );
while ( my $line = <STDIN> ) {
my @emails = ( $line =~ /(\S+[@]\S+)/g );
say for @emails;
}
```
```
$ perl find_emails.pl < /var/spool/mail/victim
```
---
class: middle center
---
class: middle
.center[
# The Diamond Operator `<>`
Filenames in @ARGV, otherwise STDIN
]
```perl
use feature qw( say );
while ( my $line = <> ) {
my @emails = ( $line =~ /(\S+[@]\S+)/g );
say for @emails;
}
```
```
$ perl find_emails.pl < /var/spool/mail/victim
$ perl find_emails.pl /var/spool/mail/victim
```
---
class: middle
.center[
# Standard Output
]
```perl
use feature qw( say );
say 'Hello, World!';
```
```
$ perl hello.pl
Hello, World!
```
---
class: middle
.center[
# Standard Error
]
```perl
warn "Look out, World!"
die "I'm going down!\n"
```
```
$ perl warn.pl
Look out, World! at warn.pl line 2.
I'm going down!
```
---
class: middle
.center[
# STDOUT vs STDERR
]
```perl
use feature qw( say );
say "Hello, World!"
warn "Look out, World!"
die "I'm going down!\n"
```
```
$ perl stdouterr.pl 1>stdout.txt 2>stderr.txt
$ cat stdout.txt
Hello, World!
$ cat stderr.txt
Look out, World! at stdouterr.pl line 4.
I'm going down!
```
---
class: middle
.center[
# Exit Status
]
```
$ perl hello.pl
Hello, World!
$ echo $?
0
$ perl warn.pl
Look out, World! at warn.pl line 2.
I'm going down!
$ echo $?
255
```
---
class: middle
.center[
# 0 is good
Everything else is bad
]
```
$ perl hello.pl && perl warn.pl
Hello, World!
Look out, World! at warn.pl line 2.
I'm going down!
$ perl warn.pl && perl hello.pl
Look out, World! at warn.pl line 2.
I'm going down!
```
---
class: middle
.center[
# Choose your exit
]
```perl
use feature qw( say );
say "Exit code $ARGV[0]";
exit $ARGV[0];
```
```
$ perl exit.pl 0
Exit code 0
$ echo $?
0
$ perl exit.pl 1
Exit code 1
$ echo $?
1
```
---
class: center middle
# User Documentation
Pod::Usage
---
class: middle
.center[
# Plain Old Documentation
]
```
=head1 NAME
greet.pl - Say hello!
=head1 SYNOPSIS
perl greet.pl [--greeting <greeting>] <who>
=head1 ARGUMENTS
=head2 who
Who to greet. Defaults to "World"
=head1 OPTIONS
=head2 greeting
The greeting to use. Defaults to "Hello"
```
---
class: middle
.center[
# Read The Fine Manual
]
```
$ perldoc greet.pl
GREET(1) User Contributed Perl Documentation GREET(1)
NAME
greet.pl - Say hello!
SYNOPSIS
perl greet.pl [--greeting <greeting>] [<who>]
ARGUMENTS
who
Who to greet. Defaults to "World".
OPTIONS
greeting
The greeting to use. Defaults to "Hello".
perl v5.14.2 2013-05-23 GREET(1)
```
---
class: middle
.center[
# Help the User
Give them a `-h`and
]
```perl
use Getopt::Long;
use Pod::Usage;
my %opt;
GetOptions( \%opt,
'help|h',
);
pod2usage(0) if $opt{help};
```
```
$ perl greet.pl -h
Usage:
perl greet.pl [--greeting <greeting>] [<who>]
perl -h|--help
Arguments:
who:
Who to greet. Defaults to "World".
Options:
greeting:
The greeting to use. Defaults to "Hello".
help|h:
Display help and usage
```
---
class: middle
.center[
# Scold the User
Tell them what they did wrong
]
```perl
use Getopt::Long;
use Pod::Usage;
my %opt;
GetOptions( \%opt,
'help|h',
);
pod2usage(0) if $opt{help};
pod2usage("ERROR: Must give someone to greet") if !@ARGV;
```
```
$ perl greet.pl
ERROR: Must give someone to greet
Usage:
perl greet.pl [--greeting <greeting>] [<who>]
perl -h|--help
```
---
class: middle
.center[
# SHBANG!
]
```perl
#!/usr/bin/env perl
use feature qw( say );
say "Hello, World!";
```
```
$ ./hello.pl
bash: permission denied: ./hello.pl
$ chmod +x hello.pl
$ ./hello.pl
Hello, World!
```
---
class: middle
.center[
# Basic Script Boilerplate
]
```perl
#!/usr/bin/env perl
use strict;
use warnings;
use Getopt::Long;
use Pod::Usage;
my %opt;
GetOptions( \%opt,
'help|h',
);
pod2usage(0) if $opt{help};
### Put your code here
=head1 NAME
=head1 SYNOPSIS
=head1 ARGUMENTS
=head1 OPTIONS
=head1 EXIT CODES
=head1 LICENSE AND COPYRIGHT
```
---
template: title
# Modulinos
Scripts as Modules
---
class: center middle
# Code Organization
---
class: center middle
# Reusable Components
---
class: center middle
# Testable Scripts
---
class: middle
.center[
# .code[int main(argv)]
]
```perl
package modulino;
sub main {
my ( $argv ) = @_;
### Put your code here
return 0;
}
exit main( \@ARGV );
```
```
$ perl modulino.pm
$ ./modulino.pm
```
---
class: middle
.center[
# Add the options
]
```perl
use Getopt::Long qw( GetOptionsFromArray );
sub main {
my ( $argv ) = @_;
my %opt;
GetOptionsFromArray( $argv, \%opt,
'help|h',
);
### Put your code here
return 0;
}
exit main( \@ARGV );
```
---
class: middle
.center[
# Use as a Module
]
```perl
exit main( \@ARGV ) if !caller(0);
```
---
class: middle
.center[
# The Greeting Modulino
]
```perl
#!/usr/bin/env perl
package greet;
use strict;
use warnings;
use feature qw( say );
use Getopt::Long qw( GetOptionsFromArray );
use Pod::Usage;
sub main {
my ( $argv ) = @_;
my %opt;
GetOptionsFromArray( $argv, \%opt,
'greeting:s',
'help|h',
);
pod2usage(0) if $opt{help};
pod2usage("ERROR: Must give someone to greet") if !@{$argv};
$opt{greeting} ||= "Hello";
say "$opt{greeting}, $argv->[0]!";
return 0;
}
exit main( \@ARGV ) if !caller(0);
1; # <module>.pm did not return a true value
```
---
class: middle
.center[
# Run the Modulino
]
```
$ perl greet.pm --greeting "Good Morning" "St. Louis"
Good Morning, St. Louis!
$ chmod +x greet.pm
$ ./greet.pm Chicago.PM
Hello, Chicago.PM
```
---
class: middle
.center[
# Test the Modulino
]
```perl
use Test::More;
use Capture::Tiny qw( capture );
use greet;
my ( $stdout, $stderr, $exit ) = capture {
greet::main( [ "Chicago.PM" ] );
};
is $stdout, "Hello, Chicago.PM!\n", 'correct greeting';
is $exit, 0, 'exit code: success';
done_testing;
```
```
$ prove -v greet.t
greet.t ..
ok 1 - correct greeting
ok 2 - exit code: success
1..2
ok
All tests successful.
Files=1, Tests=2, 0 wallclock secs (...)
Result: PASS
```
---
class: middle center
# Add more methods
.code[Sub::Exporter]
---
class: middle center
# Inheritance
---
class: middle
.center[
# Modulino Boilerplate
]
```perl
#!/usr/bin/env perl
package modulino;
use strict;
use warnings;
use Getopt::Long qw( GetOptionsFromArray );
use Pod::Usage;
sub main {
my ( $argv ) = @_;
my %opt;
GetOptionsFromArray( $argv, \%opt,
### Your options here
'help|h',
);
pod2usage(0) if $opt{help};
### Your code here
return 0;
}
exit main( \@ARGV ) if ( !caller(0) );
1;
=head1 NAME
=head1 SYNOPSIS
=head1 ARGUMENTS
=head1 OPTIONS
=head1 LICENSE AND COPYRIGHT
```
---
template: title
# MooseX::Runnable
Moose-based Modulino
---
class: center middle
# Existing Module
.code[My::Module]
---
class: center middle
# Runnable Modulino
.code[mx-run My::Module]
---
class: middle
.center[
# Hello.pm
]
```perl
package Runnable::Hello;
use feature qw( say );
use Moose;
with 'MooseX::Runnable';
sub run {
my ( $self ) = @_;
say "Hello, World!";
return 0;
}
1;
```
```
$ mx-run Runnable::Hello
Hello, World!
```
---
class: center middle
# Run From Anywhere
.code[@INC $ENV{PERL5LIB}]
---
class: middle
.center[
# Arguments
]
```perl
package Runnable::Greet;
use feature qw( say );
use Moose;
with 'MooseX::Runnable';
sub run {
my ( $self, $who ) = @_;
say "Hello, $who!";
return 0;
}
1;
```
```
$ mx-run Runnable::Greet Chicago.PM
Hello, Chicago.PM!
```
---
class: middle
.center[
# Show usage instructions
]
```perl
sub run {
my ( $self, $who ) = @_;
die "Must give someone to greet!\n\n" . $self->usage unless $who;
say "Hello, $who!";
return 0;
}
1;
```
```
$ mx-run Runnable::Greet
Must give someone to greet!
usage: mx-run [-?h] [long options...]
-h -? --usage --help Prints this usage information.
--greeting
```
---
class: middle
.center[
# Options
.code[MooseX::Getopt]
]
```perl
package Runnable::Greet;
use feature qw( say );
use Moose;
with 'MooseX::Runnable', 'MooseX::Getopt';
has greeting => (
is => 'ro',
isa => 'Str',
default => 'Hello',
);
sub run {
my ( $self, $who ) = @_;
die "Must give someone to greet!\n\n" . $self->usage unless $who;
say $self->greeting . ", $who!";
return 0;
}
1;
```
```
$ mx-run Runnable::Greet --greeting Bonjour Chicago.PM
Bonjour, Chicago.PM!
```
---
class: middle center
# Caution: Two in One!
Command-line and Object APIs can conflict
---
class: middle
.center[
# Avoiding Conflict
`MooseX::Getopt` ignores _attr and NoGetopt attributes
]
```perl
has _private => ( ... ); # cannot be set from command-line
has more_private => (
traits => [qw( NoGetopt )],
);
```
---
class: middle center
# Attributes and Documentation overlap
We're pragmatists, not purists
---
template: title
# App::Cmd
Framework for large apps
---
class: middle
.center[
## A digression
]
```
$ git help
usage: git [--version] [--exec-path[=<path>]] [--html-path] [--man-path]
[--info-path]
[-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
[-c name=value] [--help]
<command> [<args>]
The most commonly used git commands are:
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
commit Record changes to the repository
diff Show changes between commits, commit and working tree, etc
init Create an empty git repository or reinitialize an existing one
log Show commit logs
merge Join two or more development histories together
pull Fetch from and merge with another repository or a local branch
push Update remote refs along with associated objects
rebase Forward-port local commits to the updated upstream head
reset Reset current HEAD to the specified state
rm Remove files from the working tree and from the index
status Show the working tree status
tag Create, list, delete or verify a tag object signed with GPG
See 'git help <command>' for more information on a specific command.
```
---
class: middle center
# App::Cmd Framework
Manages Complexity
---
class: middle center
# Command Modules
Each module, a command
---
class: middle
.center[
# 1: Application Module
]
The entry point
```perl
package App::Say;
use App::Cmd::Setup -app;
1;
```
---
class: middle
.center[
# 2: Command Module
]
```perl
package App::Say::Command::hello;
use feature qw( say );
use App::Cmd::Setup -command;
sub execute {
my ( $self, $opt, $args ) = @_;
say "Hello, World!";
return 0;
}
1;
```
---
class: middle
.center[
# 3: The Runner Script
]
```perl
#!/usr/bin/env perl
use App::Say;
App::Say->run;
```
```
$ perl say.pl hello
Hello, World!
```
---
class: middle
.center[
# Arguments
]
```perl
package App::Say::Command::greet;
use feature qw( say );
use App::Cmd::Setup -command;
sub execute {
my ( $self, $opt, $args ) = @_;
say "Hello, $args->[0]";
return 0;
};
1;
```
```
$ perl say.pl greet Chicago.PM
Hello, Chicago.PM
```
---
class: middle
.center[
# Options
]
```perl
package App::Say::Command::greet;
use feature qw( say );
use App::Cmd::Setup -command;
sub opt_spec {
return (
[ 'greeting:s' => 'A greeting. Defaults to "Hello"' ],
)
}
sub execute {
my ( $self, $opt, $args ) = @_;
$opt->{greeting} ||= "Hello";
say "$opt->{greeting}, $args->[0]";
return 0;
};
1;
```
```
$ perl say.pl greet --greeting Bonjour Chicago.PM
Bonjour, Chicago.PM
```
---
template: title
# What Next?
---
class: center middle
# Read The Fine Manual
• Getopt::Long
• Pod::Usage