view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

ARGV::Struct - Parse complex data structures passed in ARGV

# 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