NAME
Pod::Literate - Literate programming through POD, for general applications or specifications managed by AI/Copilot/Claude/ChatGPT
VERSION
Version 0.0.4
SYNOPSIS
podweave.pl Module.pod | pod2text
podtangle.pl Module.pod
perl -e 'use Module; ...'
DESCRIPTION
Literate programming naturally structures code based on its written specification. Traditionally this permitted organization of very large applications in languages that initially focused on single-file development, which slowly extended to multiple files used as basic imports. With the advance of projects spanning many directories and isolation into objects, and the propensity to author code with minimal comments and documentation, literate programming became an historical curiosity.
With AI/LLM tools focused on software development assistance, it is possible to leverage literate programming to build specifications for applications and interfaces. Given the natural-language focus of this approach, LLMs benefit from and can better maintain consistency with specifications. Code again becomes focused on small, isolated, well-tested goals that can be merged together to form larger systems.
These specifications can be processed in two ways. A tangle command permits coalescing all named sections into the final application. A weave operation generates the specification with all relevant visible elements. In Pod::Literate, the weave application is perlpod itself and its associated formatters (pod2man etc.).
Backwards Incompatibility
IMPORTANT: This is an early version. Monitor the version change logs for additional information about forthcoming functional changes.
- Spacing behaviors
-
Spacing behaviors of
=beginand=forhave been fixed/established in 0.0.4! - Section declaration versus addition
-
The warning/error behavior of
literate Nameversusliterate +Namemay change, be dependent on commandline flags, etc. - Unused sections
-
Unused sections may become failures, warnings, etc.
- Weave
-
Weave options and overall behaviors are subject to change.
FORMAT FEATURES
The module, Pod::Literate, is implemented using the formatting features of perlpod. At this time, either =begin or =for may be used to declare named sections of code. They have different end-of-line behaviors. Both declarations are visible when using the weave command, but perlpod will hide the =begin sections if weave is not used first.
begin and end
The begin and end command paragraphs are used to create named sections of code, and must appear in pairs:
=begin literate Descriptive name
...
=end literate
When processing the start of these blocks, a title attribute is set with the "Descriptive name" which is used to identify the target section into which the text contents will be stored. The begin/end is best suited for code blocks, such as complete subroutines or functions, because the final blank line before the =end will be included in the code. These sections will be hidden with plain perlpod, but are visible when using weave.
Notice, at this time, that the classic additive syntax for a named section is supported, in particular
=begin literate +Descriptive name
...
=end literate
but this is equivalent to the non-additive name. In particular, if sections appear more than once, the contents are always concatenated. (This is subject to change, additional warnings, etcetera).
for
The =for command paragraph may also be used to create named sections of code, and must appear paired with and ending for statement:
=for literate Descriptive name
...
=for literate .
The stand-alone period is mandatory to signal the end of content collection. The target section is still identified by the "Descriptive name". The for/for is best suited for referenced lines of code, one or multiple lines, because the final blank line before the ending =for will not be included in the code. These sections will be visible with plain perlpod, and are visible when using weave.
The additive syntax also works for sections created with =for.
Section names
Sections named in =begin and =for tags are limited only by perlpod functionality. Each name is referenced in code by placing it within commented identifiers as:
#< Descriptive name >#
Leading and trailing spaces are ignored, but otherwise only the sequence ># would be illegal in a name.
Vertical Spacing
The behavior of single and concatenated begin and for blocks differs with regards to blank lines. Blank lines appear
when after each reference between concatenations
using begin/end yes yes
using for/for no no
Consider this example:
=begin literate subs
sub AAA {
#< for lines >#
}
=end literate
=begin literate subs
sub BBB {
#< for lines >#
}
=end literate
=for literate for lines
# comment 1
=for literate .
=for literate for lines
# comment 2
=for literate .
The result of tangle will be:
sub AAA {
# comment 1
# comment 2
}
(blank line here)
sub BBB {
# comment 1
# comment 2
}
(blank line here)
For greater control, defined #< blank ># and place it as needed.
Horizontal Spacing
References are included verbatim where they appear, so begin/end blocks are typically not appropriate in the middle of lines. Consider
=begin literate example
if(#< begin inline >#) { #< for inline ># }
=end literate
=begin literate begin inline
begin line
=end literate
=for literate for inline
for line
=for literate .
The result of tangle will be:
if(begin line
) { for line }
Note that #< for inline >##< for inline ># will yield two references without an inside newline, but multiple, concatenated declarations of =for literate will still have a blank line between each.
This permits declarations such as
=for literate header
=head
=for literate .
to be used in cases such as #<header>#1 Title.
OUTPUT
An output filename may be specified via
=for literate:command target=Module.pm
Multiple targets may be specified by repeating the command, once for each output file. Each target filename must have a defined section =begin literate filename or =for literate filename. Relative and full path specifications are permitted.
Note that the weave command still produces single-file output and does not split documentation into multiple files.
The old syntax will be deprecated: =for literate target:Module.pm
TODO
The following are being considered. No particular priority order here.
- todo Weave command is required if the begin/for names are supposed to show up in the POD
-
The names are clear within the specification, but the generated POD doesn't contain the names. Presumably the generated pod would show something like
< Descriptive name > += ContentBasic functionality is provided in
weave, but functionality is still being decided. - todo Support
=for literate:command import=filename -
Documents may appear in sections, and one large POD can become difficult to manage. With a specialized weave command, it would be sensible to support imports.
- done Handle multiple output filenames
-
Multiple
target=filenamecalls can be made. - done First line indentation is removed, to match indentation at the point of reference
- done First line indentation applies to every line in the reference
- done Inline references
-
References within lines are expanded normally, with no terminal newline changes.
- todo Inline declaration
-
Support for
X<name>codeto declare single lines of code within a paragraph. - todo Detect/reject invalid sequences like begin/for, begin/begin, for title/for title
- done Investigate colon-prefixed
=for :literate commandfor the command strings. -
These are now explicitly rejected. These are meant to denote plain/POD paragraphs according to perlpodspec, which will require additional parsers. This syntax may be used to emit POD into the tangled result in the future.
- todo Blank code lines
-
Blank lines after subroutines have improved with updates to
=begin, but there are still cases where it may be worthwhile to support additional filtering instructions during tangling, or when sections are loaded.This may be entirely the responsibility of a later style tool, but it should be possible to get actual blank lines without having to put those blank lines around the reference. Maybe some
#nlor equivalent, which would still look nicer than some lengthy# blank line #type of comment.Another approach would be, since this is Perl POD, to permit enabling spaces around balanced blocks that are denoted, such as
sub. - todo Cross reference
-
Lexicographic index of all section names etc. (Page numbers seem irrelevant, is it just 1.2.3.4 style subsection numbering?). Possibly leverage `makeindex`, if available.
- todo Module pod
-
(This is possible/solved but not yet documented). How to denote pod that belongs with the output module?
- todo Tests
-
Generally tests will appear in different sections, but it's possible to write a specification where the tests are associated with each section. Unfortunately, for concatenated sections the tests might be more difficult to arrange prior to tangling.
- todo Reference wildcards
-
Support
#< Name.* >#to select all matching names, alphabetical order
SEE ALSO
* perlpod