Add --include and --exclude and override defaults based on output mode

[displague]

• Globalizes the --json and --yaml arguments as a simplification.
• Adds --include and --exclude which can accept comma-separated values or can be given multiple times to specify more includes/excludes. Naturally, dotted syntax (as supported by the API) can be used to include/exclude deep values.
• Default includes will not be used when their results are not rendered (affects projects, events, hardware-reservations). Do override defaults in longer listing formats, --include="" can be used.

Fixes #51: packet projects get no longer includes members as an include, unless --json/--yaml is provided

[vielmetti]

I think I'm doing it wrong, but I'm not sure what I'm doing wrong:

emv@bastion-01:~/src/github.com/packethost/packet-cli$ ./packet-cli device get -p $FREEBIES --include id,hostname,ip_addresses.address | more
+--------------------------------------+---------------+------------------+-----
---+----------------------+
|                  ID                  |   HOSTNAME    |        OS        | STAT
E  |       CREATED        |
+--------------------------------------+---------------+------------------+-----
---+----------------------+
| 116abfa3-b1c7-4e96-a559-3a48e691a419 | freebsd-ewr1  | FreeBSD 12.1     | acti
ve | 2020-08-30T02:04:30Z |
| 8b6695c5-1839-4c28-94a2-922fda96aae7 | debian10-ewr1 | Debian 10        | acti
ve | 2020-08-30T02:05:37Z |
| 18cc6bf8-b23a-4025-9e01-f7cd894ae6d2 | qualcomm-01   | Ubuntu 18.04 LTS | acti
ve | 2020-05-21T04:52:12Z |
| 6105741f-14ee-462a-8fd9-e580af929ba2 | bastion-01    | Ubuntu 20.04 LTS | acti
ve | 2020-05-20T16:44:22Z |
| 2f07a39f-3256-4619-87f9-432be941c892 | mon1          | Deprovision      | fail
ed | 2020-06-15T11:37:32Z |
+--------------------------------------+---------------+------------------+-----
---+----------------------+
emv@bastion-01:~/src/github.com/packethost/packet-cli$

[vielmetti]

I could use a fully worked-out example of --include and --exclude here.

[vielmetti]

I could use a fully worked-out example of --include and --exclude; I wasn't able to figure out how to use it from these docs.

[displague]

Great point, @vielmetti!

The includes and excludes could easily be confused for output field selectors. That is not their purpose.

https://www.packet.com/developers/api/common-parameters/ describes how includes and excludes are used in the API. Effectively, this expands or collapses Href sub-entities in API responses.

I'll include a section in the README.md about how to use this in practice.

The reason that packet projects get runs slowly is because the API request is "including" or embedding details about the members of each project. These additional details added a significant amount of time to the API request.

By changing the default include/exclude behavior for commands, and allowing these to be overridden (--include, --exclude), we can speed up the default request behavior, especially when the embedded details would not have been rendered. Users can also embed additional entities in their responses..

To maintain backward compatibility for long output formats (yaml, json) the default embedding options are retained in those modes.

command	behavior
packet projects get	default table listing with this PR it no longer embeds members lists in the API request/response
packet projects get --json	still takes long, includes full member lists

[vielmetti]

Makes sense - anything to speed up the common case!

[displague]

@vielmetti Updated in the latest push with some README.md content about --include and --exclude and an example.

[vielmetti]

Looks good to me - I'll have to test with one of my jumbo organization that has dozens of projects.