aws/aws-cli — pull request #408 by jamesls (2013-10-14 20:54:02+00:00)
Title: Improve existing text output in the CLI

Improve existing text output in the CLI

This PR improves the existing text output of the CLI.
There have been numerous requests at improving the text output.
To summarize the requests:

1. Provide backwards compat with existing CLIs (notably EC2 and CloudFormation)
2. Provide a way to to make text output scriptable (e.g. getting all the
instance ids from `aws ec2 describe-instances`)
3. Control the output of the columns emitted (this is also requested for table
output).

The majority of the pre-existing CLIs generally follow this text output:

```
IDENTIFIER	col1	col2	col3
OTHER	col4	col5	col6
IDENTIFIER	col1	col2	col3
```

That is, some identifier in all caps is the first column, followed by tab
separated columns that have been previously hand selected.

This new text output takes a similar approach with one exception:
**the output columns are solely based on the response.** We do not hand select
the columns to display. So for example, if I have a hash with the keys
'a', 'b', and 'c' with an identifier FOO then the resulting output will be:
`FOO	a	b	c`. This allows us to have a generic text output
algorithm without having to hand select output columns.

Additionally, this PR introduces a `--query` argument. This allow a user
to specify a jmespath expression that describes what data to select. This is
independent of the output format (so it can be used with json, table, and
text). Using the `--query` option with the `--output text` option gives
users a mechanism for which to write scripts.

## Examples

I plan on updating the docs to include more examples, but here are a few
examples of this in action. Let's take `ec2 describe-instances`, which is
has a rich set of output values. If we wanted to simulate the console
table that shows EC2 instances we can say:

```
$ aws ec2 describe-instances --output text --query 'Reservations[*].Instances[*].[Tags[0].Value,InstanceId,ImageId,RootDeviceType,InstanceType,State.Name]' | column -t

instancename i-12345 ami-12345 ebs t1.micro running
SomeRandomNameFooBar i-12345 ami-12345 ebs c1.medium running
FooBarBazBaz i-12345 ami-12345 ebs m1.large running
testsomething i-12345 ami-12345 ebs m1.large stopped
morestuff i-12345 ami-12345 ebs m1.small stopped
somename i-12345 ami-12345 ebs m1.small running
```

This also works with table output:

```
$ aws ec2 describe-instances --output table --query 'Reservations[*].Instances[*].{Tags[0].Value,InstanceId,ImageId,RootDeviceType,InstanceType,State.Name}'
--------------------------------------------------------------------------------------------------------
| DescribeInstances |
+--------------+-------------+---------------+-----------------+--------------+------------------------+
| ImageId | InstanceId | InstanceType | RootDeviceType | State.Name | Tags[0].Value |
+--------------+-------------+---------------+-----------------+--------------+------------------------+
| ami-12345678| i-12345678 | t1.micro | ebs | running | instancename |
| ami-12345678| i-12345678 | c1.medium | ebs | running | SomeRandomNameFooBar |
| ami-12345678| i-12345678 | m1.large | ebs | running | FooBarBazBaz |
| ami-12345678| i-12345678 | m1.large | ebs | stopped | testsomething |
| ami-12345678| i-12345678 | m1.small | ebs | stopped | morestuff |
| ami-12345678| i-12345678 | m1.small | ebs | running | somename |
+--------------+-------------+---------------+-----------------+--------------+------------------------+
```

This is an example of the text output without any `--query` specified:

```
$ aws iam list-users --output text --max-items 4 | column -t
USERS arn:aws:iam::1234567890:user/name123456 2013-02-12T19:08:52Z / EXAMPLEFOO name123456
USERS arn:aws:iam::1234567890:user/name1234 2012-10-14T23:53:39Z / EXAMPLEFOO name1234
USERS arn:aws:iam::1234567890:user/name123 2013-03-09T23:36:32Z / EXAMPLEFOO name123
USERS arn:aws:iam::1234567890:user/name12345 2013-02-23T02:36:27Z / EXAMPLEFOO name12345
```

Fixes #40, #81, #82, #84
Potentially fixes #337, #301. It only potentially fixes these two issues
because it's not backwards compatible with the old format, it does not use hand
selected columns, the columns are strictly based on the data in the parsed
response.

cc @garnaat, @toastdriven