Understanding CPAN's SCRIPT CATEGORIES

shawnhcorey has asked for the wisdom of the Perl Monks concerning the following question:

Hi, I want to install a script into CPAN but I don't know what category to place it in. Is there a web page that describes them? I looked at http://cpan.org/scripts/index.html but it does not have a description of the categories.

The script is called "sub" and it creates skeletons of sub's by parsing an usage statement and applying it to a template. An usage statement is not valid Perl but it makes sense. For examples:

  $text | @text = trim( @text );
[download]

will create:

  # --------------------------------------
  #       Name: trim
  #      Usage: $text = trim( @text );
  #             @text = trim( @text );
  #    Purpose: TBD
  # Parameters: @text -- TBD
  #    Returns: $text -- TBD
  #             @text -- TBD
  #
  sub trim {
    my @text = @_;
    my $text = '';

    return wantarray ? @text : $text;
  }
[download]

and

  \%options = $object->get_options( ; @option_names );
[download]

will create:

  # --------------------------------------
  #       Name: get_options
  #      Usage: \%options = $object->get_options( ; @option_names );
  #    Purpose: TBD
  # Parameters: @option_names -- TBD
  #    Returns:     \%options -- TBD
  #
  sub get_options {
    my $self         = shift @_;
    my @option_names = @_;
    my $options      = {};

    return $options;
  }
[download]

Can someone suggest a category for it?

Comment on Understanding CPAN's SCRIPT CATEGORIES Select or Download Code

Replies are listed 'Best First'.
Re: Understanding CPAN's SCRIPT CATEGORIES by GrandFather (Saint) on Jul 22, 2009 at 00:38 UTC
I heartily second jethro's suggestion that you create a module rather than a script on CPAN. Scripts are very poor cousins compared to modules. My First contribution to CPAN was a script and I now really wish I'd done it as a module with a small 'demo' script to call it, or used the 'run a module' trick to allow its use as both a module and a script. For example: `use warnings; use strict; package RunableModule; #... normal module stuff here sub InterestingEntryPoint { print "Hey, it works\n"; } # Execute the InterestingEntryPoint sub if being run as a script InterestingEntryPoint () unless caller (); 1;` [download] Prints: `Hey, it works` [download] when executed from the command line as a script. True laziness is hard work	[reply] [d/l] [select]
Re: Understanding CPAN's SCRIPT CATEGORIES by jethro (Monsignor) on Jul 21, 2009 at 23:53 UTC
Devel:: or Sub:: seem appropriate. UPDATE: Oh, sorry, read over the part where you said 'script'. It looks like you need a new category there. But check out Module::Starter. It has a script called module-starter alongside which just calls the module. And it might be a good idea to similarily create a module for your code and just add a small script that then calls your module. That way others can expand on or use your code in their projects	[reply]
Re: Understanding CPAN's SCRIPT CATEGORIES by shawnhcorey (Friar) on Jul 22, 2009 at 12:17 UTC
Thank you all for your suggestions. As to creating a module, at first I thought, "How would this be possible? The only option it has is --help." Then I realized that I could break it into a parser and a code generator. So now I get to rewrite it as a module. Oh joy. As to its name, the Sub:: modules seems to be about modifying the behaviour of sub's, whereas Devel:: seems to be about creating things. Unfortunately there already is a module Devel::Sub::Which that means I can't name mine simply Devel::Sub without confusion. What do you think of the name Devel::Sub::API?	[reply]
Re^2: Understanding CPAN's SCRIPT CATEGORIES by jethro (Monsignor) on Jul 23, 2009 at 01:09 UTC
API sound so passive and general. How about Devel::Sub::Creator ?	[reply]
Re^3: Understanding CPAN's SCRIPT CATEGORIES by shawnhcorey (Friar) on Jul 23, 2009 at 13:39 UTC
I thought of that. Also, Maker, Generator, and Writer but each of these imply that it would create the entire sub, code included. But it only deals with the interface, so API.	[reply]
Re^4: Understanding CPAN's SCRIPT CATEGORIES by jethro (Monsignor) on Jul 23, 2009 at 14:08 UTC
Re^5: Understanding CPAN's SCRIPT CATEGORIES by shawnhcorey (Friar) on Jul 23, 2009 at 14:38 UTC
Some notes below your chosen depth have not been shown here
Re: Understanding CPAN's SCRIPT CATEGORIES by shawnhcorey (Friar) on Jul 23, 2009 at 21:54 UTC
After more thought, how about `Devel::Sub::Foundation` since it creates something that has to be built upon? A list of things it does: It has setters and getters to manipulate its attributes. It can set its attributes by parsing a usage statement. It can write a usage statement. It can write a sub foundation. It can write a POD foundation for documenting the sub.	[reply]
Re^2: Understanding CPAN's SCRIPT CATEGORIES by jethro (Monsignor) on Jul 24, 2009 at 08:40 UTC
At first I thought it sounded somewhat unspecific, but on second thought it fits quite well.	[reply]
Re: Understanding CPAN's SCRIPT CATEGORIES by shawnhcorey (Friar) on Jul 25, 2009 at 17:32 UTC
Have you every work on something for days only to discover that the answer has been staring you in the face all along? The obvious name is `Sub::Starter` and the corresponding script, `sub-starter`. D'uh!	[reply]