Why YAML?

[dolmen]

I don't see the need for YAML.
It would be much simpler to write the spec in Perl.

If you had the need to parse the spec from outside the program itself (ex for documentation generators), you could just inject an --export-getopt-spec option that would dump the spec.

[perlpunk]

Hi,

actually you can write the spec in perl - it's just a hash of hashes and arrays. It would then be possible to dump it in any format.
So the format in which you write it doesn't actually matter. I chose YAML because it's easy to write a struture that can simply be read into perl.

My goal was that I have a spec in a (programming) language independent format in the first place, so I just need to write the completion and doc generator once; only the app framework itself that runs it needs to be implemented in the language itself.
That removes the need to run the app itself to get the spec. Porting to other languages will be easier. Usually only the author of the app needs to generate completion and docs.

So, it doesn't have to be YAML, but I think it should be a format which is easy to write and read.

My use case was: I wanted to generate an app, and the subcommands and its parameters would be automatically generated by a specification from somewhere else. I started to autogenerate MooseX::App classes, but I actually didn't need an extra class for all of the subcommands, I just needed one. It was too much work and didn't feel like the right way, so I stopped that.

I'm open for any suggestions! How would you want to write the spec?

[dolmen]

As someone currently working on implementing a web API and who started by writing a Swagger spec for it, I'm not in the position to tell you starting with a spec is a bad approach. :)

But this is just that I find this a bit overkill for the command line interface of a program.
If you really want to go that way because you consider the program an API, I think that the specification should also describe the input (STDIN) and output (STDOUT, STDERR) formats.

[perlpunk]

Yeah, my work with Swagger is one of the reasons I started this =)

I also thought about handling input and output.
How would you define it?
Maybe allow some automatic conversion, so you just return a data structure and it will be converted to json, yaml, (c|t)sv, and the other way round?

[dakkar]

As an additional data-point on ways to use App::Spec, I may point to my minimalist mailing list manager, Sietima. The mail class defines the basic sub-commands, and traits can add more.
It's also relatively easy to test!

[perlpunk]

@dakkar funny, your definitions look just like mine (name, summary, aliases etc.).
I guess that means that we chose good names ;-)

It also can do completion?

[dakkar]

@perlpunk they look like yours because I'm using App::Spec ☺
The main script uses a helper class that builds a trivial subclass of App::Spec::Run, and then it all works thanks to you.
I linked to my code as an example of having specs in Perl instead of YAML

[perlpunk]

@dakkar oh wow, appspec has its first user! \o/