ARGV-Struct

 view release on metacpan or  search on metacpan

LICENSE  view on Meta::CPAN

    a) cause the modified files to carry prominent notices stating that
    you changed the files and the date of any change; and

    b) cause the whole of any work that you distribute or publish, that
    in whole or in part contains the Program or any part thereof, either
    with or without modifications, to be licensed at no charge to all
    third parties under the terms of this General Public License (except
    that you may choose to grant warranty protection to some or all
    third parties, at your option).

    c) If the modified program normally reads commands interactively when
    run, you must cause it, when started running for such interactive use
    in the simplest and most usual way, to print or display an
    announcement including an appropriate copyright notice and a notice
    that there is no warranty (or else, saying that you provide a
    warranty) and that users may redistribute the program under these
    conditions, and telling the user how to view a copy of this General
    Public License.

    d) You may charge a fee for the physical act of transferring a
    copy, and you may at your option offer warranty protection in

LICENSE  view on Meta::CPAN

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19xx name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the
  program `Gnomovision' (a program to direct compilers to make passes
  at assemblers) written by James Hacker.

README.md  view on Meta::CPAN

# SYNOPSIS

    use ARGV::Struct;
    my $struct = ARGV::Struct->new->parse;

# DESCRIPTION

Have you ever felt that you need something different than Getopt?

Are you tired of shoehorning Getopt style arguments into your commandline scripts?

Are you trying to express complex datastructures via command line?

then ARGV::Struct is for you!

It's designed so the users of your command line utilities won't hate you when things
get complex.

# THE PAIN

I've had to use some command-line utilities that had to do creative stuff to transmit
deeply nested arguments, or datastructure-like information. Here are some strategies that
I've found over time: 

## Complex arguments codified as JSON

JSON is horrible for the command line because you have to escape the quotes. It's a nightmare.

    command --complex_arg "{\"key1\":\"value1\",\"key2\":\"value2\"}"

## Arguments encoded via some custom scheme

These schemes fail when you have to make values complex (lists, or other key/values)

    command --complex_arg key1,value1:key2,value2

## Repeating Getopt arguments

Getopt friendly, but too verbose

    command --key key1 --value value1 --key key1 --value value 2

# THE DESIGN

The design of this module is aimed at "playing well with the shell". The main purpose is
to let the user transmit complex data structures, while staying compact enough for command line
use.

## Key/Value sets (objects)

On the command line, the user can transmit sets of key/value pairs within curly brackets

    command { K_V_PAIR1 K_V_PAIR2 }

The shell is expected to do some work for us, so key/value pairs are separated by spaces

Each key/value pair is expressed as

    Key: Value

The colon between Keys and values is optional, so

    Key Value

is the same as above

If the value contains spaces, the user can surround the pair with the shell metacharacters

    command { Key: " Value " }

Values can also be objects:

    command { Key: { Nested Key } }

or lists

    command { Key: [ 1 2 3 ] }

If you want a key with a colon at the end, just repeat the colon:

    Key:: Value

## Lists

    command [ VALUE1 VALUE2 ]

Each value can be a simple scalar value, or an object or list

    command [ { Name X } { Name Y } ]
    command [ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 9 ] ]
    command [ "First Value" "Second Value" ]

Values are never separated by commas to keep the syntax compact. 
The shell is expected to split the different elements into tokens, so
the user is expected to use shell quotes to keep values together

# METHODS

## new(\[argv => ArrayRef\])

Return an instance of the parser. If argv is not specified, @ARGV will be
used.

## parse

return the parsed data structure

# STATUS

This module is quite experimental. I developed it while developing Paws (a 
Perl AWS SDK). It has a commandline utility that needs to recollect all the
Attributes and Values for method calls, and lots of times, they get complex. 
Since trying to pass params with Getopt was getting ugly as hell, I decided 
that it would be better to do things in a different way, and eventually
thought it could be an independent module.

I'm publishing this module to get the idea out to the public so it can be worked
on.

Please bash the guts out of it. Break it and shake it till it falls apart. 

Contribute bugs and patches. All input is welcome.

To help with the bashing, when you install this dist, you get a command line util
called argvstruct. It will basically print a Data::Dumper of the structure generated
by it's arguments

    user@host:~$ argvstruct { Hello Guys How [ Are You { Doing Today } ] }
    $VAR1 = {
            'Hello' => 'Guys',
            'How' => [
                       'Are',
                       'You',
                       {

lib/ARGV/Struct.pm  view on Meta::CPAN

=head1 SYNOPSIS

  use ARGV::Struct;
  my $struct = ARGV::Struct->new->parse;

=head1 DESCRIPTION

Have you ever felt that you need something different than Getopt?

Are you tired of shoehorning Getopt style arguments into your commandline scripts?

Are you trying to express complex datastructures via command line?

then ARGV::Struct is for you!

It's designed so the users of your command line utilities won't hate you when things
get complex.

=head1 THE PAIN

I've had to use some command-line utilities that had to do creative stuff to transmit
deeply nested arguments, or datastructure-like information. Here are some strategies that
I've found over time: 

=head2 Complex arguments codified as JSON

JSON is horrible for the command line because you have to escape the quotes. It's a nightmare.

  command --complex_arg "{\"key1\":\"value1\",\"key2\":\"value2\"}"

=head2 Arguments encoded via some custom scheme

These schemes fail when you have to make values complex (lists, or other key/values)

  command --complex_arg key1,value1:key2,value2

=head2 Repeating Getopt arguments

Getopt friendly, but too verbose

  command --key key1 --value value1 --key key1 --value value 2

=head1 THE DESIGN

The design of this module is aimed at "playing well with the shell". The main purpose is
to let the user transmit complex data structures, while staying compact enough for command line
use.

=head2 Key/Value sets (objects)

On the command line, the user can transmit sets of key/value pairs within curly brackets

  command { K_V_PAIR1 K_V_PAIR2 }

The shell is expected to do some work for us, so key/value pairs are separated by spaces

Each key/value pair is expressed as

  Key: Value

The colon between Keys and values is optional, so

  Key Value

is the same as above

If the value contains spaces, the user can surround the pair with the shell metacharacters

  command { Key: " Value " }

Values can also be objects:

  command { Key: { Nested Key } }

or lists

  command { Key: [ 1 2 3 ] }

If you want a key with a colon at the end, just repeat the colon:

  Key:: Value

=head2 Lists

  command [ VALUE1 VALUE2 ]

Each value can be a simple scalar value, or an object or list

  command [ { Name X } { Name Y } ]
  command [ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 9 ] ]
  command [ "First Value" "Second Value" ]

Values are never separated by commas to keep the syntax compact. 
The shell is expected to split the different elements into tokens, so
the user is expected to use shell quotes to keep values together

=head1 METHODS

=head2 new([argv => ArrayRef])

Return an instance of the parser. If argv is not specified, @ARGV will be
used.

=head2 parse

return the parsed data structure

=head1 STATUS

This module is quite experimental. I developed it while developing Paws (a 
Perl AWS SDK). It has a commandline utility that needs to recollect all the
Attributes and Values for method calls, and lots of times, they get complex. 
Since trying to pass params with Getopt was getting ugly as hell, I decided 
that it would be better to do things in a different way, and eventually
thought it could be an independent module.

I'm publishing this module to get the idea out to the public so it can be worked
on.

Please bash the guts out of it. Break it and shake it till it falls apart. 

Contribute bugs and patches. All input is welcome.

To help with the bashing, when you install this dist, you get a command line util
called argvstruct. It will basically print a Data::Dumper of the structure generated
by it's arguments

  user@host:~$ argvstruct { Hello Guys How [ Are You { Doing Today } ] }
  $VAR1 = {
          'Hello' => 'Guys',
          'How' => [
                     'Are',
                     'You',
                     {