Rocco's Perl Stufftag:blogs.perl.org,2009-11-03:/users/rocco_caputo//5632011-08-04T06:34:58ZThings Rocco's doing with Perl.Movable Type Pro 4.38Pod::Plexus meta-yak, editor foldingtag:blogs.perl.org,2011:/users/rocco_caputo//563.20472011-08-04T05:42:14Z2011-08-04T06:34:58ZPod::Plexus development has led me down a slippery slope peppered with boulders and broken glass I thought I could avoid forever. My inner typographer wants to lay out documentation "just so", which means putting all the POD together, usually at...Rocco Caputohttp://poe.perl.org/
Pod::Plexus development has led me down a slippery slope peppered with boulders and broken glass I thought I could avoid forever.

My inner typographer wants to lay out documentation "just so", which means putting all the POD together, usually at the end of the file. Pod::Plexus and Pod::Weaver move POD around, making this semitypographical exercise a big time waster. All the careful consideration of placing "SEE ALSO" before (or after) "BUGS" matters naught.

Suddenly interleaving POD and code doesn't sound so bad. It doesn't change the finished product. I can also get rid of some of my pre-method comments, since the documentation will do double duty. Smaller distributions and less work for me? What's not to like?

Well, it's a pity that interleaved code and POD is butt ugly and distracting. By breaking up the continuity and context between methods, it's actually interfering with my ability to hold design in my head. And this is code I'm in the process of writing. Maybe I'll evolve out of my modalities, but it's a learning hurdle for now.

Which leads me to my other nemesis, source folding. If you don't know, it's where groups of lines in a source file are squashed ("folded") together into a single line. As much as I hate the concept, the ability to hide POD or code might make interleaving them barely tolerable. It's ironic because I hate source folding about as much as I hate interleaving code and POD. Necessity seems to be the mother of strange bedfellows. Maybe two wrongs can make a right.

So I spent the past couple nights hacking POD/code folding into my .vimrc. Now two keystrokes will hide all the POD so I can read the code, and two other keystrokes will swap that around. The results are ugly and preliminary, but I'm kind of happy about them. I thought I'd share. This is me sharing. You have been shared with.

I plan to clean this up and add it to Pod::Plexus' CPAN distribution after the module is ready to be released. I chose to shave this meta-yak now because I think it'll help me write the remaining code faster. I'll let you know how that works out for me.

Meanwhile, if you know Vim scripting, you're probably better off than I am. Patches to this are welcome. For example, I don't know how I'm going to add Moose syntax to the mix.

]]>
If you can't make money, at least have fun.tag:blogs.perl.org,2011:/users/rocco_caputo//563.20332011-07-31T03:39:02Z2011-07-31T04:17:19ZThere's a saying: "If you can't make money, at least have fun." My open source projects have never earned a profit, but they've been enormous fun. They've put me in the position to meet a lot of great people and...Rocco Caputohttp://poe.perl.org/
There's a saying: "If you can't make money, at least have fun." My
open source projects have never earned a profit, but they've been
enormous fun.

They've put me in the position to meet a lot of great people and go to
interesting places. It's hard to imagine having more fun than I did
speaking at Perl Oasis and YAPC::NA this
year.
If anyone releasing projects in other languages has more fun than
this, how do they survive?

But giving away software is only fun when people use it. Otherwise
it's just saving public backups or something.

So if you're using CPAN modules (and can talk about it, of course) let
us authors know. Because most of us aren't making money at it, and
you'll help us have more fun and release more code despite that.

]]>
Reducing Documentation's Technical Debttag:blogs.perl.org,2011:/users/rocco_caputo//563.19802011-07-17T00:31:23Z2011-07-17T01:03:55ZI want to write good documentation, but my idea of it requires high effort to write and maintain. I'm working on [Pod::Plexus](https://github.com/rcaputo/pod-plexus) to make it easier.Rocco Caputohttp://poe.perl.org/
Documentation is a social asset, but it's balanced by a technical debt. Documentation describes code that changes over time. As the code changes, so must the docs.

I want to write good documentation for my Perl distributions, but my standard of "good" documentation requires a lot of effort to write and maintain. I'm working on Pod::Plexus to make it easier. It doesn't replace anything, as far as I know. In fact, I've begun using it with Pod::Weaver in my Reflex distribution.

For example, I tend to write modular, cross-referenced code. Everything but the most superficial interfaces is used somewhere else in the distribution. I'd rather not contrive usage examples, so why not reuse parts of the distribution in the documentation? So Pod::Plexus includes an "=example" directive to insert live code into the documentation.

One of my pet peeves is hierarchical documentation. It's easy to document a subclass by saying "everything else (which I may or may not list here) is documented in this base class". On the down side, that's terrible for first time users. What does the module provide? Which ancestor documents which method? So tonight I added an "=include" directive to insert live documentation from another place.

Here's an example of Pod::Plexus markup. Output follows. It uses "=example" to create a synopsis from the module's live implementation. "=include" imports the description from a nearly identical module. Pod::Plexus includes some templating magic, so [% doc.module %] expands to the module being documented.

In a future installment, I'll talk briefly about how "=index REGEXP" creates an index of all the distributed modules matching a regular expression.

]]>
App::PipeFilter for Top-N Reportstag:blogs.perl.org,2011:/users/rocco_caputo//563.18332011-06-06T23:28:26Z2011-06-06T23:40:33ZI'm testing some software at work by replaying pcap files at the application. I want to make sure the results in the database match what's in the original packet dump. There are hundreds of packet producers. I want to focus...Rocco Caputohttp://poe.perl.org/
I'm testing some software at work by replaying pcap files at the application. I want to make sure the results in the database match what's in the original packet dump. There are hundreds of packet producers. I want to focus on the top ten to make better use of my time.

I've written a utility to dump interesting packet data as streams of JSON objects, one per packet. Each object includes the source and destination IP and port, among other things.

]]>
Bundlefly - Make Your Bundles Flytag:blogs.perl.org,2011:/users/rocco_caputo//563.18152011-05-30T19:46:01Z2011-05-31T01:07:16ZBundlefly is a hack I've written to build a graph of a bundle's distributions and install them in optimal order. It accelerates the installation of entire library suites for new Perl builds and perlbrew instances. As with App::PipeFilter, it may...Rocco Caputohttp://poe.perl.org/Bundlefly is a hack I've written to build a graph of a bundle's distributions and install them in optimal order. It accelerates the installation of entire library suites for new Perl builds and perlbrew instances. As with App::PipeFilter, it may end up on CPAN if there's interest.

Autobundle snapshots are comprehensive by design. They list all installed modules at a particular point in time. We should rarely be asked to confirm "unsatisfied dependencies" while installing them. The dependencies are almost always somewhere in there.

To compound the suck, we're often asked to install the same fundamental dependencies repeatedly. ExtUtils::MakeMaker and Test::More immediately come to mind. We shouldn't be asked once, yet we're asked several times by the end of the day.

One problem is that autobundle snapshots list distributions alphabetically, and CPAN's shell installs them in that order. Test::More, a distribution used to test a large portion of CPAN, is installed relatively late—after it's already been prepended to the install queue as a dependency of several other distributions.

Bundlefly's dependency graph allows it to install dependencies before dependents. The only "unsatisfied dependencies" one should ever see are those introduced since the last CPANDB build and which aren't listed in the autobundle snapshot.

]]>
App::PipeFilter 0.001 on its way to CPANtag:blogs.perl.org,2011:/users/rocco_caputo//563.17982011-05-24T04:22:50Z2011-05-24T05:17:23ZThanks, everyone who was interested in App::PipeFilter. Your interest motivated me to clean it up and send the very first release to PAUSE. It'll be on CPAN once your favorite mirror catches up. Check out the snazzy documentation, which consumed...Rocco Caputohttp://poe.perl.org/
Thanks, everyone who was interested in App::PipeFilter. Your interest motivated me to clean it up and send the very first release to PAUSE. It'll be on CPAN once your favorite mirror catches up. Check out the snazzy documentation, which consumed most of my time since my last announcement.

]]>
App::PipeFilters gets multiline parsing and JSON::Pathtag:blogs.perl.org,2011:/users/rocco_caputo//563.17922011-05-21T05:49:55Z2011-05-21T06:39:46ZTonight I added support for multiline JSON input to all the App::PipeFilter tools. This is great for data sources that are beyond one's control, such as those found on the web. But I haven't found one to use as an...Rocco Caputohttp://poe.perl.org/
Tonight I added support for multiline JSON input to all the
App::PipeFilter tools.
This is great for data sources that are beyond one's control, such as
those found on the web. But I haven't found one to use as an example,
so you get this instead:

]]>
App::PipeFilters - JSON in the Shelltag:blogs.perl.org,2011:/users/rocco_caputo//563.17902011-05-20T04:25:49Z2011-05-20T04:44:40ZI've just put App::PipeFilters on github for review before I inflict them on CPAN. They're a small set of UNIX command line tools for working with structured data. In particular, JSON objects, one per line. They're compatible with many UNIX...Rocco Caputohttp://poe.perl.org/
I've just put App::PipeFilters on github for review before I inflict them on CPAN.

They're a small set of UNIX command line tools for working with structured data. In particular, JSON objects, one per line. They're compatible with many UNIX command line tools like sort and uniq. From the README:

The new repository contains just a few tools for working on JSON data. The goal is to let UNIX do most of the work. ☺

jcut is like cut(1) but understands named fields

jmap renames JSON fields

json2yaml reads JSON and writes YAML, which may be easier for some to read.

jsort is like sort(1) but -k names JSON fields

mysql2json reads mysql(1) batch files (-B flag) and writes JSON

]]>
Sleep Sort with POEtag:blogs.perl.org,2011:/users/rocco_caputo//563.17882011-05-19T19:34:29Z2011-05-19T15:20:50ZSleep sort is described in this silly 4chan thread. I don't guarantee work safety. It's essentially an insertion sort into time itself. A timer is created for each numeric value to sort, and the order in which they occur determines...Rocco Caputohttp://poe.perl.org/
Sleep sort is described in this silly 4chan thread. I don't guarantee work safety.

It's essentially an insertion sort into time itself. A timer is created for each numeric value to sort, and the order in which they occur determines the outcome.