NAME

CLI::Dispatch::Help - show help

SYNOPSIS

  to list available commands:

    > perl your_script.pl

  to show help of a specific command:

    > perl your_script.pl help command

  you may want to encode/decode the text:

    > perl your_script.pl command --help --from=utf-8 --to=shift_jis

DESCRIPTION

This command is used to show help, and expects the first section of the pod of each command to be a NAME (or equivalent) section with a class name and brief description of the class/command, separated by a hyphen and arbitrary numbers of white spaces (like this pod).

If you distribute your script, you may want to make a subclass of this command just to provide more user-friendly document (content-wise and language-wise).

METHODS

run

shows a list of available commands (with brief description if any), or help (pod) of a specific command.

options

by default, encode/decode options are available to change encoding.

extra_namespaces

by default, this command looks for commands just under the namespace you specified in the script/dispatcher. However, you may want it to look into other directories to show something like tutorials. For example, if you make a subclass like this:

  package MyScript::Help;
  use strict;
  use base qw( CLI::Dispatcher::Help );

  sub extra_namespaces { qw( MyScript::Cookbook ) }
  1;

then, when you run the script like this, MyScript/Cookbook/Install.pod (or .pm) will be shown:

  > perl myscript.pl help install

You may even make it language-conscious:

  package MyScript::Help;
  use strict;
  use base qw( CLI::Dispatcher::Help );

  sub options {qw( lang=s )}

  sub extra_namespaces {
    my $self = shift;
    my $lang = uc( $self->option('lang') || 'EN' );
    return (
      'MyScript::Cookbook::'.$lang,
      'MyScript::Cookbook::EN',     # in case of $lang is wrong
    );
  1;

This can be used to provide more user-friendly documents (without overriding commands themselves).

output

by default, takes a text, decode/encode it if necessary, prints the result to stdout, and returns the text.

extract_pod

takes a command and looks for the actual pm/pod file to read its pod, and returns the pod (without the first section to hide the class name and brief description).

extract_pod_body

takes a pod, removes the first ("NAME") section, and returns the pod. You may also want to hide other sections like "AUTHOR" and "COPYRIGHT" for end users.

list_commands

returns a concatenated text of a list of the available commands with brief description (if any).

convert_command

takes a name of a command, converts it if necessary (decamelize by default), and returns the result.

extract_brief_description

takes a pod, extract the first ("NAME") section (actually the first line of the first section), and returns it. Override this if you don't want to cut longer (multi-lined) description.

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Kenichi Ishigaki.

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

cpanm CLI::Dispatch

perl -MCPAN -e shell
install CLI::Dispatch