view release on metacpan or  search on metacpan

docs/docs/10-tutorial-base.md  view on Meta::CPAN

   ...
      $child = path($config->{basedir})->child($type, $id);
   ...
   return $child;
} ## end sub resolve
```

## Complex sub-command

The "complex" sub-commands are actually very similar to the simple ones
described above, with the exception that they accept additional
command-line options.

As an example, let's consider command `add`, to track a new task:

```perl
# inside hash at $application->{commands}:
add => {
   help        => 'add a task',
   description => 'Add a task, optionally setting it as waiting',
   supports    => [qw< add new post >],
   options     => [
      {
         help   => 'add the tasks as waiting',
         getopt => 'waiting|w!'
      },
      {
         help   => 'set the editor for adding the task, if needed',
         getopt => 'editor|visual|e=s',
         environment => 'VISUAL',
         default     => 'vi',
      }
   ],
   execute => '#add',
},
```

Keys `help`, `description`, `supports`, and `execute` are exacty as
before.

Options are no surprise too: we already saw them in detail for the
`MAIN` entry point command. The difference here is that, by default,
options are taken from the command line, then the environment, then the
parent command, then the defaults; there is no loading of additional
options from files. This is also what the user expects, anyway.

Other sub-commands `list` and `edit` share the same structure.


## The dump outlier

The example `tudu` application also contains an *outlier* sub-command
`dump`, which is normally excluded from the children list (we would have
to set it explicitly in `MAIN`'s `children` in case).

```perl
# inside hash at $application->{commands}:
dump => { # this child is normally excluded!
   help => 'dump configuration',
   execute => sub ($m, $c, $a) {
      require Data::Dumper;
      warn Data::Dumper::Dumper({config => $c, args => $a});
      return 0;
   },
},
```

In this case we don't need to hand the execution over to `TuDu`, but can
provide it right off the bat with a `sub` reference. This gives us an
idea of how flexible we can be with the *executables*, ranging from
in-site implementation, to reference to other subs, up to putting stuff
in different packages and, possibly, different module files.

## Getting all pieces together

The whole program for our toy `tudu` application is the following,
including all the implementation functions placed in the `TuDu` package:

```
#!/usr/bin/env perl
use v5.24;
use warnings;
use experimental 'signatures';
no warnings 'experimental::signatures';
use App::Easer 'run';

my $application = {
   factory       => {prefixes => {'#' => 'TuDu#'}},
   configuration => {
      'auto-leaves'    => 1,
      'help-on-stderr' => 1,
   },
   commands => {
      MAIN => {
         help        => 'to-do application',
         description => 'A simple to-do application',
         options     => [
            {
               help        => 'path to the configuration file',
               getopt      => 'config|c=s',
               environment => 'TUDU_CONFIG',
            },
            {
               help        => 'base directory where tasks are kept',
               getopt      => 'basedir|dir|d=s',
               environment => 'TUDU_BASEDIR',
               default     => "$ENV{HOME}/.tudu",
            },
            {
               help   => 'max number of attempts to find non-colliding id',
               getopt => 'attempts|max-attempts|M=i',
               default => 9,
            },
         ],
         sources        => '+SourcesWithFiles',
         'config-files' => ["$ENV{HOME}/.tudu.conf", '/etc/tudu.conf'],
         commit         => '#ensure_basedir',
         children => [qw< list show cat add edit done wait resume remove >],
      },
      dump => { # this child is normally excluded!
         help => 'dump configuration',
         execute => sub ($m, $c, $a) {
            require Data::Dumper;
            warn Data::Dumper::Dumper({config => $c, args => $a});
            return 0;
         },
      },
      list => {
         help        => 'list tasks',
         description => 'Get full or partial list of tasks',
         supports    => [qw< list ls >],
         options     => [
            {
               help => 'include all tasks (including done) '
                 . '(exclusion is not honored)',
               getopt => 'all|A!',
            },
            {
               help => 'include(/exclude) all active tasks '
                 . '(ongoing and waiting)',
               getopt => 'active|a!',
            },
            {
               help   => 'include(/exclude) done tasks',
               getopt => 'done|d!',
            },
            {
               help   => 'include(/exclude) ongoing tasks',
               getopt => 'ongoing|o!',
            },
            {
               help   => 'include(/exclude) waiting tasks',
               getopt => 'waiting|w!',
            },
            {
               help   => 'use extended, unique identifiers',
               getopt => 'id|i!',
            },
            {
               help => 'limit up to n items for each category (0 -> inf)',
               getopt => 'n=i'
            },
         ],
         execute => '#list',
      },
      show => {
         help        => 'print one task',
         description => 'Print one whole task',
         supports    => [qw< show print get >],
         execute     => '#show',
      },
      cat => {
         help        => 'print one task (no delimiters)',
         description => 'Print one whole task, without adding delimiters',
         supports    => [qw< cat >],
         execute     => '#cat',
      },
      add => {
         help        => 'add a task',
         description => 'Add a task, optionally setting it as waiting',
         supports    => [qw< add new post >],
         options     => [
            {
               help   => 'add the tasks as waiting',