Writing Maintainable Commands with App::Cmd

Slide 1

Slide 1 text

App::Cmd Writing Maintainable Commands

Slide 2

Slide 2 text

TMTOWTDI

Slide 3

Slide 3 text

There’s More Than One Way To Do It

Slide 4

Slide 4 text

Web

Slide 5

Slide 5 text

Web •Mason

Slide 6

Slide 6 text

Web •Mason •Catalyst

Slide 7

Slide 7 text

Web •Mason •Catalyst •CGI::Application

Slide 8

Slide 8 text

Web •Mason •Catalyst •CGI::Application •Maypole

Slide 9

Slide 9 text

Web •Mason •Catalyst •CGI::Application •Maypole •Continuity

Slide 10

Slide 10 text

Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp

Slide 11

Slide 11 text

Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry

Slide 12

Slide 12 text

Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry •Tripletail

Slide 13

Slide 13 text

Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry •Tripletail •CGI::ExApp

Slide 14

Slide 14 text

Web •Mason •Catalyst •CGI::Application •Maypole •Continuity •RayApp •Gantry •Tripletail •CGI::ExApp •OpenInteract

Slide 15

Slide 15 text

Daemons

Slide 16

Slide 16 text

Daemons •POE

Slide 17

Slide 17 text

Daemons •POE •Danga

Slide 18

Slide 18 text

Daemons •POE •Danga •Net::Server

Slide 19

Slide 19 text

Daemons •POE •Danga •Net::Server •Daemon::Generic

Slide 20

Slide 20 text

Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon

Slide 21

Slide 21 text

Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon •Net::Daemon

Slide 22

Slide 22 text

Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon •Net::Daemon •MooseX::Daemonize

Slide 23

Slide 23 text

Daemons •POE •Danga •Net::Server •Daemon::Generic •Proc::Daemon •Net::Daemon •MooseX::Daemonize •Event

Slide 24

Slide 24 text

TMTOWTDI

Slide 25

Slide 25 text

TMTOWTDI •All the big problem sets have a few solutions!

Slide 26

Slide 26 text

TMTOWTDI •All the big problem sets have a few solutions! •So, when I needed to write a CLI app, I checked CPAN...

Slide 27

Slide 27 text

Command-Line Apps

Slide 28

Slide 28 text

Command-Line Apps •App::CLI

Slide 29

Slide 29 text

Command-Line Apps

Slide 30

Slide 30 text

Command-Line Apps :-(

Slide 31

Slide 31 text

Everybody writes command-line apps!

Slide 32

Slide 32 text

Why are there no good tools?

Slide 33

Slide 33 text

Second-Class Citizens

Slide 34

Slide 34 text

Second-Class Citizens •That’s how we view them.

Slide 35

Slide 35 text

Second-Class Citizens •That’s how we view them. •They’re

Slide 36

Slide 36 text

Second-Class Citizens •That’s how we view them. •They’re •hard to test

Slide 37

Slide 37 text

Second-Class Citizens •That’s how we view them. •They’re •hard to test •not reusable components

Slide 38

Slide 38 text

Second-Class Citizens •That’s how we view them. •They’re •hard to test •not reusable components •hard to add more behavior later

Slide 39

Slide 39 text

Here’s an Example

Slide 40

Slide 40 text

Example Script $ sink 30min “server mx-pa-1 crashed!”

Slide 41

Slide 41 text

Example Script $ sink --list who | time | event ------+-------+---------------------------- rjbs | 30min | server mx-pa-1 crashed!

Slide 42

Slide 42 text

Example Script

Slide 43

Slide 43 text

Example Script GetOptions(\%opt, ...);

Slide 44

Slide 44 text

Example Script GetOptions(\%opt, ...);

Slide 45

Slide 45 text

Example Script GetOptions(\%opt, ...); if ($opt{list}) {

Slide 46

Slide 46 text

Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV;

Slide 47

Slide 47 text

Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all;

Slide 48

Slide 48 text

Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events);

Slide 49

Slide 49 text

Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events); } else {

Slide 50

Slide 50 text

Example Script GetOptions(\%opt, ...); if ($opt{list}) { die if @ARGV; @events = Events->get_all; print_events(@events); } else { my ($duration, $desc) = @ARGV;

Slide 51

Slide 51 text

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);

Slide 52

Slide 52 text

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); }

Slide 53

Slide 53 text

Example Script $ sink --list --user jcap who | time | event ------+-------+---------------------------- jcap | 2hr | redeploy exigency subsystem

Slide 54

Slide 54 text

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); }

Slide 55

Slide 55 text

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

Insult to Injury

Slide 58

Slide 58 text

Insult to Injury •...well, that’s going to take a lot of testing.

Slide 59

Slide 59 text

Insult to Injury •...well, that’s going to take a lot of testing. •How can we test it?

Slide 60

Slide 60 text

Insult to Injury •...well, that’s going to take a lot of testing. •How can we test it? •my $output = `sink @args`;

Slide 61

Slide 61 text

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)

Slide 62

Slide 62 text

Here’s a Solution

Slide 63

Slide 63 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’

Slide 64

Slide 64 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ App

Slide 65

Slide 65 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Command

Slide 66

Slide 66 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Options

Slide 67

Slide 67 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Args

Slide 68

Slide 68 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’

Slide 69

Slide 69 text

“do” command

Slide 70

Slide 70 text

“do” command sub run {

Slide 71

Slide 71 text

“do” command sub run { my ($self, $opt, $args) = @_;

Slide 72

Slide 72 text

“do” command sub run { my ($self, $opt, $args) = @_;

Slide 73

Slide 73 text

“do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago});

Slide 74

Slide 74 text

“do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for});

Slide 75

Slide 75 text

“do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0];

Slide 76

Slide 76 text

“do” command sub run { my ($self, $opt, $args) = @_; my $start = parse_ago($opt->{ago}); my $length = parse_duration($opt->{for}); my $desc = $args->[0];

Slide 77

Slide 77 text

“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(

Slide 78

Slide 78 text

“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,

Slide 79

Slide 79 text

“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,

Slide 80

Slide 80 text

Slide 81

Slide 81 text

Slide 82

Slide 82 text

Slide 83

Slide 83 text

Slide 84

Slide 84 text

Slide 85

Slide 85 text

“do” command

Slide 86

Slide 86 text

“do” command sub opt_desc {

Slide 87

Slide 87 text

“do” command sub opt_desc { [ “start=s”, “when you started doing this” ],

Slide 88

Slide 88 text

“do” command sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”,

Slide 89

Slide 89 text

“do” command sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”, { required => 1} ],

Slide 90

Slide 90 text

“do” command sub opt_desc { [ “start=s”, “when you started doing this” ], [ “for=s”, “how long you did this for”, { required => 1} ], }

Slide 91

Slide 91 text

“do” command

Slide 92

Slide 92 text

“do” command sub validate_args {

Slide 93

Slide 93 text

“do” command sub validate_args { my ($self, $opt, $args) = @_;

Slide 94

Slide 94 text

“do” command sub validate_args { my ($self, $opt, $args) = @_;

Slide 95

Slide 95 text

“do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) {

Slide 96

Slide 96 text

“do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”);

Slide 97

Slide 97 text

“do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”); }

Slide 98

Slide 98 text

“do” command sub validate_args { my ($self, $opt, $args) = @_; if (@$args != 1) { $self->usage_error(“provide one argument”); } }

Slide 99

Slide 99 text

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;

Slide 100

Slide 100 text

Slide 101

Slide 101 text

Extra Scaffolding

Slide 102

Slide 102 text

Extra Scaffolding package Sink;

Slide 103

Slide 103 text

Extra Scaffolding package Sink; use base ‘App::Cmd’;

Slide 104

Slide 104 text

Extra Scaffolding package Sink; use base ‘App::Cmd’; 1;

Slide 105

Slide 105 text

Extra Scaffolding use Sink; Sink->run;

Slide 106

Slide 106 text

Testing Your App

Slide 107

Slide 107 text

Testing App::Cmd

Slide 108

Slide 108 text

Testing App::Cmd use Test::More tests => 3;

Slide 109

Slide 109 text

Testing App::Cmd use Test::More tests => 3; use Test::Output;

Slide 110

Slide 110 text

Testing App::Cmd use Test::More tests => 3; use Test::Output;

Slide 111

Slide 111 text

Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error;

Slide 112

Slide 112 text

Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do {

Slide 113

Slide 113 text

Testing App::Cmd use Test::More tests => 3; use Test::Output; my $error; my $stdout = do { local @ARGV = qw(do --for 8hr ‘sleeping’);

Slide 114

Slide 114 text

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 {

Slide 115

Slide 115 text

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 = $@;

Slide 116

Slide 116 text

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 = $@; });

Slide 117

Slide 117 text

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 = $@; }); }

Slide 118

Slide 118 text

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 = $@; }); }

Slide 119

Slide 119 text

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!$/;

Slide 120

Slide 120 text

Slide 121

Slide 121 text

Slide 122

Slide 122 text

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;

Slide 123

Slide 123 text

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/;

Slide 124

Slide 124 text

Growing Your App

Slide 125

Slide 125 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’

Slide 126

Slide 126 text

Command Breakdown $ sink do --for 1hr --ago 1d ‘rebuild raid’ Command

Slide 127

Slide 127 text

package Sink::Command::List; use base ‘App::Cmd::Command’; sub opt_desc { ... } sub validate_args { ... } sub run { ... } 1;

Slide 128

Slide 128 text

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;

Slide 129

Slide 129 text

package Sink::Command::Start; use base ‘App::Cmd::Command’; sub opt_desc { ... } sub validate_args { ... } sub run { ... } 1;

Slide 130

Slide 130 text

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;

Slide 131

Slide 131 text

More Commands! $ sink do --for 1hr --ago 1d ‘rebuild raid’ $ sink list --open $ sink start ‘porting PHP to ASP.NET’

Slide 132

Slide 132 text

More Commands! $ sink sink help Available commands: commands: list the application’s commands help: display a command’s help screen do: (unknown) list: (unknown) start: (unknown)

Slide 133

Slide 133 text

Command Listing package Sink::Command::Start; =head1 NAME Sink::Command::Start - start a new task =cut

Slide 134

Slide 134 text

Command Listing package Sink::Command::Start; sub abstract { ‘start a new task’; }

Slide 135

Slide 135 text

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

Slide 136

Slide 136 text

Command Listing

Slide 137

Slide 137 text

Command Listing $ sink help list

Slide 138

Slide 138 text

Command Listing $ sink help list

Slide 139

Slide 139 text

Command Listing $ sink help list sink list [long options...]

Slide 140

Slide 140 text

Command Listing $ sink help list sink list [long options...] -u --user only events for this user

Slide 141

Slide 141 text

Command Listing $ sink help list sink list [long options...] -u --user only events for this user --open only unfinished events

Slide 142

Slide 142 text

Core Commands

Slide 143

Slide 143 text

Core Commands •Where did “help” and “commands” come from?

Slide 144

Slide 144 text

Core Commands •Where did “help” and “commands” come from? •App::Cmd::Command::help

Slide 145

Slide 145 text

Core Commands •Where did “help” and “commands” come from? •App::Cmd::Command::help •App::Cmd::Command::commands

Slide 146

Slide 146 text

Default Command package Sink; use base ‘App::Cmd’; 1;

Slide 147

Slide 147 text

Default Command package Sink; use base ‘App::Cmd’; sub default_command { ‘help’ } 1;

Slide 148

Slide 148 text

Default Command package Sink; use base ‘App::Cmd’; sub default_command { ‘list’ } 1;

Slide 149

Slide 149 text

One-Command Applications

Slide 150

Slide 150 text

Simple Example $ ckmail check -a work -a home No new mail.

Slide 151

Slide 151 text

Simple Example $ ckmail -a work -a home No new mail.

Slide 152

Slide 152 text

The Lousy Way

Slide 153

Slide 153 text

The Lousy Way •create Ckmail::Command::Check

Slide 154

Slide 154 text

The Lousy Way •create Ckmail::Command::Check •make empty Ckmail.pm

Slide 155

Slide 155 text

The Lousy Way •create Ckmail::Command::Check •make empty Ckmail.pm •make “check” the default command

Slide 156

Slide 156 text

The Simple Way package Ckmail::Command::Check; use base ‘App::Cmd::Command’; sub opt_desc { ... } sub run { ... } 1;

Slide 157

Slide 157 text

The Simple Way package Ckmail::Command::Check; use base ‘App::Cmd::Simple’; sub opt_desc { ... } sub run { ... } 1;

Slide 158

Slide 158 text

The Simple Way use Ckmail; Ckmail->run;

Slide 159

Slide 159 text

The Simple Way use Ckmail::Command::Check; Ckmail::Command::Check->run;

Slide 160

Slide 160 text

App::Cmd::Simple

Slide 161

Slide 161 text

App::Cmd::Simple •You write a command...

Slide 162

Slide 162 text

App::Cmd::Simple •You write a command... •...but you use it like an App::Cmd.

Slide 163

Slide 163 text

App::Cmd::Simple •You write a command... •...but you use it like an App::Cmd. •Later, you can just demote it.