Proposed module for CPAN for FilePro data file reading

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

I have some perl code that literally tens of people might be interested in. Although I've used perl for a decade, it has been a long time since I've coded anything other than simple ad-hoc scripts in it. So I'm pretty new to the OO perl model (I've written a book on Java, but perl OO is a little more, well, exotic!)

Anyways, the module is designed to allow you to read data from a closed, old 4GL called "FilePro."

I built the module following the guidance in the Apress title "Writing Perl Modules for CPAN." Even with that, I've already seen things I know I should change. I'll switch from "die" to "croak" and so on.

Basically, I'm hoping someone will take a look and make recommendations for things I should address prior to offering it up on CPAN. I've got my PAUSE account and such, but I'd like someone besides me to look at it.

You can get to the code at my website (and take it easy, this server runs in my home!)

http://www.technodane.com/code/FilePro-Data-0.01.tar.gz

Like I said, I'm new to the formal module game. I'm seeking advice on writing tests, on documentation best practices, namespace (filePro appears to be a registered trademark; tips on that?)

An implementation detail: My iterator model uses a hash key string as a "handle." It would probably be better to use another "object" for that, but I'm not clear on the best way to do that. Does it make sense to put more than one "package" in a single CPAN module? Should the iterator be separate module on which FilePro::Data depends?

Any tips would be welcome!

Comment on Proposed module for CPAN for FilePro data file reading

Replies are listed 'Best First'.
Re: Proposed module for CPAN by toolic (Bishop) on Dec 01, 2009 at 22:30 UTC
Welcome to the Monastery. You should add the module name to your node title, such as "Proposed module for CPAN FilePro Data". I downloaded your tar.gz file, and I have the following suggestions: Add real tests. Your single t/ file just loads your module, but it does not do anything else. Start with basic tests, then add corner cases. The Perl Best Practices book has an excellent checklist of items to test. Add more code to the SYNOPSIS section of your POD. Try to make the code runnable if anyone does a copy-n-paste. Currently, it just shows how to construct an object, but I have no idea what to do with the object. Add POD for each method, describing legal input values/types, and typical return values. You can preview your POD prior to upload using Re: pod2html question, which is now available on CPAN: pod2cpanhtml (jmcnamara just /msg'd me about this) When I run perlcritic on your Data.pm file, I see some pretty simple things you can fix, such as "Bareword filehandle opened..." and "Return value of open ignored...". It dumps out 2 pages of warnings, which should not take you too long to decide what is important for you to fix. Review the Tutorials section here at the Monastery (Creating and Distributing Modules) Review perlnewmod Provide example usage code in an 'examples' directory. Add a META.yml file: I believe this is used by CPAN to list any dependencies. Finally, Fix CPAN uploads for world writable files Make sure you are maintaining your changes with your own version control system.	[reply]
Re: Proposed module for CPAN by spx2 (Deacon) on Dec 02, 2009 at 09:52 UTC
Hi, I read from "Writing Perl modules for CPAN" recently and it was pretty good. Now we have Dist::Zilla which does a lot of the work of writing pod tests, building, uploading to CPAN, prepends `use strict;use warnings` to your files or some other piece of code(that you can specify0, and a lot more(check plugins for Dist::Zilla on CPAN). You just write in ~/.dzil/config.ini your username and password to your PAUSE account and after that when you run `dzil release` the module is automatically built and uploaded to your PAUSE account. You can also have the version set in dzil.ini so that it gets into the POD of each of your .pm files, and it builds your `Makefile.PL` for you. Use Test::Kwalitee as a separate test for your module. It will make various checks on your module and tell you what you need to add/correct. For OO use Moose.	[reply] [d/l] [select]
Re: Proposed module for CPAN by biohisham (Priest) on Dec 01, 2009 at 23:31 UTC
OOP as a concept and practice is so interesting, I am yet to learn many a things and what not, very good that you got to implement what you studied, thinking of 'ideas' for a module is abound in puzzlement for me as a beginner, I installed your module on a Windoze machine and the installation went just smooth. I will just stress on providing code examples of the various contexts this module can be operational under and the different scenarios involving handling 'FilePro' formats this can serve to illustrate the capability of the module and extends a reaching hand to anyone who uses it... Other than this, good luck, and congrats for the achievement... Excellence is an Endeavor of Persistence. Chance Favors a Prepared Mind.	[reply] [d/l]
Re: Proposed module for CPAN for FilePro data file reading by talexb (Chancellor) on Dec 02, 2009 at 17:41 UTC
Cool. I can highly recommend Andy Lester's excellent module-starter script to build a skeleton structure for your module. You can then drop your existing code (which I've not downloaded) into that structure. Then just do `perl Makefile.PL`, `make dist`, and your module is ready to go. I've also had good success with Perl::Tidy and Perl::Critic to clean up and standardize code. The latter works like a Perl version of `lint`, which I used for a couple of years when I did C development. It asks those difficult questions like "Are you sure you want to do this here?" Finally, and you've already heard about this, tests are good, tests are great. They find the darndest things. Write lots of tests. Alex / talexb / Toronto Team website: Forex Chart Monkey, Forex Technical Analysis and Pickpocket Prevention "Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds	[reply] [d/l] [select]