\n21. Testing

Here we detail a few different ways that we could use literate programming to help the first bugbear of programming: testing.

\n21.1 Generating Common Test Environments

\n21.2 h5 Test Headings

\n21.3 Inline Eval Testing of Code Snippets

The ultimate in unit testing, we test a variety of pieces of the code immediately.

",{"_507":508,"_40":41,"_44":45,"_42":43,"_63":64,"_509":510,"_621":505},"previewContent","

\n \n
- \n Introduction\n
\n
\n I The Basics\n
- \n 1. What is literate programming?\n
- \n 2. LitPro\n
- \n 3. Semi-literate programming\n
- \n 4. Symphonic Programming\n
  - \n 4.1 Syntax\n
  - \n 4.2 Functions or reordering\n
  \n
- \n 5. Artistic programming\n
  - \n 5.1 Web\n
  \n
\n
\n II Cookbook\n
- \n 6. Constants\n
  - \n 6.1 Evaling\n
  - \n 6.2 Command producing constants\n
  \n
- \n 7. Eval\n
  - \n 7.1 Command Eval\n
  - \n 7.2 Command Async\n
  - \n 7.3 Directive Eval\n
  \n
- \n 8. Boiler Plate\n
  - \n 8.1 Repeated Use of Chunks\n
  - \n 8.2 Evaling\n
  - \n 8.3 Minors and Compiling\n
  \n
- \n 9. Making a Command\n
  - \n 9.1 Synch command\n
  - \n 9.2 Async command\n
  - \n 9.3 Plugins\n
  \n
- \n 10. Making a Directive\n
  - \n 10.1 Evaling to a Directive\n
  - \n 10.2 lprc.js Directives\n
  - \n 10.3 Plugins and Directives\n
  \n
- \n 11. Project Files\n
  - \n 11.1 Version\n
  - \n 11.2 NPM\n
  - \n 11.3 Readme\n
  - \n 11.4 gitignore\n
  \n
- \n 12. lprc.js\n
  - \n 12.1 Custom commands and directives\n
  - \n 12.2 Loading plugins\n
  - \n 12.3 Default arguments\n
  \n
- \n 13. Other Languages\n
  - \n 13.1 Hyphenated var names\n
  - \n 13.2 Space separated to JSON\n
  - \n 13.3 CSV to JSON\n
  - \n 13.4 Auto-prefixer\n
  - \n 13.5 SASS to CSS\n
  \n
- \n 14. Making a Plugin\n
  - \n 14.1 Independent\n
  - \n 14.2 Jade\n
  - \n 14.3 JSHint\n
  - \n 14.4 Markdown, PostCSS\n
  \n
- \n 15. Data Entry\n
  - \n 15.1 Reading CSV into Template\n
  - \n 15.2 Date/Time\n
  - \n 15.3 Pulling from web\n
  \n
- \n 16. Conditional Compiling\n
  - \n 16.1 Flags\n
  - \n 16.2 Conditional Syntax\n
  - \n 16.3 Multiple Compiles\n
  \n
- \n 17. Domain Specific Languages\n
  - \n 17.1 Math Algorithms\n
  - \n 17.2 Extra Markdownish\n
  \n
- \n 18. Making a Subcommand\n
- \n 19. Linting\n
- \n 20. h5 and h6 Headers\n
  - \n 20.1 Paths\n
  - \n 20.2 Collecting CSS\n
  \n
- \n 21. Testing\n
  - \n 21.1 Generating Common Test Environments\n
  - \n 21.2 h5 Test Headings\n
  - \n 21.3 Inline Eval Testing of Code Snippets\n
  \n
- \n 22. Documentation\n
- \n 23. Debugging\n
\n
\n III Web Projects\n
- \n 24. HTML\n
  - \n 24.1 Boilerplate\n
  - \n 24.2 Jade\n
  - \n 24.3 Markdown\n
  - \n 24.4 Template Runs\n
  - \n 24.5 Cheerio\n
  \n
- \n 25. JavaScript\n
  - \n 25.1 A Little Code\n
  - \n 25.2 Linting\n
  - \n 25.3 Testing\n
  - \n 25.4 h5\n
  - \n 25.5 Helpers\n
  - \n 25.6 Transpilers\n
  \n
- \n 26. CSS\n
  - \n 26.1 PostCSS\n
  - \n 26.2 SASS\n
  \n
- \n 27. Servers\n
  - \n 27.1 Making a Server\n
  - \n 27.2 Pushing Content to Server\n
  - \n 27.3 Pushing Content to S3\n
  - \n 27.4 Database managing\n
  \n
- \n 28. AWS Lambda\n
- \n 29. Writeweb\n
- \n 30. Static Sites\n
\n
\n IV Reference\n
- \n 31. A Complete and Full Syntax Specification\n
- \n 32. Directives\n
  - \n 32.1 LitPro Directives\n
  - \n 32.2 Literate Programming Directives\n
  \n
- \n 33. Commands\n
- \n 34. Subcommands\n
- \n 35. Command Line\n
- \n 36. Plugins\n
- \n 37. lprc.js\n
- \n 38. Compiling\n
\n
\n V The Literate Programs\n

Introduction

\n\n

This is a book that specifically covers the author’s tool for doing literate\nprogramming. The tool is freely available via npm, with source code available on github.

\n\n

The tool implements a version of Don Knuth’s idea of literate programming. The\nbasic idea is to write code for being read and maintained rather than for\nthe need of the computer. One can reorder code, cut up code into different\nsnippets, promote comments to a top level, and do arbitrary transformations to\nthe input text before outputting the code.

\n\n

This book covers both the idea and the tool. Most of it is about what this\nspecific tool does.

\n\n

Part I, which is The Basics, covers the 80% of needs and uses. It is a fairly\nsimple and straightforward concept. The freedom to break code up arbitrarily\nis quite nice and this part explains how to go about doing this.

\n\n

Part II details more about what I term “artistic programming”. This is very\nmuch concerned with arbitrary actions and transformations of the compilation\nphase. At its core, it takes input text, does some stuff to it, and gives an\noutput that is then arranged into the final code. The transformation is the\nartistic part, the assembling of small snippets is more of a symphonic part.

\n\n

Transformations opens a wide world of possibilities and Part II delves into\nvarious scenarios and how to deal with them. This is a bit of a cookbook\napproach.

\n\n

Part III focuses on this as a tool for the web environment. The web stack is a\nmess of different technologies, optimizations, and many files. The tool can\nhandle all of this and this is the place to explain it in detail.

\n\n

Part IV is a reference section. Every piece of syntax is\ndocumented, from the format to the commands, directives, and subcommands.

\n\n

Part V is not included, but links are provided to PDFs of the various literate\nprograms that make up this tool. Yes, the tool compiles itself. It lightly discusses the structure of the tools.

\n\n

A note on terminology. I use the term compile because this transforms source code from one thing to another. Often it will be transpiling, that is, transforming from one language to another on the same level of abstraction, but there is nothing inherent about the process that limits us to transpiling. You could set it up to generate machine code, if you really want to. You can read a little more about compiling vs. transpiling if you like.

\n\n\n\n

\nI The Basics

\n\n

What are we trying to do and how do we do it? This should be enough to get you going.

\n\n

What is literate programming?

\n\n

A brief description of the philosophy and history of this mode of programming.

\n\n

LitPro

\n\n

A description of the tool, hopefully enough to get started with it.

\n\n

Semi-literate programming

\n\n

The first step towards literate programming, this is where comments become elevated to be at least as important, if not more important, than the code. Essentially, comments are the default text mode and code must be initiated.

\n\n

Symphonic programming

\n\n

Humans do not think in the same way computers process. Respecting the order of human thought is what symphonic programming is about. We cut up the code in many pieces, scatter it around and then the program acts as a conductor to put it all together in a harmonious symphony of beautiful code.

\n\n

Artistic programming

\n\n

This is the full power of LitPro released. The bits of code can be processed in arbitrary ways. We are not bound by the dictates of the language and can craft the code in whatever elegant manner we wish to craft it. With great power comes the possibilty of making a mess. This is painting code on a canvas with the blending of the bits and pieces in ways that are very powerful.

\n\n\n

\n1. What is literate programming?

\n\n

Literate programming is a way of organizing code developed in the late ’70s by\nDonald Knuth. It allows one to interweave documentation and code snippets laid\nout in a way agnostic to the underlying language needs. That is, it fits the\nhuman need, not the computer need, for how something is organized and\nexplained.

\n\n

As a first approximation, literate programming allows one to explain the\npurpose of the code, how it fits in with the larger program, what this specific\nbit is supposed to do, and some non-obvious maneuvers in the code. The details\nof how, of course, can be left to well-written code, but the hope is that the\nprose and section headings allow one to navigate around to the interesting\nbits.

\n\n

This approximation is the elevation of comments out of code and into the\nprimary view with code descending into a secondary viewpoint.

\n\n

This is semi-literate programming and is the most often implemented view,\nbeing the easiest and fitting with the name “literate”.

\n\n

At the next level of understanding, it allows one to sculpt the code to fit\nthe human mind. The most interesting bits can be placed first. Or the overall\nstructure can be laid out first. Whatever makes more sense, it can be done\nthat way. Much like how a\nstory may be laid out in non-chronological order for maximum impact of the\nhuman reading it, so too does literate programming enable the organization of\ncode for maximal human understanding by shedding the dependency on what the\ncomputer requires for organization.

\n\n

Just as humans may disagree on rather a story is told well so to does this increase the potential conflicts between reader and author of code. It becomes dependent on the author to try and think in the perspective of the reader as to how to present it well enough to the expected audience. This is not an easy task.

\n\n

This is the level of arbitrary ordering of snippets. We can go even further\nand have arbitrary input and output files. That is, multiple literate program\nfiles can combine to make a single or multiple output files. This allows us to\nnot only reorganize code within a single file, but organize the code across\nthe project.

\n\n

We could, for example, use a literate program in web development in which some\nhtml widget, with its css and javascript, all live in a single literate\nprogram file but upon compiling, those pieces go to there separate various\ndestinations. We could also choose to do the opposite such as having javascript,\nsay, in its own literate program, but then inject it (or a small, crucial\nsubset of it) into the html file for performance reasons. We fit the\norganization of the project to the demands of the mental view of the project.

\n\n

Related to this is the idea of a central project management file. Compile that\nliterate program and it triggers the compilation of the entire project. But\nmore to the point, it would be the entry point, a sort of table-of-contents\nwith explanations, for the whole project. Instead of being limited to\nexpressive directory and file names, one can use arbitrary comments to reveal\na clear insight into the whole structure of the project.

\n\n

We could call this literate projecting. Or perhaps symphonic programming,\nthinking of it as conducting all the disparate pieces of code threaded\ntogether in a harmonious fashion.

\n\n

The third level is complete and arbitrary control of the code. At this stage,\nwe can run snippets through any process we want. We can write a JSON\ndescription of an object and then translate that into a language specific\nobject. We can have bits of markdown or pug and compile it into the same HTML\ndocument. We can create our own little mini-language for just that one bit of\nthe project to reduce the amount of code written and have the literate program\ncreate the final rendered version.

\n\n

We can also take almost common bits of code and programmatically change them\nas needed. This is a middle ground between copy-and-paste versus creating\nfunctions to implement common code.

\n\n

This third level is where the bulk of the effort of litpro was spent. It is\nnot hard to do the first two levels, particularly if syntax is not too worried\nabout. But the third opens an entire world of asynchronous text processing\nwith arbitrary tools. Here convenience is extremely important and, as anyone\nknows, the price of convenience is complexity.

\n\n

This level is perhaps described as artistic programming. It allows for an\nunconstrained canvas to paint the code.

\n\n

As we go up the levels, each one is increasingly more complex and potentially\ndangerous for the undisciplined. But it is also a big opportunity to learn\ndiscipline. There is nothing quite like making a mess to teach one discipline\nin coding.

\n\n\n

\n2. LitPro

\n\n

Here we briefly explain the tool that this book describes in detail.

\n\n

The idea of litpro is to write literate programs in markdown. This is not a\nnew idea. Markdown is a wonderfully simple format where paragraphs are normal\ntext and indented blocks (or fenced off blocks) are treated as code.

\n\n

Markdown has wide support and, in particular, GitHub supports viewing markdown\nquite nicely.

\n\n

Litpro uses the CommonMark variant. This is a highly\nspecified version with edge cases laid out in detail. Anything it considers a\nheading or a code block is what Litpro considers it to be. Some of the syntax\nchoices have been constrained by following this format, but for the most part,\nthese constraints have been most welcomed.

\n\n

Litpro is written in JavaScript. The command-line tool runs using node.js and can be installed using npm install -g litpro. This is good for explorations and initializations. Use it by using the command litpro filename.

\n\n

Any serious use of the tool for the project should have litpro, strictly versioned, as a\ndevelopment dependency in the package.json file and refer to it that way. When\ninstalled as a dependency, the command can be located from the top directory\nas node_modules/.bin/litpro

\n\n

To initiate a package.json file and put litpro as a dev dependency try

\n\n

npm init\nnpm install litpro --save-dev\n

\n\n\n\n

You can hook up scripts in the package.json file to make it easier to run.\nThere are also configuration options and a file that we will get into\neventually. We will also detail setting up a watch system to continuously\ncompile and test the development.

\n\n

Litpro is free and open source. Issue request are most welcome and you can\nfind its repository at litpro

\n\n

The command-line interface is a thin wrapper around a library which is\nplatform agnostic (hopefully). The hope is to one day have a browser based\nversion and the decoupling of the library from the command-line will be most useful to that end. The\nlibrary can be found at \nliterate-programming-lib

\n\n

There are also some plugins available. The convention is to call them litpro-...\nFor example litpro-jshint implements a jshint command for applying that\nlibrary to JavaScript code in order to find likely errors.

\n\n

But there is often very little that needs to be done to use an external node module. Thus, there is not a need to have very many plugins. Instead, we can write the code needed out in the configuration file.

\n\n

There is one other version which is called \nliterate-programming\nThis was the original client, but it has been completely replaced with litpro powering it. It does differ from litpro in that it comes with “batteries included” for web development. While it is more than impossible to include much of what is used in web development, this does attempt to include some of those modules found most useful by the author. At the present time, they include a markdown compiler, jshint, some beautifiers and some minifiers, pug (formerly jade), and postcss.

\n\n

Much of the inspiration for this tool comes from web development. The number\nof different languages and tools involved in web development coupled with best\npractices makes web development quite difficult. The hope is that this tool\nmakes that easier.

\n\n

While targeted at web development, it is by no means the only use. It is\nlanguage agnostic and can be used for doing any type of text creation. It\ntakes in markdown files and produces text files. Some languages need much more\nfrom an environment (such as code completion) which is orthogonal to this\nissue.

\n\n

One possible solution to this is to use named language types for fenced code\nblocks and, if the editor is made aware of it, using that to do code\ncompletion, at least of the canonical language features.

\n\n\n

\n3. Semi-literate programming

\n\n

Here we explain the simplest use of litpro: elevating comments to readable\nparagraphs.

\n\n

The idea here is quite simple. Write paragraphs for comments. Then use either\nindented blocks or code fences to write code blocks.

\n\n

Here is a simple example:

\n\n

# Saying Hi\n\nWe want to write a little javascript command that says hi, waits one second,\nand then says bye. We will save it in [teens.js](# \"save:\")\n\nGreetings are great, right?\n\n    console.log(\"hi\");\n\nTimer is in milliseconds, so 1000. We'll call the function `bye` defined\nelsewhere\n\n    setTimeout(bye, 1000);\n\nAnd now let's define the bye function. For no apparent reason, we use a named\nfence block. Hey, maybe we'll get some syntax highlighting!\n\n```js\nfunction bye () {\n    console.log(\"bye\");\n}\n```\n\nHey, we're all done!\n

\n\n\n\n

With that text saved in a file, we can run litpro on it and it should produce\nthe file teens.js consisting of

\n\n

console.log(\"hi\");\nsetTimeout(bye, 1000);\nfunction bye () {\n    console.log(\"bye\");\n}\n

\n\n\n\n

This uses the save directive which is, at its simplest, [filename](# \"save:\")\nwhere filename is where to save the file. The hash symbol says to use the current section; we’ll see later how to reference other sections.

\n\n\n

\n4. Symphonic Programming

\n\n

Here we want to explore reordering code. And to discuss it, let’s first talk\nabout this.

\n\n

a, b ....\nif (crazy) {\n    // lots of lines\n    c = a;\n} else if (slightlyCrazy) {\n    // fewer lines\n    c = b;\n} else {\n    // very few lines\n    c = d;\n}\n

\n\n\n\n

So we have a conditional with some complicated bodies. And maybe we want to\nmove those complications elsewhere to make it easier to understand the\nconditional flow. Typically, we would only have functions to do that role:

\n\n

a, b, ...\nif (crazy) {\n    c = lots(a, b);\n} else if (slightlyCrazy) {\n    c = fewer(a, b); \n} else {\n    c = few(a, b);\n}\n\nfunction lots (a, b) {\n    // lots of lines\n    return a;\n} \n\nfunction fewer(a,b) {\n    // fewer lines\n    return b;\n} \n\nfunction few(a,b) {\n    // very few lines\n    return d;\n}\n

\n\n\n\n

That works. But notice that we have introduced functions solely for the\nconvenience of human reading. It adds in the complexity of new scopes and makes\nit harder to deal with error conditions effectively. It also means we never get\nto see the compiled code in its context.

\n\n

In contrast, we can do the following with litpro.

\n\n

a, b ....\nif (crazy) {\n    _\"lots\"\n    c = a;\n} else if (slightlyCrazy) {\n    _\"fewer\"\n    c = b;\n} else {\n    _\"few\"\n    c = d;\n}\n\n## Lots\n\nHere we ...\n    \n    //lots of lines\n\n## Fewer\n\nAnd with less code we do \n\n    // fewer lines\n\n## Few\n   \n    // very few lines\n

\n\n\n\n

This will compile to the first block. It allows us to see in the literate\nprogram the outline of that section and see the other bits separated. But if we\nwant to see all the context together as the computer sees it, we can do that as\nwell. We also do not lose the surrounding scope or placement in the flow. These\nare powerful tools at times.

\n\n

\n4.1 Syntax

\n\n

The syntax for different blocks, at its simplest, is a header block making a\nnew section and then referencing that section with _\"section name\" in a\ncode block. For example,

\n\n

Some text\n\n## Awesome details-jack\n\nWe have some awesome code\n\n    Yay      \n\n but what? \n\n ```\n yeah\n \n ```\n\n ## Importing\n\n Here we put in the awesome\n\n    So jack says\n\n    _\"awesome details-jack\"\n\n    And we get what we want\n

\n\n\n\n

The above snippet will create

\n\n

    So jack says\n    \n    Yay\n    yeah\n    \n\n    And we get what we want\n

\n\n\n\n

Note that for blank lines, if you want trailing or leading newline from a code\nblock, you need to use the fenced blocks.

\n\n

Some symbols are allowed in the heading. Given how it is used in the syntax,\npipes are not allowed and quotes can lead to conflicts (obviously ## \"Quote\"\nhas problems with _\"\"quote\"\" but should be fine with _'\"Quote\"'

\n\n

This syntax works pretty well, but there are a couple of more tricks to learn.\nIn particular, colons are not allowed in headings either\nas they have been co-opted for minor blocks, discussed below.

\n\n

The available markdown header syntaxes are those that convert into h1 to h4 headers, namely \n#, ##, ###, #### or either of the underline heading syntax. Those headers become references to the code in their blocks. h5 and h6\nheaders are reserved for something else which is discussed later.

\n\n

References should be unique. If you reuse the same reference name (the same h1 to h4 header twice in the same file), then it will concatenate the blocks. h5 and h6 headers can be repeated without them being combined, as will be discussed later.

\n\n

One can use the same reference as many times as one likes.

\n\n

One can use any of the quotes (\", ', `) to start a substitution, just use the same quote to end.

\n\n

Minor blocks

\n\n

A minor block is designed for little snippets that seem too minor to create\nanother section heading, but that one wants to move out of the way anyway. In\na markdown toc, these will not appear nor do they need to be unique between different sections though they should be unique within one section.

\n\n

A minor block is initiated with either a link whose title starts with a colon\nor one whose target is completely empty. Let’s assume this is in section\nbob.

\n\n

[jane](# \":\") would create reference bob:jane while\n[jack 2]() would create reference bob:jack 2

\n\n

Within section bob, we can reference it as \":jane\" or \":jack 2\" and\noutside of bob, we need the full syntax of \"bob:jane\" and \"bob:jack 2\"

\n\n

We can also do a save directive using section names as such \n[whatever](#:jane \"save:\") if we are in the bob section or\n[whatever](#bob:jane \"save:\") if not.

\n\n

This works quite nicely (for headers, not minors) in terms of being an actual link when viewed on GitHub for on-minor references. For example, [whatever](#bob-is-cool \"save:\") will save the section “Bob is cool” and link to it.

\n\n

Other literate program files

\n\n

To use other literate program files, we use the load directive. We then use a\ndouble colon syntax to refer to it. Let’s assume we have a file called\ncool.md. Then we can load it in a litpro document using \n[great](cool.md \"load:\") and then reference section bob:jane in it using \n_\"great::bob:jane\" The load syntax has the alias as the linkname (bit in\nsquare brackets) but it can be omitted. In either case, the filename itself\ncan be referenced. That is, in the above example we can also use\n_\"cool.md::jane\"

\n\n

Full Example

\n\n

Here we have a full example with the different syntaxes being used. We will\nload from two files and save to three.

\n\n

load.md is the main entry point. One would compile it with litpro -s . load.md The -s says to look for any other literate document to be loaded in the current directory; the default is src.

\n\n

# Full HTML\n\nHere we are building an HTML page. We will use a\n[widget](load2.md \"load:\") that comes from another literate program. \n\n    <html>\n        <head>\n            _\"widget::files link\"\n        </head>\n        <body>\n            <h2> Widgets for everybody!</h2>\n            _\"sp-load2.md::html:top\"\n            <p> snuck something in! </p>\n            _\"widget::html:bottom\"\n        </body>\n    </html>\n\n[full.html](# \"save:\")\n

\n\n\n\n

The above code loads up load2.md which has some nice bits in it.

\n\n

# Widget\n\nHere we define a widget. This widget will be amazing!\n\nWe will save two files from here \n\n* [widget.js](#js \"save:\")\n* [widget.css](#css-for-widget \"save:\")\n\n## Files link\n\nThis is the loading tags for our pages\n\n    <link rel=\"stylesheet\" href=\"widget.css\" />\n    <script src=\"widget.js\"></script>\n\n## HTML\n\nHere we put the html for our widget. We have a top and a bottom. The top\ncontains the div and a heading.  The minor block syntax can be either of the\nbelow. \n\n[top]()\n\n    <div class=\"widget\">\n        <h2>Click a button</h2>\n\n[bottom](# \":\")\n\n    <button>Awesome!</button>\n    </div>\n\n## JS\n\nWhen the button is clicked, we add the big class to the h2 element in the\nwidget \n\n    document.addEventListener(\"DOMContentLoaded\", function () {\n        _\":add click\"\n    });\n   \n[add click]()\n\nHere we add a click listener to the button. It should add a class to make the\ntext big and then one second later remove it.\n\n    var button = document.querySelector(\".widget button\");\n    var h2 = document.querySelector(\".widget h2\").classList;\n    button.addEventListener(\"click\", function () {\n        h2.add(\"big\");\n        setTimeout(_\":remove class\", 1000);\n    });\n\n[remove class]()\n\nThis removes the big class\n\n    function () {\n        h2.remove(\"big\");\n    }\n\n## CSS for widget\n\nWe want the h2 to have a red background!\n\n    .widget h2 {\n        background-color : red;\n    }\n\n    .big {\n        font-size: 5em;\n    }\n

\n\n\n\n

When compiled, we get widget.js:

\n\n

document.addEventListener(\"DOMContentLoaded\", function () {\n    var button = document.querySelector(\".widget button\");\n    var h2 = document.querySelector(\".widget h2\").classList;\n    button.addEventListener(\"click\", function () {\n        h2.add(\"big\");\n        setTimeout(function () {\n            h2.remove(\"big\");\n        }, 1000);\n    });\n});\n

\n\n\n\n

widget.css:

\n\n

.widget h2 {\n    background-color : red;\n}\n\n.big {\n    font-size: 5em;\n}\n

\n\n\n\n

and full.html:

\n\n

<html>\n    <head>\n        <link rel=\"stylesheet\" href=\"widget.css\" />\n        <script src=\"widget.js\"></script>\n    </head>\n    <body>\n        <h2> Widgets for everybody!</h2>\n        <div class=\"widget\">\n            <h2>Click a button</h2>\n        <p> snuck something in! </p>\n        <button>Awesome!</button>\n        </div>\n    </body>\n</html>\n

\n\n\n\n

\n4.2 Functions or reordering

\n\n

A common point of debate is whether this reordering is significant. The argument\nis that in modern languages, the ability to define functions after they have been called allows one to shift the code elsewhere.

\n\n

While true, this muddies the role of functions a bit. Functions are best used\nto be repeated bits of code that are called over and over. In old JavaScript,\nfunctions are also the only way to have scoped variables, but with the let\nkeyword, that has changed. Both are considerations for the computer and are\ngood reasons to use functions.

\n\n

But to use functions solely for human readable purposes at the expense of\nincreased complexity and cognitive load seems like a poor trade. Reordering\nusing literate programming allows one complete freedom in how to cut up the\ncode without any extra programming complexity. There is no wrestling with\nscope because of that reordering. There is no increased levels of redirection\nnor restrictions from redirecting from within the local code. It simply shifts\nthe placement for the sole purpose of humans reading the code.

\n\n

It is separation of concerns at its best. We have computer needs and we have\nhuman needs. We need to cater to both. Most paradigms try to balance the two\nneeds simultaneously with various costs and trade-offs. This approach allows us\nto satisfy both constituents with the small price of an extra compile (or\ntranspile) step.

\n\n\n

\n5. Artistic programming

\n\n

And so we reach the third and final level of our journey. The other two levels\nare pretty much complete in explaining them and how to use them. What follows\nfor the rest of this tome is all about the third level.

\n\n

The third level is the shedding of constraints. We take those snippets of code\nfrom the second level and we run them through code transformations. This\nenables us to do just about anything. Even more, we can call out to external\nprograms, feeding the snippets in as standard input and receiving the output\nas the next form of the snippet.

\n\n

This is the level of complete artistry. We can write little mini-languages to\nmake efficient input. We can use a wide variety of text transformations of one\nlanguage to the next all smoothly in the code. We can weave in user-end documentation, tests, sanity checks, compile contexts, and whatever else we can dream of, to make the job of coding, and all of its ancillary tasks, efficient and enjoyable.

\n\n

The basic command syntax uses pipe syntax. Instead of just a reference,\nsuch as _\"name\", we can pipe the incoming text into a command, or series of\ncommands, such as _\"name | cat awesome, _\"dude\" | sub A, b\". This would\ntake the text in the reference name and send it through the command cat which\nconcatenates stuff together. In particular it would join the incoming text\nwith awesome and the stuff in the dude section. Then that resulting text\ngoes through the sub command and all instances of A get replaced with b.\nNote that section names can be referenced in the command arguments.

\n\n

Sub

\n\n

To start with, let’s say we want to create functions for the arithmetic\noperators. That is, we want to be able to write add(4, 5) instead of 4+5.\nIn JavaScript, we could do

\n\n

var add = function (a, b) {\n    return a + b;\n}\n

\n\n\n\n

And that would be fine. We could then do that for subtraction, multiplication,\nand division. But that is a bit repetitive. So instead we can do

\n\n

# Operators\n\nWe want to convert the operators to functions.\n\nWe start with a basic form using addition\n\n    var OP = function (a, b) {\n        return a ?? b;\n    }\n\n When done we will save it in [ops.js](#math-ops \"save:\")\n\n## Math ops\n\nLet's create the operators\n\n    _\"operators| sub OP, add, ??, +\"\n    _\"operators| sub OP, mul, ??, *\"\n    _\"operators| sub OP, div, ??, /\"\n    _\"operators| sub OP, sub, ??, -\"\n

\n\n\n\n

And that generates the following in a file called ops.js.

\n\n

var add = function (a, b) {\n    return a + b;\n}\nvar mul = function (a, b) {\n    return a * b;\n}\nvar div = function (a, b) {\n    return a / b;\n}\nvar sub = function (a, b) {\n    return a - b;\n}\n

\n\n\n\n

This is not that exciting of an example. And there are a number of ways we\ncould have approached this with a simple copy and paste being one of them. Indeed,\nthe four lines of litpro code is copy and pasted (it is also possible to run\nsome custom code to do this more elegantly, but this is a simple\nintroduction).

\n\n

But you may wonder what is the advantage? The creative effort is about the\nsame level, but now all four are dependent on each other. This may be good, it\nmay not be good. It is good if you later decide to modify this. For example,\nyou may want to check that the operators are numbers. Or you may want to round\nthe result or cast it into some other form. By modifying the originating\nfunction, we get all of them modified at once. That is, the benefit is in the\nmaintenance.

\n\n

The downside is that they are coupled. So, for example if we want to inject a\ntest for division by zero, we need to add something to facilitate that. One\nsolution is to put in a comment line that gets replaced with what you need.

\n\n

# Operators\n\nWe want to convert the operators to functions.\n\nThe ?? will be replaced with operator symbols. We check for something to be a\nnumber and then do the computation. This is not really necessary nor perhaps\nthe best to do it, but there you have it.\n\n    var OP = function (a, b) {\n        if (Number.isNumber(a) && Number.isNumber(b) ) { \n            //rep\n            return a ?? b;\n        } else {\n            return NaN;\n        }\n    }\n\n When done we will save it in [ops2.js](#math-ops \"save:\")\n\n## Math ops\n\nLet's create the operators\n\n    _\"operators| sub OP, add, ??, +\"\n    _\"operators| sub OP, mul, ??, *\"\n    _\"operators| sub OP, div, ??, /, //rep, _\"division by zero\" \"\n    _\"operators| sub OP, sub, ??, -\"\n\n## Division by zero\n\nThe division by zero is so bad so let's deal it. Let's be bad mathematical\npeople and give some values of oo, -oo, and 1\n\n    if (b === 0) {\n        if (a > 0) {\n            return Infinity;\n        } else if (a < 0) {\n            return -Infinity;\n        } else {\n            return 1;\n        }\n    }\n

\n\n\n\n

Turning into:

\n\n

var add = function (a, b) {\n    if (Number.isNumber(a) && Number.isNumber(b) ) { \n        //rep\n        return a + b;\n    } else {\n        return NaN;\n    }\n}\nvar mul = function (a, b) {\n    if (Number.isNumber(a) && Number.isNumber(b) ) { \n        //rep\n        return a * b;\n    } else {\n        return NaN;\n    }\n}\nvar div = function (a, b) {\n    if (Number.isNumber(a) && Number.isNumber(b) ) { \n        if (b === 0) {\n            if (a > 0) {\n                return Infinity;\n            } else if (a < 0) {\n                return -Infinity;\n            } else {\n                return 1;\n            }\n        }\n        return a / b;\n    } else {\n        return NaN;\n    }\n}\nvar sub = function (a, b) {\n    if (Number.isNumber(a) && Number.isNumber(b) ) { \n        //rep\n        return a - b;\n    } else {\n        return NaN;\n    }\n}\n

\n\n\n\n

This could easily become cumbersome. As is generally true with this style of\nprogramming, it is a matter of artistic choice as to which is the most useful\nand clear in any given situation. It is likely to evolve over time just as\nrepeating similar code often evolves into pulling it out to functions. This\nis just one of the stops along the way.

\n\n

\n5.1 Web

\n\n

As another example, let’s say we are creating a web page. We want to have the\ncontent written in markdown, but we want to create the structure in pug (formerly the jade language).\nLet’s presume that the commands to convert them are md and pug,\nrespectively.

\n\n

# Webpage\n\nWe are going to make a web page. \n\n[web.html](#structure \"save:|log | jade | compile structure \")\n\n## Structure\n\nWe use the HTML5 elements of nav, article and aside in their appropriate\nroles. The nav is very lame. \n\n    nav\n        .left Click\n        .right Clack\n\n    article \\_\":content |md \"\n\n    aside \\_\"announcements |md \"\n\n    script \\_\"js stuff | jshint \"\n\n[content]() \n\nHere we have some great body content\n\n    # Best Webs Ever\n\n    We have the best webs **ever**. \n\n    ## Silk\n\n    Yeah, we got spider silk. [Kevlar strength](kevlar.html). Real cool.\n\n\n### Announcements\n\nWhatever we want to say\n\n    _Open Now!_ \n\n## js Stuff\n\nJust some random javascript. The jshint will check it for errors and such. \n\n    var a, b; \n    if (a = b) {\n        a = 2;\n    } else {\n        // never reached;\n    }\n\nJshint just loves it when one uses assignment instead of equality testing in a\nboolean expression. \n\nNote that jshint still allows it to be built. It will just give a warning on\nthe command line.\n

\n\n\n\n

This yields

\n\n

<nav>\n  <div class=\"left\">Click</div>\n  <div class=\"right\">Clack</div>\n</nav>\n<article><h1>Best Webs Ever</h1>\n<p>We have the best webs <strong>ever</strong>.</p>\n<h2>Silk</h2>\n<p>Yeah, we got spider silk. <a href=\"kevlar.html\">Kevlar strength</a>. Real coo\\\nl.</p>\n</article>\n<aside><p><em>Open Now!</em></p>\n</aside>\n<script>var a, b; \nif (a = b) {\n    a = 2;\n} else {\n    // never reached;\n}</script>\n

\n\n\n\n

The easiest way to run this is with literate-programming which has both markdown and pug included.

\n\n

But to run this with litpro, one needs to use the lprc.js file that defines these commands.\nThere are other methods that we’ll discuss later, but this is perhaps the most useful method.

\n\n

The lprc.js file requires the modules markdown-it and pug. We also\ninclude jshint which was done to check the script that we snuck in there.

\n\n

module.exports = function (Folder, args) {\n\n    if (args.file.length === 0) {\n        args.file = [\"web.md\"];\n    }\n\n\n    if (!Folder.prototype.local) {\n        Folder.prototype.local = {};\n    }\n\n    require('litpro-jshint')(Folder, args);\n\n    var jade = require('pug');\n    \n    Folder.sync(\"pug\" , function (code, args) {\n        options = args.join(\",\").trim();\n        if (options) {\n            options = JSON.parse(options);\n        } else {\n            options = {'pretty':true};\n        }\n        return jade.render(code, options); \n    });\n    \n    var md = require('markdown-it')({\n        html:true,\n        linkify:true\n    });\n    \n    \n    Folder.prototype.local.md = md; \n    \n    Folder.sync( \"md\", function (code, args) {\n        return  md.render(code);\n    });\n\n};\n

\n\n\n\n

We will discuss a lot of what is going on in this example as time goes on. But\nnotice how we can cut up our assembly of the material, run them through\ncommands, and get a nice compiled output.

\n\n

The backslashes are escaping the substitution in the first round as mixing\npug with compiled HTML content does not lead to good results. So we compile\nthe pug and then when that is ready, we call the compile command to run that\nthrough our standard compiler. In this example, we need to include the\nstructure named section as the overarching section.

\n\n\n

\nII Cookbook

\n\n

This is where we do a variety of specific examples of use. It mainly focuses\non examples from the web stack. In particular, the programming is almost\nentirely JavaScript.

\n\n

Constants

\n\n

We can define constants once with explanations and then put them into whatever\nfiles need them.

\n\n

Eval

\n\n

How to run some JavaScript

\n\n

Boilerplate

\n\n

If you have need of boilerplate, then we can do that with some substitutions\nfor templating it as well.

\n\n

Making a Command

\n\n

Commands are very useful. This is how to make them in a literate program.

\n\n

Making a Directive

\n\n

Inline custom directives are not that useful, but it can be insightful in\ngoing towards making plugins.

\n\n

Project Files

\n\n

Often there are other files needing managing for a project other than just\ncode. For example, .gitignore, readme, package.json, … These can all live\nin a single literate programming document that generates these files. It could\nalso be setup to have variables that you define once and then use when needed,\nsuch as the version number.

\n\n

Making a lprc.js file

\n\n

What constitutes a lprc.js file. This is where directives and commands are\nideally added, either directly or from plugins.

\n\n

Other languages

\n\n

If you want to write in your own style or language or whatever, it can do that\nas well. Write in a way comfortable to you and have it compile it into any\ntarget language.

\n\n

Making a Plugin

\n\n

Making a plugin leads to good consistent behavior.

\n\n

Data Entry

\n\n

Dealing with little bits of data is a difficult problem. Here we look at\ninline data entry using a quick split style as well as reading in data from an\nexternal file. This pertains more to generating written output, then code\nitself, but it could be needed there as well such as if you want to pull in\nsecrets from a file outside of the repo and put it in the compiled code that\nis also stored outside of the repo.

\n\n

Conditional Compiling

\n\n

We may want to do one thing or another depending on the compilation context,\ne.g., development vs production though one can often do both at the same time,\nwith multiple output targets.

\n\n

Domain Specific Languages

\n\n

We can write full blown domain specific languages and have them translated at\nbuild time. Or you can use standard languages that get transformed, such as\nmarkdown into html.

\n\n

Making a Subcommand

\n\n

These allow for doing complex actions in arguments. These are different from\ncommands that expect to be a part of a pipe flow.

\n\n

Linting

\n\n

We can lint pieces of our code. It would even be possible to lint the pieces\nin isolation to see what shared variables might pop up.

\n\n

h5 and h6 Headers

\n\n

These are headers that generate path-escaped references using the most recent\nmain block reference as the root path. These sections can not only be useful\nfor commonly named parts, but can also have custom behavior automatically\nacting on the parts.

\n\n

Testing

\n\n

Testing should be easy. Here we give a strategy for testing little bits of\ncode (unit testing) as well as testing the combined pieces (integrated\ntesting).

\n\n

Having fake data specified as well as expected output is also easy.

\n\n

Documentation

\n\n

While literate programming is designed to be the documentation for the\nmaintenance programmer, there is still the little issue of user documentation.\nWhile that may call for a separate document, it could be included in the same\nliterate program as well using the h5 and h6 mechanism, keeping it with the\ncode.

\n\n

Debugging

\n\n

Debugging can be supported by conditional commands.

\n\n\n

\n6. Constants

\n\n

Let’s say we want to put constants at the top of a file.

\n\n

\n6.1 Evaling

\n\n

\n6.2 Command producing constants

\n\n\n

\n7. Eval

\n\n

Being able to run arbitrary code is a powerful tool. It helps in doing quick debugging as well as quick prototyping of an effect.

\n\n

\n7.1 Command Eval

\n\n

\n7.2 Command Async

\n\n

\n7.3 Directive Eval

\n\n\n

\n8. Boiler Plate

\n\n

A few examples of doing boiler plate in a better way.

\n\n

\n8.1 Repeated Use of Chunks

\n\n

You can use the same chunk multiple times.

\n\n

\n8.2 Evaling

\n\n

\n8.3 Minors and Compiling

\n\n\n

\n9. Making a Command

\n\n

Commands are extremely useful in sculpting the code. You can make your own commands

\n\n

\n9.1 Synch command

\n\n

\n9.2 Async command

\n\n

\n9.3 Plugins

\n\n\n

\n10. Making a Directive

\n\n

Directives are very powerful. They get invoked when they are encountered which means that defining directives in a document is less useful (and such definitions need to come first). Still, this is a good exercise in moving towards defining directives as part of a plugin.

\n\n

\n10.1 Evaling to a Directive

\n\n

\n10.2 lprc.js Directives

\n\n

\n10.3 Plugins and Directives

\n\n\n

\n11. Project Files

\n\n

Many projects need a variety of files, not just code. Configurations are often in their own little files, even git has a file of gitignore that you might want to have around. It is possible to generate these files with litpro document and it may allow for easier creation and maintenance of such files.

\n\n

\n11.1 Version

\n\n

\n11.2 NPM

\n\n

\n11.3 Readme

\n\n

\n11.4 gitignore

\n\n\n

\n12. lprc.js

\n\n

This is the configuration file for a literate programming file. What can it do and what should it do?

\n\n

\n12.1 Custom commands and directives

\n\n

\n12.2 Loading plugins

\n\n

\n12.3 Default arguments

\n\n\n

\n13. Other Languages

\n\n

Sometimes I just want to speak in another dialect. What can LitPro do for me?

\n\n

\n13.1 Hyphenated var names

\n\n

\n13.2 Space separated to JSON

\n\n

\n13.3 CSV to JSON

\n\n

\n13.4 Auto-prefixer

\n\n

\n13.5 SASS to CSS

\n\n

??\nExample: using hyphens for spaces in javascript.

\n\n

Example: math algorithm

\n\n\n

\n14. Making a Plugin

\n\n

Eventually, all good tools need a lot of plugins to be considered successful. So start writing them!

\n\n

Most plugins are just a thin layer of wrapping over someone else’s carefully written plugin.

\n\n

We’ll do a few case studies of plugins

\n\n

\n14.1 Independent

\n\n

Using nothing, creating whatever.

\n\n

\n14.2 Jade

\n\n

Very simple

\n\n

\n14.3 JSHint

\n\n

A little bit harder, also trying to shoehorn config details into the plugin

\n\n

\n14.4 Markdown, PostCSS

\n\n

Plugins of markdown-it and using them

\n\n\n

\n15. Data Entry

\n\n

Getting data to its right place.

\n\n

\n15.1 Reading CSV into Template

\n\n

\n15.2 Date/Time

\n\n

both js and command line

\n\n

\n15.3 Pulling from web

\n\n\n

\n16. Conditional Compiling

\n\n

We can set flags for which environment is being run and this can cause different things to happen. For example, stripping debugging and testing code out of the build if it is production.

\n\n

\n16.1 Flags

\n\n

\n16.2 Conditional Syntax

\n\n

\n16.3 Multiple Compiles

\n\n\n

\n17. Domain Specific Languages

\n\n

This is an interesting area of use. We could have some general purpose code created from very small little languages. They might be highly constrained and limited, but perhaps sufficient for a project.

\n\n

\n17.1 Math Algorithms

\n\n

\n17.2 Extra Markdownish

\n\n\n

\n18. Making a Subcommand

\n\n

This is about exploring the mysterious world of subcommands.

\n\n\n

\n19. Linting

\n\n

Linting little pieces of code.

\n\n\n

\n20. h5 and h6 Headers

\n\n

These headers create a path-like structure from the last major section. This allows for common headers that can have interesting stuff happening to them.

\n\n

\n20.1 Paths

\n\n

\n20.2 Collecting CSS

\n\n\n

\n21. Testing

\n\n

Here we detail a few different ways that we could use literate programming to help the first bugbear of programming: testing.

\n\n

\n21.1 Generating Common Test Environments

\n\n

\n21.2 h5 Test Headings

\n\n

\n21.3 Inline Eval Testing of Code Snippets

\n\n

The ultimate in unit testing, we test a variety of pieces of the code immediately.

\n\n\n

\n22. Documentation

\n\n

Strategies for dealing with the second bugbear of programming: documentation for end users. This is different than documenting for maintenance uses which is what literate programming does best. Here we try to use are tools to make writing end user documentation robust and, most importantly, maintainable. It will follow a similar flow to testing.

\n\n\n

\n23. Debugging

\n\n

Our third and final bugbear is debugging. How can we use these tools to pepper development code with debugger stuff easily while keeping code clean for production?

\n\n\n

\nIII Web Projects

\n\n

The web is a particularly beautiful hot mess of tech stacks.

\n\n

We first detail various useful parts related to particular pieces of the\nstack.

\n\n

HTML

\n\n

This is a language that covers both the structure of a webpage and the\ncontent. Combining the tasks lead to a language that is a bit painful to\nwrite out.

\n\n

Litpro can help by offering boiler plate with subbing in of content. The\nboiler plate can be written in a structure focused (templating) language, such\nas pug, and the content can be written in markdown. Litpro can then transform\nand stitch together it all.

\n\n

JS

\n\n

Litpro is written in JavaScript and thus many of the common commands turn out\nto be quite useful in writing JavaScript.

\n\n

There are a few very specific ways that can be very helpful.

\n\n

The first is using JSHint. You can take any block of JS code and feed it into\nJSHint to get a log output of issues and problems. It is as easy as js code |\njshintassuming you have installed litpro-jshint or using the full\nliterate-programming.

\n\n

Another handy command, in all versions, is js-string. This takes the text\nand breaks it by newline and outputs text suitable for creating a string in JS\ncode that returns that text. This enables one to, say, write some HTML for\ntemplating and put it in there. In newer versions of JS, one can have\nmulti-line strings, but this works for all versions of JS.

\n\n

There is also the ife command which creates an immediate function execution\naround the incoming text. This is again less necessary in the newer variants,\nbut it can still be handy for closures or if one does not want to use the new\nlet version of var.

\n\n

CSS

\n\n

This is a language with great potential, but it is hampered by differing\nbrowser specs. While that has greatly improved, it is best to let a tool\nhandle the differences. There can also be a lot of repetition at times. Both\nof these things Litpro can help with.

\n\n

One can take any incoming text and run it through a preprocessor such as SASS\nor run it through PostCSS and the wonderful auto-prefixer. The latter is\nincluded in literate-programming.

\n\n

One can also use some snippets or the caps command to help ease some of the\nmore verbose parts of the syntax.

\n\n

One can also do variables with the substitutions. This may help avoid using\nsomething like SASS entirely.

\n\n

Tidy and Minify

\n\n

Literate-programming includes tools for formatting the above three languages,\neither to make them pretty (tidy) or to reduce their size (minify).

\n\n

One can have multiple directories generated say, one for development and one\nfor production. Using the cd command, this is often quite convenient.

\n\n

It is also possible to include some code in one, but not the other. Again,\nthis comes to transforming the blocks of text.

\n\n

Servers

\n\n

In addition to the static content served up, one often needs dynamic\ninteractions and thus writing a server and using a database comes up.

\n\n

The same tools above for writing JavaScript are just as helpful with node. In\nparticular, having development and production splits can be very useful.

\n\n

There is also the database. For a database, one has the language of the server\nand the database language. Plus, one may have schemas to guide the\ndevelopment, perhaps even a specific language.

\n\n

This tool may help with that by offering a mapping between the languages.\nUnlike the magic tools of ORM, this tool does the conversion and allows one to\nsee the output in context.

\n\n

AWS

\n\n

AWS is an amazing land of tools. It is all very piecemeal and run by resource\npolicies. There are a lot of configurations to handle and updating requires a\nprocess.

\n\n

It seems like a perfect place for a text transformation tool to run.

\n\n

writeweb

\n\n

This is an attempt by the author to create automatic compiling of literate\nprograms. Due to their insecure nature, this would be something that would\nneed to be installed by an individual (or team).

\n\n

static site

\n\n

This is where we show how to setup a static site, one in which the content and\nindividual page styling/js is done in a directory of files that are not\nliterate programs, but a literate program processes them.

\n\n

That is, we make a static site generator that runs as a literate program.

\n\n\n

\n24. HTML

\n\n

How can we handle HTML gracefully?

\n\n

\n24.1 Boilerplate

\n\n

\n24.2 Jade

\n\n

\n24.3 Markdown

\n\n

\n24.4 Template Runs

\n\n

\n24.5 Cheerio

\n\n\n

\n25. JavaScript

\n\n

What can this do for our JavaScript woes?

\n\n

\n25.1 A Little Code

\n\n

If you have just a little bit of JS code, maybe you just want to put it in the\npage?

\n\n

\n25.2 Linting

\n\n

\n25.3 Testing

\n\n

\n25.4 h5

\n\n

\n25.5 Helpers

\n\n

\n25.6 Transpilers

\n\n\n

\n26. CSS

\n\n

CSS is hard to organize correctly. However you decide to do it, this can work for you.

\n\n

\n26.1 PostCSS

\n\n

\n26.2 SASS

\n\n\n

\n27. Servers

\n\n

Web content needs to be served. Here are some ways this tool can help.

\n\n

\n27.1 Making a Server

\n\n

\n27.2 Pushing Content to Server

\n\n

\n27.3 Pushing Content to S3

\n\n

\n27.4 Database managing

\n\n\n

\n28. AWS Lambda

\n\n

AWS Lambda is awesome. But if anything needs an organizational strategy, it would be AWS Lambda. Here is how.

\n\n\n

\n29. Writeweb

\n\n

This is how to write up a literate program and have it compiled automatically.

\n\n

This describes the setup of the writeweb server…

\n\n\n

\n30. Static Sites

\n\n

Putting it all together to show how to do great web development quickly and\neasily for whatever your needs are. Hah. Might as well talk about mobile\ndevelopment….

\n\n\n

\nIV Reference

\n\n

This part is the technical documentation of literate programming. While it\ndoes document itself, in some sense, this is a ready index of syntax,\ndirectives, commands, subcommands, and plugins.

\n\n

Most of this applies to literate-programming core library, but there are\ndirectives and commands that may only be applicable in the command client.\nThose are marked in their own section, either with Litpro (thin and fat client\napplicable) or Literate-Programming (just the fat client)

\n\n

Syntax

\n\n

Here we describe the syntax as formally as possible.

\n\n

Commonmark

\n\n

This is the markdown specification and parser that we use to determine when\nsomething is a header, a code block or link. The rest of the syntax is not\nrelevant for our purposes though it may be of relevance to readers.

\n\n

Code blocks

\n\n

Our main concern is to transform and string together code blocks. A code block\nis something that essentially is indented by 4 spaces or is fenced off (3\nbackticks before and after).

\n\n

Minor Blocks

\n\n

A minor block is a block that is being referenced by two parts: a header block\nname and, after a colon, the minor block’s name.

\n\n

References and Substitutions

\n\n

References are what we use to refer to the chunks of code, or rather, what we call\nthe names of those chunks.

\n\n

Substitutions are the syntax saying that something else should go there. Only\nsubstitutions and their escaped versions cause a change in the code chunks.

\n\n

Substitutions can have null references. The point of these would be the pipes\nand commands.

\n\n

References can occur before the first pipe or as part of a command or as part\nof a directive.

\n\n

Pipes

\n\n

These initiate commands that transform the incoming text.

\n\n

Directive Syntax

\n\n

This is a link syntax with the title text starting with a word followed by a\ncolon. Each part of the link may or may not have relevance to the directive.

\n\n

Command Syntax

\n\n

No parentheses required for command arguments.

\n\n

Subcommand Syntax

\n\n

These are functions in the arguments of a command. These require parentheses.

\n\n

Directives

\n\n

Directives are generally intended for using text in a certain way, such as\nsaving it to a file or defining a command with it. There is also the eval\nsyntax which will act immediately upon being encountered.

\n\n

Commands

\n\n

Much of the heart of the transformations are commands and there are a great\nmany commands that come by default.

\n\n

Subcommands

\n\n

These help in getting the right kind of arguments into a command. One can\ncreate arrays, objects, booleans, numbers, etc., as well as manipulate such\nstructures.

\n\n

Command-line

\n\n

The command line programs have flags that we explain here.

\n\n

Plugins

\n\n

Plugins are a way to have commonly used function easily packaged up and used.

\n\n

lprc.js

\n\n

This is a file that gets executed upon startup. It is the place to load up\nplugins, define commands, directives, and defaults.

\n\n

Some internals

\n\n

Here we detail some of the parts of the program that one may want to access\nfor a variety of reasons. Further details can be read in the literate source\ncode, mainly in that of\nliterate-programming-lib.

\n\n\n

\n31. A Complete and Full Syntax Specification

\n\n\n

\n32. Directives

\n\n

All the directives

\n\n

…

\n\n

\n32.1 LitPro Directives

\n\n

\n32.2 Literate Programming Directives

\n\n\n

\n33. Commands

\n\n

Commands …

\n\n\n

\n34. Subcommands

\n\n

Existing in a weird argument world…

\n\n\n

\n35. Command Line

\n\n

All you need to know about LitPro’s command line.

\n\n\n

\n36. Plugins

\n\n

These are some of the plugins available for LitPro.

\n\n\n

\n37. lprc.js

\n\n

A full specification of how to use this file. It includes a variety of information about the structure of the folder and doc objects.

\n\n\n

\n38. Compiling

\n\n

This details ways to get information out about what is going on in the compiling of a litpro document: events, reports, evaling, ..

\n\n\n

\nV The Literate Programs

\n\n

Here we give descriptions and links to all the various pieces of the literate\nprogram family. They are all written in a literate fashion and the source code\nis freely available at their repositories, listed below.

\n\n

All of this relies on node.js.

\n\n

To understand these tools, the most interesting repositories are those for the\nunderlying library, literate-programming-lib, and the event library,\nevent-when.

\n\n

litpro

\n\n

This is our main tool. It is a command-line tool. It can be installed globally\nor locally into a repository. Use npm install litpro -g to install it\nglobally.

\n\n

\ngithub is where the code lives
\nnpm is the package.

\n\n

literate-programming

\n\n

This is the fat command-line client. It can do everything that litpro can do,\nbut it also comes bundled with pug, markdown-it, postcss, tidy, minifiers.\nThis is a “batteries loaded” tool for web development.

\n\n

\ngithub is where the code lives
\nnpm is the package.

\n\n

This can also be installed globally with npm install literate-programming\n-g. The command is then literate-programming.

\n\n

litpro-jshint

\n\n

If you all you need is jshint, you might want to install the module\nlitpro-jshint instead of the full one.

\n\n

\ngithub is where the code\nlives
\nnpm is the package.

\n\n

literate-programming-cli

\n\n

This is an intermediate project between the library and litpro. This is where\nmost of the command line client code is written.

\n\n

\ngithub is where the code\nlives
\nnpm is the package.

\n\n

literate-programming-cli-test

\n\n

This is our test framework for the command line client. Basically, we have a\ndirectory with the files to process, a canonical directory showing what we\nexpect to be in the build directory.

\n\n

\ngithub is where\nthe code lives
\nnpm is the\npackage.

\n\n

literate-progamming-lib

\n\n

This is the place to read the literate program construction in detail. Start\nwith project.md and migrate to the other files in the structure. Parsing and\nstitching are the two main algorithmic pages.

\n\n

\ngithub is where the code\nlives
\nnpm is the package.

\n\n

event-when

\n\n

This is an event library that allows one to wait for multiple events with\nease. We use it, for example, to assemble a variety of substitutions into a\nsingle code block. The return of that code block must wait for when the events\nof the other blocks being subbed in have fired.

\n\n

\ngithub is where the code\nlives
\nnpm is the package.

\n\n

\n\n","tocStructure",[511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532,533,534,535,536,537,538,539,540,541,542,543,544,545,546,547,548,549,550,551,552,553,554,555,556,557,558,559,560,561,562,563,564,565,566,567,568,569,570,571,572,573,574,575,576,577,578,579,580,581,582,583,584,585,586,587,588,589,590,591,592,593,594,595,596,597,598,599,600,601,602,603,604,605,606,607,608,609,610,611,612,613,614,615,616,617,618,619,620],{"_78":72,"_40":68,"_69":-5,"_73":74,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":68,"_69":-5,"_73":74,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":72,"_40":84,"_69":-5,"_73":85,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":88,"_69":-5,"_73":89,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":92,"_69":-5,"_73":93,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":96,"_69":-5,"_73":97,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":100,"_69":-5,"_73":101,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":105,"_69":-5,"_73":106,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":110,"_69":-5,"_73":111,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":113,"_69":-5,"_73":114,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":117,"_69":-5,"_73":118,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":72,"_40":120,"_69":-5,"_73":121,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":124,"_69":-5,"_73":125,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":128,"_69":-5,"_73":129,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":131,"_69":-5,"_73":132,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":134,"_69":-5,"_73":135,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":138,"_69":-5,"_73":139,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":141,"_69":-5,"_73":142,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":144,"_69":-5,"_73":145,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":147,"_69":-5,"_73":148,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":151,"_69":-5,"_73":152,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":154,"_69":-5,"_73":155,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":157,"_69":-5,"_73":158,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":160,"_69":-5,"_73":161,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":164,"_69":-5,"_73":165,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":167,"_69":-5,"_73":168,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":170,"_69":-5,"_73":171,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":173,"_69":-5,"_73":174,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":177,"_69":-5,"_73":178,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":180,"_69":-5,"_73":181,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":183,"_69":-5,"_73":184,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":186,"_69":-5,"_73":187,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":190,"_69":-5,"_73":191,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":193,"_69":-5,"_73":194,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":196,"_69":-5,"_73":197,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":199,"_69":-5,"_73":200,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":202,"_69":-5,"_73":203,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":206,"_69":-5,"_73":207,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":209,"_69":-5,"_73":210,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":212,"_69":-5,"_73":213,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":215,"_69":-5,"_73":216,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":219,"_69":-5,"_73":220,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":222,"_69":-5,"_73":223,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":225,"_69":-5,"_73":226,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":228,"_69":-5,"_73":229,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":231,"_69":-5,"_73":232,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":234,"_69":-5,"_73":235,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":238,"_69":-5,"_73":239,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":241,"_69":-5,"_73":242,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":244,"_69":-5,"_73":245,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":247,"_69":-5,"_73":248,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":250,"_69":-5,"_73":251,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":254,"_69":-5,"_73":255,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":257,"_69":-5,"_73":258,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":260,"_69":-5,"_73":261,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":263,"_69":-5,"_73":264,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":267,"_69":-5,"_73":268,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":270,"_69":-5,"_73":271,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":273,"_69":-5,"_73":274,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":276,"_69":-5,"_73":277,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":280,"_69":-5,"_73":281,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":283,"_69":-5,"_73":284,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":286,"_69":-5,"_73":287,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":290,"_69":-5,"_73":291,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":294,"_69":-5,"_73":295,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":298,"_69":-5,"_73":299,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":301,"_69":-5,"_73":302,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":304,"_69":-5,"_73":305,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":308,"_69":-5,"_73":309,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":311,"_69":-5,"_73":312,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":314,"_69":-5,"_73":315,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":317,"_69":-5,"_73":318,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":321,"_69":-5,"_73":322,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":72,"_40":325,"_69":-5,"_73":326,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":329,"_69":-5,"_73":330,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":333,"_69":-5,"_73":334,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":336,"_69":-5,"_73":337,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":339,"_69":-5,"_73":340,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":342,"_69":-5,"_73":343,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":345,"_69":-5,"_73":346,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":348,"_69":-5,"_73":349,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":352,"_69":-5,"_73":353,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":355,"_69":-5,"_73":356,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":358,"_69":-5,"_73":359,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":361,"_69":-5,"_73":362,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":364,"_69":-5,"_73":365,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":367,"_69":-5,"_73":368,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":370,"_69":-5,"_73":371,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":374,"_69":-5,"_73":375,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":377,"_69":-5,"_73":378,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":380,"_69":-5,"_73":381,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":384,"_69":-5,"_73":385,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":387,"_69":-5,"_73":388,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":390,"_69":-5,"_73":391,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":393,"_69":-5,"_73":394,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":396,"_69":-5,"_73":397,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":400,"_69":-5,"_73":401,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":404,"_69":-5,"_73":405,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":72,"_40":408,"_69":-5,"_73":409,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":412,"_69":-5,"_73":413,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":416,"_69":-5,"_73":417,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":420,"_69":-5,"_73":421,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":104,"_40":423,"_69":-5,"_73":424,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":426,"_69":-5,"_73":427,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":430,"_69":-5,"_73":431,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":434,"_69":-5,"_73":435,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":438,"_69":-5,"_73":439,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":442,"_69":-5,"_73":443,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":79,"_40":446,"_69":-5,"_73":447,"_71":72,"_107":-5,"_108":-5,"_82":-5},{"_78":72,"_40":450,"_69":-5,"_73":451,"_71":72,"_107":-5,"_108":-5,"_82":-5},"publicChapterContent","nextChapter","sections",[579,580,581],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

\n21. Testing

\n21.1 Generating Common Test Environments

\n21.2 h5 Test Headings

\n21.3 Inline Eval Testing of Code Snippets

Table of Contents

Introduction

\nI The Basics

What is literate programming?

LitPro

Semi-literate programming

Symphonic programming

Artistic programming

\n1. What is literate programming?

\n2. LitPro

\n3. Semi-literate programming

\n4. Symphonic Programming

\n4.1 Syntax

Minor blocks

Other literate program files

Full Example

\n4.2 Functions or reordering

\n5. Artistic programming

Sub

\n5.1 Web

\nII Cookbook

Constants

Eval

Boilerplate

Making a Command

Making a Directive

Project Files

Making a lprc.js file

Other languages

Making a Plugin

Data Entry

Conditional Compiling

Domain Specific Languages

Making a Subcommand

Linting

h5 and h6 Headers

Testing

Documentation

Debugging

\n6. Constants

\n6.1 Evaling

\n6.2 Command producing constants

\n7. Eval

\n7.1 Command Eval

\n7.2 Command Async

\n7.3 Directive Eval

\n8. Boiler Plate

\n8.1 Repeated Use of Chunks

\n8.2 Evaling

\n8.3 Minors and Compiling

\n9. Making a Command

\n9.1 Synch command

\n9.2 Async command

\n9.3 Plugins

\n10. Making a Directive

\n10.1 Evaling to a Directive

\n10.2 lprc.js Directives

\n10.3 Plugins and Directives

\n11. Project Files

\n11.1 Version

\n11.2 NPM

\n11.3 Readme

\n11.4 gitignore

\n12. lprc.js

\n12.1 Custom commands and directives

\n12.2 Loading plugins

\n12.3 Default arguments

\n13. Other Languages

\n13.1 Hyphenated var names

\n13.2 Space separated to JSON

\n13.3 CSV to JSON

\n13.4 Auto-prefixer

\n13.5 SASS to CSS

\n14. Making a Plugin

\n14.1 Independent

\n14.2 Jade