NAME

MooX::Commander - Build command line apps with subcommands and option parsing

SYNOPSIS

    # EXAMPLE
    # MooX::Commander helps you build a command line app like this:
    $ bin/pie-factory --help
    usage: pie-factory [options]

    You have inherited a pie factory.  Use your powers wisely.
    
    COMMANDS
    pie-factory recipe list             List pie recipes
    pie-factory recipe show <recipe>    Display a recipe
    pie-factory recipe add <recipe>     Add a recipe
    pie-factory recipe delete <recipe>  Delete a recipe
    pie-factory bake <pie>              Bake a pie
    pie-factory eat <pie>               Eat a pie
    pie-factory throw <pie> <target>    Throw a pie at something
    pie-factory help <cmd>              Get help with a command

    OPTIONS
      -v, --version  Show version
      -h, --help     Show this message

    
    # HOW TO DISPATCH TO COMMAND CLASSES
    # inside bin/pie-factory:
    my $commander = MooX::Commander->new(
        base_class   => 'PieFactory',
        class_prefix => 'Cmd',  # optional, default value is 'Cmd'
        version      => 'v1.0', # optional. default lazy loads $PieFactory::VERSION
    );
    $commander->dispatch(argv => \@ARGV);

    # HOW TO BUILD A COMMAND CLASS
    # inside lib/PieFactory/Cmd/Throw.pm
    package PieFactory::Cmd::Throw;
    sub go {
        my ($self, $pie, $target) = @_;
        # throw $pie at the $target
    }

    # HOW TO ADD OPTION PARSING TO A COMMAND CLASS
    # See L<MooX::Command::HasOptions>

    # HOW TO BUILD A HELP SUBCOMMAND
    # See L<MooX::Command::IsaHelpCommand>

    # HOW TO BUILD A SUBSUBCOMMAND
    # See L<MooX::Command::HasSubcommands>

DESCRIPTION

MooX::Commander makes it easy to add commands and option parsing to your command line application a la git.

This module instantiates the command class requested by the user and calls the go() method on the object. @ARGV is passed to the command class and saved in the argv attribute.

If a user passes in no args or --help or -h the help command class is instantiated and the usage() method is called on that object.

WHAT THIS MODULE DOES NOT DO

This module doesn't dynamically generate usage/help statements. I wasn't interested in solving that problem. I think its not possible or very difficult to do well and usually leads to a very complex and verbose user interface and a one size fits all usage/help output that is inflexible and poorly formatted.

I also suspect people who really care about the usability of their command line applications want to tweak help output based on the situation and their personal preferences. Or maybe thats just me.

LICENSE

Copyright (C) Eric Johnson.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Eric Johnson <eric.git@iijo.org>