Skip Menu |
 

This queue is for tickets about the App-Rad CPAN distribution.

Report information
The Basics
Id: 40578
Status: resolved
Priority: 0/
Queue: App-Rad

People
Owner: garu [...] cpan.org
Requestors: notbenh [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: (no value)
Broken in: (no value)
Fixed in: (no value)



Subject: help with more data on each command
Download (untitled) / with headers
text/plain 583b
it would be nice to have more context docs in your commands: cmd help ... hello : will print out 'hello world' then in your command, something that allows you to export your docs, the only two things that I can think of are messy but would work: - have a seperate sub (would require them being pulled from $c->commands though : sub hello {...}; sub hello_doc { return q{...} } - use PPI to parse out POD sub hello { return 'hello world'; =for help ... = end help } Other then that I'm loving having something else write up the 80% drudge code for the small things. -- benh~
Download (untitled) / with headers
text/plain 1.9k
On Fri Oct 31 18:18:47 2008, NOTBENH wrote: Show quoted text
> it would be nice to have more context docs in your commands: > > cmd help > ... > hello : will print out 'hello world' >
I've thought about it, and you're absolutely right! Unfortunately, I've only thought of somewhat messy solutions for it (just like you said). The elegant one will be a couple of releases away when you'll be able to have a single module as a single command (e.g.: Myapp::Commands::Cmd or whatever) and then we can have some special-purpose subroutines just for that. On the other hand, this leads to bigger applications and may just not be suitable for small "single .pl" apps, so it's still an issue for me. Show quoted text
> > then in your command, something that allows you to export your docs, the > only two things that I can think of are messy but would work: > > - have a seperate sub (would require them being pulled from $c->commands > though : > sub hello {...}; > sub hello_doc { return q{...} } > > - use PPI to parse out POD > sub hello { > return 'hello world'; > =for help > ... > = end help > }
I'm trying to give the greatest amount of freedom possible to the developer, so I'll try to keep "reserved" subroutine names to a minimum. On the other hand, I kinda liked your "=for" POD approach (it's way better than the ones I thought of so far). I'll give that a try right away (too bad I didn't caught your report until after I released 0.6), probably with Pod::Parser instead of PPI - since I'm trying to keep dependencies to a minimum and Pod::Parser is 5.8 core. Show quoted text
> > Other then that I'm loving having something else write up the 80% drudge > code for the small things. >
Thanks! That's the general idea :) Please let me know if you have any more ideas, comments or requests for App::Rad (on this or any other subject to easen and improve it). It's great to have feedback! I'll update this ticket as soon as your request is implemented. Best regards, -b Show quoted text
> -- > benh~
Download (untitled) / with headers
text/plain 3.3k
Fixed in 0.7! Now the register_commands() method accepts not only rules but also a list of commands with their help text. This way you can code like this: sub setup { my $c = shift; $c->register_commands({ 'hello' => 'will print hello world', 'foo' => 'will do foo', 'bar' => 'will do bar', }); } and now 'hello', 'foo' and 'bar' have embedded help information :) ./myapp.pl Usage: myapp.pl command [arguments] Available Commands: bar will do bar foo will do foo hello will print hello world help show syntax and available commands Note that, in this example, I can have as many internal subs as I like, as App::Rad will only register as commands the ones you told him to. This version register_commands() is a lot more powerful and can add commands by rules, rule exceptions, or simple command listing. Please refer to the documentation for advanced usage examples. One small catch, though, is that I had to do a minor API change: Now, "ignore_suffix", "ignore_prefix" and "ignore_regexp" *must* start with a dash ("-ignore_*), otherwise App::Rad will try to include a command named "ignore_prefix", etc. I hope this is what you expected! Please let me know if this fulfills your needs properly. And thanks again for the report! -b On Sun Nov 02 23:15:49 2008, GARU wrote: Show quoted text
> On Fri Oct 31 18:18:47 2008, NOTBENH wrote:
> > it would be nice to have more context docs in your commands: > > > > cmd help > > ... > > hello : will print out 'hello world' > >
> > I've thought about it, and you're absolutely right! Unfortunately, I've > only thought of somewhat messy solutions for it (just like you said). > The elegant one will be a couple of releases away when you'll be able to > have a single module as a single command (e.g.: Myapp::Commands::Cmd or > whatever) and then we can have some special-purpose subroutines just for > that. On the other hand, this leads to bigger applications and may just > not be suitable for small "single .pl" apps, so it's still an issue
for me. Show quoted text
>
> > > > then in your command, something that allows you to export your docs, the > > only two things that I can think of are messy but would work: > > > > - have a seperate sub (would require them being pulled from $c->commands > > though : > > sub hello {...}; > > sub hello_doc { return q{...} } > > > > - use PPI to parse out POD > > sub hello { > > return 'hello world'; > > =for help > > ... > > = end help > > }
> > I'm trying to give the greatest amount of freedom possible to the > developer, so I'll try to keep "reserved" subroutine names to a minimum. > On the other hand, I kinda liked your "=for" POD approach (it's way > better than the ones I thought of so far). > > I'll give that a try right away (too bad I didn't caught your report > until after I released 0.6), probably with Pod::Parser instead of PPI - > since I'm trying to keep dependencies to a minimum and Pod::Parser is > 5.8 core. >
> > > > Other then that I'm loving having something else write up the 80% drudge > > code for the small things. > >
> > Thanks! That's the general idea :) > > Please let me know if you have any more ideas, comments or requests for > App::Rad (on this or any other subject to easen and improve it). It's > great to have feedback! > > I'll update this ticket as soon as your request is implemented. > > Best regards, > > -b >
> > -- > > benh~
>
Subject: Re: [rt.cpan.org #40578] help with more data on each command
Date: Thu, 13 Nov 2008 12:50:36 -0800
To: bug-App-Rad [...] rt.cpan.org
From: benh <ben.hengst [...] gmail.com>
Download (untitled) / with headers
text/plain 3.7k
very cool. thanks. On Wed, Nov 12, 2008 at 6:14 PM, Breno G. de Oliveira via RT <bug-App-Rad@rt.cpan.org> wrote: Show quoted text
> <URL: http://rt.cpan.org/Ticket/Display.html?id=40578 > > > Fixed in 0.7! > > Now the register_commands() method accepts not only rules but also a > list of commands with their help text. This way you can code like this: > > sub setup { > my $c = shift; > > $c->register_commands({ > 'hello' => 'will print hello world', > 'foo' => 'will do foo', > 'bar' => 'will do bar', > }); > } > > and now 'hello', 'foo' and 'bar' have embedded help information :) > > ./myapp.pl > Usage: myapp.pl command [arguments] > > Available Commands: > bar will do bar > foo will do foo > hello will print hello world > help show syntax and available commands > > Note that, in this example, I can have as many internal subs as I like, > as App::Rad will only register as commands the ones you told him to. > > This version register_commands() is a lot more powerful and can add > commands by rules, rule exceptions, or simple command listing. Please > refer to the documentation for advanced usage examples. > > One small catch, though, is that I had to do a minor API change: > > Now, "ignore_suffix", "ignore_prefix" and "ignore_regexp" *must* start > with a dash ("-ignore_*), otherwise App::Rad will try to include a > command named "ignore_prefix", etc. > > I hope this is what you expected! Please let me know if this fulfills > your needs properly. And thanks again for the report! > > -b > > On Sun Nov 02 23:15:49 2008, GARU wrote:
>> On Fri Oct 31 18:18:47 2008, NOTBENH wrote:
>> > it would be nice to have more context docs in your commands: >> > >> > cmd help >> > ... >> > hello : will print out 'hello world' >> >
>> >> I've thought about it, and you're absolutely right! Unfortunately, I've >> only thought of somewhat messy solutions for it (just like you said). >> The elegant one will be a couple of releases away when you'll be able to >> have a single module as a single command (e.g.: Myapp::Commands::Cmd or >> whatever) and then we can have some special-purpose subroutines just for >> that. On the other hand, this leads to bigger applications and may just >> not be suitable for small "single .pl" apps, so it's still an issue
> for me.
>>
>> > >> > then in your command, something that allows you to export your docs, the >> > only two things that I can think of are messy but would work: >> > >> > - have a seperate sub (would require them being pulled from $c->commands >> > though : >> > sub hello {...}; >> > sub hello_doc { return q{...} } >> > >> > - use PPI to parse out POD >> > sub hello { >> > return 'hello world'; >> > =for help >> > ... >> > = end help >> > }
>> >> I'm trying to give the greatest amount of freedom possible to the >> developer, so I'll try to keep "reserved" subroutine names to a minimum. >> On the other hand, I kinda liked your "=for" POD approach (it's way >> better than the ones I thought of so far). >> >> I'll give that a try right away (too bad I didn't caught your report >> until after I released 0.6), probably with Pod::Parser instead of PPI - >> since I'm trying to keep dependencies to a minimum and Pod::Parser is >> 5.8 core. >>
>> > >> > Other then that I'm loving having something else write up the 80% drudge >> > code for the small things. >> >
>> >> Thanks! That's the general idea :) >> >> Please let me know if you have any more ideas, comments or requests for >> App::Rad (on this or any other subject to easen and improve it). It's >> great to have feedback! >> >> I'll update this ticket as soon as your request is implemented. >> >> Best regards, >> >> -b >>
>> > -- >> > benh~
>>
> > > >
-- benh~ http://three.sentenc.es/
Some people complained about having to setup() first in order to set the help string for each command, so as of version 0.8 of App::Rad you can also use the 'Help()' attribute: use strict; use warnings; use App::Rad; App::Rad->run(); sub mycmd :Help(this is my help string) { ... } sub myothercmd :Help(this is another help string) { ... } The default output would go something like this: $ perl myapp.pl Usage: myapp.pl command [arguments] Available Commands: help show syntax and available commands mycmd this is my help string myothercmd this is another help string This way the command help text is near the command declaration itself, so it's probably even easier to maintain. Note that Perl attribute syntax is a little strict so you cannot put any spaces between "Help" and "(". And I used "Help()" instead of "help()" (with lower "h") to avoid ambiguity with the 'help' command and a name clash with a possible (but unlikely) future built-in function of perl itself. Hope this improves the experience :)


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.