X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=gitmo%2FMooseX-Getopt.git;a=blobdiff_plain;f=lib%2FMooseX%2FGetopt.pm;h=fc48b571b4412c7294bd4af52539088deb4b1781;hp=8907942e715b4560d3cb0b9c4c2d3bc1cc6054bd;hb=986fb4690bc00c860b1f728b986e39b412100854;hpb=b766829d7cc3432721907f957291cdc3edd56e61

diff --git a/lib/MooseX/Getopt.pm b/lib/MooseX/Getopt.pm
index 8907942..fc48b57 100644
--- a/lib/MooseX/Getopt.pm
+++ b/lib/MooseX/Getopt.pm
@@ -1,235 +1,13 @@
-
 package MooseX::Getopt;
-use Moose::Role;
-
-use MooseX::Getopt::OptionTypeMap;
-use MooseX::Getopt::Meta::Attribute;
-use MooseX::Getopt::Meta::Attribute::NoGetopt;
-
-use Carp ();
-
-use Getopt::Long (); # GLD uses it anyway, doesn't hurt
-use constant HAVE_GLD => not not eval { require Getopt::Long::Descriptive };
-
-our $VERSION   = '0.18';
-our $AUTHORITY = 'cpan:STEVAN';
-
-has ARGV       => (is => 'rw', isa => 'ArrayRef', metaclass => "NoGetopt");
-has extra_argv => (is => 'rw', isa => 'ArrayRef', metaclass => "NoGetopt");
-
-sub new_with_options {
-    my ($class, @params) = @_;
-
-    my $config_from_file;
-    if($class->meta->does_role('MooseX::ConfigFromFile')) {
-        local @ARGV = @ARGV;
-
-        my $configfile;
-        my $opt_parser = Getopt::Long::Parser->new( config => [ qw( pass_through ) ] );
-        $opt_parser->getoptions( "configfile=s" => \$configfile );
-
-        if(!defined $configfile) {
-            my $cfmeta = $class->meta->find_attribute_by_name('configfile');
-            $configfile = $cfmeta->default if $cfmeta->has_default;
-        }
-
-        if(defined $configfile) {
-            $config_from_file = $class->get_config_from_file($configfile);
-        }
-    }
-
-    my $constructor_params = ( @params == 1 ? $params[0] : {@params} );
-    
-    Carp::croak("Single parameters to new_with_options() must be a HASH ref")
-        unless ref($constructor_params) eq 'HASH';
-
-    my %processed = $class->_parse_argv(
-        options => [
-            $class->_attrs_to_options( $config_from_file )
-        ],
-        params => $constructor_params,
-    );
-
-    my $params = $config_from_file ? { %$config_from_file, %{$processed{params}} } : $processed{params};
-
-    $class->new(
-        ARGV       => $processed{argv_copy},
-        extra_argv => $processed{argv},
-        @params, # explicit params to ->new
-        %$params, # params from CLI
-    );
-}
-
-sub _parse_argv {
-    my ( $class, %params ) = @_;
-
-    local @ARGV = @{ $params{argv} || \@ARGV };
-
-    my ( $opt_spec, $name_to_init_arg ) = ( HAVE_GLD ? $class->_gld_spec(%params) : $class->_traditional_spec(%params) );
-
-    # Get a clean copy of the original @ARGV
-    my $argv_copy = [ @ARGV ];
-
-    my @err;
-
-    my ( $parsed_options, $usage ) = eval {
-        local $SIG{__WARN__} = sub { push @err, @_ };
-
-        if ( HAVE_GLD ) {
-            return Getopt::Long::Descriptive::describe_options($class->_usage_format(%params), @$opt_spec);
-        } else {
-            my %options;
-            Getopt::Long::GetOptions(\%options, @$opt_spec);
-            return ( \%options, undef );
-        }
-    };
-
-    die join "", grep { defined } @err, $@ if @err or $@;
-
-    # Get a copy of the Getopt::Long-mangled @ARGV
-    my $argv_mangled = [ @ARGV ];
+# ABSTRACT: A Moose role for processing command line options
 
-    my %constructor_args = (
-        map {
-            $name_to_init_arg->{$_} => $parsed_options->{$_}
-        } keys %$parsed_options,
-    );
+use Moose::Role 0.56;
 
-    return (
-        params    => \%constructor_args,
-        argv_copy => $argv_copy,
-        argv      => $argv_mangled,
-        ( defined($usage) ? ( usage => $usage ) : () ),
-    );
-}
+with 'MooseX::Getopt::GLD';
 
-sub _usage_format {
-    return "usage: %c %o";
-}
-
-sub _traditional_spec {
-    my ( $class, %params ) = @_;
-
-    my ( @options, %name_to_init_arg, %options );
-
-    foreach my $opt ( @{ $params{options} } ) {
-        push @options, $opt->{opt_string};
-
-        my $identifier = $opt->{name};
-        $identifier =~ s/\W/_/g; # Getopt::Long does this to all option names
-
-        $name_to_init_arg{$identifier} = $opt->{init_arg};
-    }
-
-    return ( \@options, \%name_to_init_arg );
-}
-
-sub _gld_spec {
-    my ( $class, %params ) = @_;
-
-    my ( @options, %name_to_init_arg );
-
-    my $constructor_params = $params{params};
-
-    foreach my $opt ( @{ $params{options} } ) {
-        push @options, [
-            $opt->{opt_string},
-            $opt->{doc} || ' ', # FIXME new GLD shouldn't need this hack
-            {
-                ( ( $opt->{required} && !exists($constructor_params->{$opt->{init_arg}}) ) ? (required => $opt->{required}) : () ),
-                # NOTE:
-                # remove this 'feature' because it didn't work 
-                # all the time, and so is better to not bother
-                # since Moose will handle the defaults just 
-                # fine anyway.
-                # - SL
-                #( exists $opt->{default}  ? (default  => $opt->{default})  : () ),
-            },
-        ];
+no Moose::Role;
 
-        my $identifier = $opt->{name};
-        $identifier =~ s/\W/_/g; # Getopt::Long does this to all option names
-
-        $name_to_init_arg{$identifier} = $opt->{init_arg};
-    }
-
-    return ( \@options, \%name_to_init_arg );
-}
-
-sub _compute_getopt_attrs {
-    my $class = shift;
-    grep {
-        $_->does("MooseX::Getopt::Meta::Attribute::Trait")
-            or
-        $_->name !~ /^_/
-    } grep {
-        !$_->does('MooseX::Getopt::Meta::Attribute::Trait::NoGetopt')
-    } $class->meta->get_all_attributes
-}
-
-sub _get_cmd_flags_for_attr {
-    my ( $class, $attr ) = @_;
-
-    my $flag = $attr->name;
-
-    my @aliases;
-
-    if ($attr->does('MooseX::Getopt::Meta::Attribute::Trait')) {
-        $flag = $attr->cmd_flag if $attr->has_cmd_flag;
-        @aliases = @{ $attr->cmd_aliases } if $attr->has_cmd_aliases;
-    }
-
-    return ( $flag, @aliases );
-}
-
-sub _attrs_to_options {
-    my $class = shift;
-    my $config_from_file = shift || {};
-
-    my @options;
-
-    foreach my $attr ($class->_compute_getopt_attrs) {
-        my ( $flag, @aliases ) = $class->_get_cmd_flags_for_attr($attr);
-
-        my $opt_string = join(q{|}, $flag, @aliases);
-
-        if ($attr->has_type_constraint) {
-            my $type = $attr->type_constraint;
-            if (MooseX::Getopt::OptionTypeMap->has_option_type($type)) {
-                $opt_string .= MooseX::Getopt::OptionTypeMap->get_option_type($type)
-            }
-        }
-
-        push @options, {
-            name       => $flag,
-            init_arg   => $attr->init_arg,
-            opt_string => $opt_string,
-            required   => $attr->is_required && !$attr->has_default && !$attr->has_builder && !exists $config_from_file->{$attr->name},
-            # NOTE:
-            # this "feature" was breaking because 
-            # Getopt::Long::Descriptive would return 
-            # the default value as if it was a command 
-            # line flag, which would then override the
-            # one passed into a constructor.
-            # See 100_gld_default_bug.t for an example
-            # - SL
-            #( ( $attr->has_default && ( $attr->is_default_a_coderef xor $attr->is_lazy ) ) ? ( default => $attr->default({}) ) : () ),
-            ( $attr->has_documentation ? ( doc => $attr->documentation ) : () ),
-        }
-    }
-
-    return @options;
-}
-
-no Moose::Role; 1;
-
-__END__
-
-=pod
-
-=head1 NAME
-
-MooseX::Getopt - A Moose role for processing command line options
+1;
 
 =head1 SYNOPSIS
 
@@ -295,7 +73,7 @@ specified by the C<--configfile> option (or the default you've
 given for the configfile attribute) for you.
 
 Options specified in multiple places follow the following
-precendence order: commandline overrides configfile, which
+precedence order: commandline overrides configfile, which
 overrides explicit new_with_options parameters.
 
 =head2 Supported Type Constraints
@@ -404,64 +182,89 @@ type for it to the C<OptionTypeMap>, it would be treated just
 like a normal C<ArrayRef> type for Getopt purposes (that is,
 C<=s@>).
 
-=head1 METHODS
-
-=over 4
-
-=item B<new_with_options (%params)>
+=method B<new_with_options (%params)>
 
 This method will take a set of default C<%params> and then collect
 params from the command line (possibly overriding those in C<%params>)
 and then return a newly constructed object.
 
+The special parameter C<argv>, if specified should point to an array
+reference with an array to use instead of C<@ARGV>.
+
 If L<Getopt::Long/GetOptions> fails (due to invalid arguments),
 C<new_with_options> will throw an exception.
 
+If L<Getopt::Long::Descriptive> is installed and any of the following
+command line params are passed, the program will exit with usage
+information (and the option's state will be stored in the help_flag
+attribute). You can add descriptions for each option by including a
+B<documentation> option for each attribute to document.
+
+  -?
+  --?
+  -h
+  --help
+  --usage
+
 If you have L<Getopt::Long::Descriptive> the C<usage> param is also passed to
-C<new>.
+C<new> as the usage option.
 
-=item B<ARGV>
+=method B<ARGV>
 
 This accessor contains a reference to a copy of the C<@ARGV> array
 as it originally existed at the time of C<new_with_options>.
 
-=item B<extra_argv>
+=method B<extra_argv>
 
 This accessor contains an arrayref of leftover C<@ARGV> elements that
 L<Getopt::Long> did not parse.  Note that the real C<@ARGV> is left
 un-mangled.
 
-=item B<meta>
+B<Important>: By default, L<Getopt::Long> will reject unrecognized I<options>
+(that is, options that do not correspond with attributes using the Getopt
+trait). To disable this, and allow options to also be saved in C<extra_argv> (for example to pass along to another class's C<new_with_options>), you can either enable the
+C<pass_through> option of L<Getopt::Long> for your class:  C<< use Getopt::Long
+qw(:config pass_through); >> or specify a value for for L<MooseX::Getopt::GLD>'s C<getopt_conf> parameter.
 
-This returns the role meta object.
+=method B<usage>
 
-=back
+This accessor contains the L<Getopt::Long::Descriptive::Usage> object (if
+L<Getopt::Long::Descriptive> is used).
 
-=head1 BUGS
+=method B<help_flag>
 
-All complex software has bugs lurking in it, and this module is no
-exception. If you find a bug please either email me, or add the bug
-to cpan-RT.
+This accessor contains the boolean state of the --help, --usage and --?
+options (true if any of these options were passed on the command line).
 
-=head1 AUTHOR
+=method B<print_usage_text>
 
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
+This method is called internally when the C<help_flag> state is true.
+It prints the text from the C<usage> object (see above) to stdout and then the
+program terminates normally.  You can apply a method modification (see
+L<Moose::Manual::MethodModifiers>) if different behaviour is desired, for
+example to include additional text.
 
-Brandon L. Black, E<lt>blblack@gmail.comE<gt>
+=method B<meta>
 
-Yuval Kogman, E<lt>nothingmuch@woobling.orgE<gt>
+This returns the role meta object.
 
-=head1 CONTRIBUTORS
+=method B<process_argv (%params)>
 
-Ryan D Johnson, E<lt>ryan@innerfence.comE<gt>
+This does most of the work of C<new_with_options>, analyzing the parameters
+and argv, except for actually calling the constructor. It returns a
+L<MooseX::Getopt::ProcessedArgv> object. C<new_with_options> uses this
+method internally, so modifying this method via subclasses/roles will affect
+C<new_with_options>.
 
-=head1 COPYRIGHT AND LICENSE
+=head2 More Customization Options
 
-Copyright 2007-2008 by Infinity Interactive, Inc.
+See L<Getopt::Long/Configuring Getopt::Long> for many other customizations you
+can make to how options are parsed. Simply C<use Getopt::Long qw(:config
+other_options...)> in your class to set these.
 
-L<http://www.iinteractive.com>
+=cut
 
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+=head1 SEE ALSO
+
+L<MooseX::Getopt::Usage>, an extension to generate man pages, with colour
 
-=cut