Writing Maintainable Commands with App::Cmd

It's easy to write command-line programs in Perl. There are a million option parsers to choose from, and Perl makes it easy to deal with input, output, and all that stuff.

Once your program has gotten beyond just taking a few switches, though, it can be difficult to maintain a clear interface and well-tested code. App::Cmd is a lightweight framework for writing easy to manage CLI programs.

This talk provides an introduction to writing programs with App::Cmd.

Transcript

1. App::Cmd Writing Maintainable Commands
2. TMTOWTDI
3. There’s More Than One Way To Do It
4. Web
5. Web •Mason
6. Web •Mason •Catalyst
7. Web •Mason •Catalyst •CGI::Application
8. Web •Mason •Catalyst •CGI::Application •Maypole
9. Web •Mason •Catalyst •CGI::Application •Maypole •Continuity
10. Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp
11. Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry
12. Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry •Tripletail
13. Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry •Tripletail •CGI::ExApp
14. Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry •Tripletail •CGI::ExApp •OpenInteract
15. Daemons
16. Daemons •POE
17. Daemons •POE •Danga
18. Daemons •POE •Danga •Net::Server
19. Daemons •POE •Danga •Net::Server •Daemon::Generic
20. Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon
21. Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon •Net::Daemon
22. Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon •Net::Daemon •MooseX::Daemonize
23. Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon •Net::Daemon •MooseX::Daemonize •Event
24. TMTOWTDI
25. TMTOWTDI •All the big problem sets have a few solutions!
26. TMTOWTDI •All the big problem sets have a few solutions! •So, when I needed to write a CLI app, I checked CPAN...
27. Command-Line Apps
28. Command-Line Apps •App::CLI
29. Command-Line Apps
30. Command-Line Apps :-(
31. Everybody writes command-line apps!
32. Why are there no good tools?
33. Second-Class Citizens
34. Second-Class Citizens •That’s how we view them.
35. Second-Class Citizens •That’s how we view them. •They’re
36. Second-Class Citizens •That’s how we view them. •They’re •hard to test
37. Second-Class Citizens •That’s how we view them. •They’re •hard to test •not reusable components
38. Second-Class Citizens •That’s how we view them. •They’re •hard to test •not reusable components •hard to add more behavior later
39. Here’s an Example
40. Example Script $ sink 30min “server mx-pa-1 crashed!”
41. Example Script $ sink --list who | time | event ------+-------+---------------------------- rjbs | 30min | server mx-pa-1 crashed!
42. Example Script
43. Example Script GetOptions(\%opt, ...);
44. Example Script GetOptions(\%opt, ...);
45. Example Script GetOptions(\%opt, ...); if ($opt{list}) {
46. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV;
47. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all;
48. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events);
49. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events); } else {
50. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events); } else { my ($duration, $desc) = @ARGV;
51. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events); } else { my ($duration, $desc) = @ARGV; Event->new($duration, $desc);
52. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events); } else { my ($duration, $desc) = @ARGV; Event->new($duration, $desc); }
53. Example Script $ sink --list --user jcap who | time | event ------+-------+---------------------------- jcap | 2hr | redeploy exigency subsystem
54. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = $opt{user} ? Events->get(user => $opt{user}) : Events->get_all; print_events(@events); } else { my ($duration, $desc) = @ARGV; Event->new($duration, $desc); }
55. Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = $opt{user} ? Events->get(user => $opt{user}) : Events->get_all; print_events(@events); } else { my ($duration, $desc) = @ARGV; die if $opt{user}; Event->new($duration, $desc); }
56. Example Script $ sink --start ‘putting out oil fire‘ Event begun! use --finish to finish event $ sink --list --open 18. putting out oil fire $ sink --finish 18 Event finished! Total time taken: 23 min
57. Insult to Injury
58. Insult to Injury •...well, that’s going to take a lot of testing.
59. Insult to Injury •...well, that’s going to take a lot of testing. •How can we test it?
60. Insult to Injury •...well, that’s going to take a lot of testing. •How can we test it? •my $output = `sink @args`;
61. Insult to Injury •...well, that’s going to take a lot of testing. •How can we test it? •my $output = `sink @args`; •IPC::Run3 (or one of those)
62. Here’s a Solution
63. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’
64. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ App
65. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Command
66. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Options
67. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Args
68. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’
69. “do” command
70. “do” command sub run {
71. “do” command sub run { my ($self, $opt, $args) = @_;
72. “do” command sub run { my ($self, $opt, $args) = @_;
73. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago});
74. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for});
75. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0];
76. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0];
77. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create(
78. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start,
79. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length,
80. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc;
81. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc; );
82. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc; );
83. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc; ); print “event created!”;
84. “do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc; ); print “event created!”; }
85. “do” command
86. “do” command sub opt_desc {
87. “do” command sub opt_desc { [ “start=s”, “when you started doing this” ],
88. “do” command sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”,
89. “do” command sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”, { required => 1} ],
90. “do” command sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”, { required => 1} ], }
91. “do” command
92. “do” command sub validate_args {
93. “do” command sub validate_args { my ($self, $opt, $args) = @_;
94. “do” command sub validate_args { my ($self, $opt, $args) = @_;
95. “do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) {
96. “do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”);
97. “do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”); }
98. “do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”); } }
99. package Sink::Command::Do; use base ‘App::Cmd::Command’; sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”, { required => 1} ], } sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”); } } sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc; ); print “event created!”; } 1;
100. package Sink::Command::Do; use base ‘App::Cmd::Command’; sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”, { required => 1} ], } sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”); } } sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0]; Sink::Event->create( start => $start, finish => $start + $length, desc => $desc; ); print “event created!”; } 1;
101. Extra Scaffolding
102. Extra Scaffolding package Sink;
103. Extra Scaffolding package Sink; use base ‘App::Cmd’;
104. Extra Scaffolding package Sink; use base ‘App::Cmd’; 1;
105. Extra Scaffolding use Sink; Sink->run;
106. Testing Your App
107. Testing App::Cmd
108. Testing App::Cmd use Test::More tests => 3;
109. Testing App::Cmd use Test::More tests => 3; use Test::Output;
110. Testing App::Cmd use Test::More tests => 3; use Test::Output;
111. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error;
112. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do {
113. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’);
114. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub {
115. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@;
116. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@; });
117. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@; }); }
118. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@; }); }
119. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@; }); } like $stdout, qr/^event created!$/;
120. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@; }); } like $stdout, qr/^event created!$/; is Sink::Event->get_count, 1;
121. Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’); stdout_from(sub { eval { Sink->run; 1 } or $error = $@; }); } like $stdout, qr/^event created!$/; is Sink::Event->get_count, 1; ok ! $error;
122. Testing App::Cmd use Test::More tests => 3; use Test::App::Cmd; use Sink; my ($stdout, $error) = test_app( Sink => qw(do --for 8hr ‘sleeping’) ); like $stdout, qr/^event created!$/; is Sink::Event->get_count, 1; ok ! $error;
123. Testing App::Cmd use Test::More tests => π; use Sink::Command::Do; eval { Sink::Command::Do->validate_args( { for => ‘1hr’ }, [ 1, 2, 3 ], ); }; like $@, qr/one arg/;
124. Growing Your App
125. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’
126. Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Command
127. package Sink::Command::List; use base ‘App::Cmd::Command’; sub opt_desc { ... } sub validate_args { ... } sub run { ... } 1;
128. package Sink::Command::List; use base ‘App::Cmd::Command’; sub opt_desc { [ “open”, “only unfinished events” ], [ “user|u=s”, “only events for this user” ], } sub validate_args { shift->usage_error(’no args allowed’) if @{ $_[1] } } sub run { ... } 1;
129. package Sink::Command::Start; use base ‘App::Cmd::Command’; sub opt_desc { ... } sub validate_args { ... } sub run { ... } 1;
130. package Sink::Command::Start; use base ‘App::Cmd::Command’; sub opt_desc { return } sub validate_args { shift->usage_error(’one args required’) if @{ $_[1] } != 1 } sub run { ... } 1;
131. More Commands! $ sink do --for 1hr --ago 1d ‘rebuild raid’ $ sink list --open $ sink start ‘porting PHP to ASP.NET’
132. More Commands! $ sink sink help <command> Available commands: commands: list the application’s commands help: display a command’s help screen do: (unknown) list: (unknown) start: (unknown)
133. Command Listing package Sink::Command::Start; =head1 NAME Sink::Command::Start - start a new task =cut
134. Command Listing package Sink::Command::Start; sub abstract { ‘start a new task’; }
135. Command Listing $ sink commands Available commands: commands: list the application’s commands help: display a command’s help screen do: record that you did something list: list existing events start: start a new task
136. Command Listing
137. Command Listing $ sink help list
138. Command Listing $ sink help list
139. Command Listing $ sink help list sink list [long options...]
140. Command Listing $ sink help list sink list [long options...] -u --user only events for this user
141. Command Listing $ sink help list sink list [long options...] -u --user only events for this user --open only unfinished events
142. Core Commands
143. Core Commands •Where did “help” and “commands” come from?
144. Core Commands •Where did “help” and “commands” come from? •App::Cmd::Command::help
145. Core Commands •Where did “help” and “commands” come from? •App::Cmd::Command::help •App::Cmd::Command::commands
146. Default Command package Sink; use base ‘App::Cmd’; 1;
147. Default Command package Sink; use base ‘App::Cmd’; sub default_command { ‘help’ } 1;
148. Default Command package Sink; use base ‘App::Cmd’; sub default_command { ‘list’ } 1;
149. One-Command Applications
150. Simple Example $ ckmail check -a work -a home No new mail.
151. Simple Example $ ckmail -a work -a home No new mail.
152. The Lousy Way
153. The Lousy Way •create Ckmail::Command::Check
154. The Lousy Way •create Ckmail::Command::Check •make empty Ckmail.pm
155. The Lousy Way •create Ckmail::Command::Check •make empty Ckmail.pm •make “check” the default command
156. The Simple Way package Ckmail::Command::Check; use base ‘App::Cmd::Command’; sub opt_desc { ... } sub run { ... } 1;
157. The Simple Way package Ckmail::Command::Check; use base ‘App::Cmd::Simple’; sub opt_desc { ... } sub run { ... } 1;
158. The Simple Way use Ckmail; Ckmail->run;
159. The Simple Way use Ckmail::Command::Check; Ckmail::Command::Check->run;
160. App::Cmd::Simple
161. App::Cmd::Simple •You write a command...
162. App::Cmd::Simple •You write a command... •...but you use it like an App::Cmd.
163. App::Cmd::Simple •You write a command... •...but you use it like an App::Cmd. •Later, you can just demote it.
164. Any Questions?
165. Thank You!