|go ahead... be a heretic|
An Introduction to Literate Programming with perlWEBby adamcrussell (Hermit)
|on Jan 13, 2009 at 04:57 UTC||Need Help??|
In this Meditation I provide an overview of literate programming(LP) with perl. In the interest of not being too wordy I will omit much discussion of the theory of literate programming. There is an excellent article here by Mark-Jason Dominus which discusses literate programming in some detail. By not belaboring the more theoretical points what remains here is essentially a quickstart guide in LP using the perlWEB tool. Hopefully, with a short and practical introduction to LP the use of the technique may find some more widespread use. My goal with this Meditation is to remove the initial barrier to entry to using perlWEB. I found getting my first working example off the ground and to understand the main points of the tool took me longer than I would have liked!
LP is basically a method of writing code in which you write documentation and code in the same file(s). I became drawn to LP as I realized that it greatly reduced the amount of time I would later spend either re-educating myself about some old code of my own or explaining my code to later maintainers. Even with well written comments within the source files I found that LP provided so much more breadth and depth of information that the greater up front time investment was always well worth it. Here I will create a file based on the code posted to this node. This has the benefit of providing a concise example that displays many features of LP with perlWEB but has the drawback of not impressing you, the reader, with how much easier your life will be in maintaining and updating a significant codebase. Also, as with all well intentioned examples it is a little convoluted for the sake of exposition.
If the above code is in a file called example.w then the command
w2h example.w -o example.html
will create the documentation file that looks like this. Nice, isn't it! Imagine giving that to the developer responsible for maintaining your code! This is the sort of document I wish I started each job with! The process of creating that documentation from the LP source file is called WEAVE-ing. Now, to create the perl source file(TANGLE-ing) for the interpreter to actually run we need to use the command
w2p example.w -o example.pl
Here is what example.pl will look like:
The perlWEB documentation covers the full process of how the source file is assembled. Please do refer to it when you get a chance but for now we need only concern ourselves with a few key points:
• The perlWEB source file has a number of sections.
• The starred sections are major headings and we only have one. Most sections have a name but there may be any number of unnamed sections.
• Unnamed sections are the sections that begin with #p. There must be at least one unnamed section. I find it convenient to put it right in the beginning.
• At several points raw html is added to enhance the readability of the documentation.
Here is what I left out:
• change files
• file includes
• … and a ton of fiddly details. My goal here is to give a quickstart guide for the impatient but yet still diligent perl developer. I am not trying to re-write he perlWEB manual but simply try and make it more accessible.
Some final notes that I recorded while writing this:
0. I have been informed that he book Elements of Programming with Perl discusses literate programming with perl in Chapter 9. I do not own this book nor have I ever read the text itself. I have read excerpts on Amazon.com and have looked at the freely downloadable source code. From the author's file pqtangle.pdf it appears he discusses a system developed in the text that uses a syntax similar to noweb. noweb is a language agnostic literate programming tool which has many merits. However, for the purposes of this article I have focused on perlWEB. The main reason for this is that unlike noweb and many other literate programming tools perlWEB's weave output is in html as opposed to TeX or LaTeX and I believe that html is much more accessible for the majority of working developers than TeX or LaTeX. When one sees that most literate programming adherents are Math and Computer Science academics I think it lends credibility to the argument that the hurdle of learning TeX or LaTeX is sufficient to discourage more widespread adoption of these techniques.
1. At the first run of w2p I get the following error:
$ ./w2p temp.w
./w2p: line 29: /usr/lib/cpp: No such file or directory
If you have this problem the fix is easy... This is fixed by usingthe right path. On my machine the correct path is /usr/bin/cpp. perlWEB uses the C pre-processor for macro definitions.
2. Some users may be put off at the age of perlWEB. Please don't be! While originally written in 1997 they system is very stable and is holding up quite well. Here is the link for the perlWEB homepage.