adding module list command

[spasarok]

Hello! The ops guy at my company (@matro) is interested in using Peru to automate some build tasks. I was wondering if you'd be interested in integrating some sort of peru module list command. The code here would list modules in either a human readable format or, if the -z flag is specified, in a format better suited for iteration. Let me know what you think! Thanks!

[oconnor663]

Thanks for the PR! @matro and I talked a little bit about features like this last year (#101), so I'm glad to start looking at code.

It would help me think about the requirements, if you could describe an example script that would consume this. Here are some of the questions that come up for me:

• Is it enough to dump everything out at once, or will callers want to do things like "list all module names" and "list all the overrides" separately?
• Would different modes like that work better as separate commands, or flags to a single command?
• Is the caller likely to be written in Bash (which struggles to parse even newlines), or a more powerful language?

If there's an 80% use case that can be satisfied by a simple command or two, that'll probably make sense to add into peru. But if we find ourselves imagining a bunch of different flags and filters and things like that (to do things like "list all the url fields for each git module that's been overridden" or "list all the modules that are defined but not imported"), it might make more sense to just tell clients "take a dependency on a YAML parsing library and read peru.yaml directly". That's one of the major benefits of using a widely supported format.

(Another thought that's come up before, is that in use cases that involve a lot of automated editing of the peru.yaml file, it might make more sense to actually generate the entire file, rather than trying to edit it in place. This is especially true if your automation is already storing state of its own somewhere else; it's much cleaner to have one source of truth than to have two of them and to try to keep them in sync.)

Let me know some more of your thoughts. I'll go ahead and comment inline on implementation details in this PR too.

[oconnor663]

I think the convention with find and git is to use the null character \x00 as a delimiter in the machine-readable mode. That makes it at least a little less likely that one of the strings you're printing will accidentally contain the delimiter inside of it. (For example, if we were listing full targets like module_name|rule_name, the | in there would kind of conflict with the | delimiter we have here.)

[matro]

For my needs, getting just the module names would easily pass the 80% mark. That'd get me a list to loop over and get atomic commits for each peru reup $module_name. And since everything hinges on module names... that list (especially with decently-named modules) should do most of what humans and simple scripts would need, I'd think. Kind of like git branch.

When we came back to this recently, @spasarok and I got feedback along the lines of "more info spat into the terminal is better". I'm kind of on the fence about it, but I'm kind of thinking it's a brain thing; folks used to git status & https://getcomposer.org/doc/03-cli.md#status constantly might just find "open this file" jarring.

Tugging on the git branch yarn... what would the Peru equiv. of git branch -vv look like? I think that'd take things to the 100% mark. Something verbose enough to be useful (especially if it includes override state), but not overwhelming or too verbose. Enough to show "the state of the world" and give someone what they need to do some peru overrideing, or zoom straight to where they're aiming in peru.yaml.

And anything beyond that... I feel like taking a stance of "simmer down, sed/awkers, parse the YAML or pipe --json through https://stedolan.github.io/jq/" (like @olson-sean-k brought up in #163) makes total sense. Adding flags to tune output sounds nice on the surface, but I can definitely seen ballooning complexity in both code and documentation.

[matro]

Or, heck... maybe peru list just prints module names, some separate peru status shows "state of the world", and everything else is "parse thee some YAML/JSON" territory?

[oconnor663]

We've replaced this PR with #171