II Cookbook
This is where we do a variety of specific examples of use. It mainly focuses on examples from the web stack. In particular, the programming is almost entirely JavaScript.
Constants
We can define constants once with explanations and then put them into whatever files need them.
Eval
How to run some JavaScript
Boilerplate
If you have need of boilerplate, then we can do that with some substitutions for templating it as well.
Making a Command
Commands are very useful. This is how to make them in a literate program.
Making a Directive
Inline custom directives are not that useful, but it can be insightful in going towards making plugins.
Project Files
Often there are other files needing managing for a project other than just code. For example, .gitignore, readme, package.json, … These can all live in a single literate programming document that generates these files. It could also be setup to have variables that you define once and then use when needed, such as the version number.
Making a lprc.js file
What constitutes a lprc.js file. This is where directives and commands are ideally added, either directly or from plugins.
Other languages
If you want to write in your own style or language or whatever, it can do that as well. Write in a way comfortable to you and have it compile it into any target language.
Making a Plugin
Making a plugin leads to good consistent behavior.
Data Entry
Dealing with little bits of data is a difficult problem. Here we look at inline data entry using a quick split style as well as reading in data from an external file. This pertains more to generating written output, then code itself, but it could be needed there as well such as if you want to pull in secrets from a file outside of the repo and put it in the compiled code that is also stored outside of the repo.
Conditional Compiling
We may want to do one thing or another depending on the compilation context, e.g., development vs production though one can often do both at the same time, with multiple output targets.
Domain Specific Languages
We can write full blown domain specific languages and have them translated at build time. Or you can use standard languages that get transformed, such as markdown into html.
Making a Subcommand
These allow for doing complex actions in arguments. These are different from commands that expect to be a part of a pipe flow.
Linting
We can lint pieces of our code. It would even be possible to lint the pieces in isolation to see what shared variables might pop up.
h5 and h6 Headers
These are headers that generate path-escaped references using the most recent main block reference as the root path. These sections can not only be useful for commonly named parts, but can also have custom behavior automatically acting on the parts.
Testing
Testing should be easy. Here we give a strategy for testing little bits of code (unit testing) as well as testing the combined pieces (integrated testing).
Having fake data specified as well as expected output is also easy.
Documentation
While literate programming is designed to be the documentation for the maintenance programmer, there is still the little issue of user documentation. While that may call for a separate document, it could be included in the same literate program as well using the h5 and h6 mechanism, keeping it with the code.
Debugging
Debugging can be supported by conditional commands.
6. Constants
Let’s say we want to put constants at the top of a file.
6.1 Evaling
6.2 Command producing constants
7. Eval
Being able to run arbitrary code is a powerful tool. It helps in doing quick debugging as well as quick prototyping of an effect.
7.1 Command Eval
7.2 Command Async
7.3 Directive Eval
8. Boiler Plate
A few examples of doing boiler plate in a better way.
8.1 Repeated Use of Chunks
You can use the same chunk multiple times.
8.2 Evaling
8.3 Minors and Compiling
9. Making a Command
Commands are extremely useful in sculpting the code. You can make your own commands
9.1 Synch command
9.2 Async command
9.3 Plugins
10. Making a Directive
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.
10.1 Evaling to a Directive
10.2 lprc.js Directives
10.3 Plugins and Directives
11. Project Files
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.
11.1 Version
11.2 NPM
11.3 Readme
11.4 gitignore
12. lprc.js
This is the configuration file for a literate programming file. What can it do and what should it do?
12.1 Custom commands and directives
12.2 Loading plugins
12.3 Default arguments
13. Other Languages
Sometimes I just want to speak in another dialect. What can LitPro do for me?
13.1 Hyphenated var names
13.2 Space separated to JSON
13.3 CSV to JSON
13.4 Auto-prefixer
13.5 SASS to CSS
?? Example: using hyphens for spaces in javascript.
Example: math algorithm
14. Making a Plugin
Eventually, all good tools need a lot of plugins to be considered successful. So start writing them!
Most plugins are just a thin layer of wrapping over someone else’s carefully written plugin.
We’ll do a few case studies of plugins
14.1 Independent
Using nothing, creating whatever.
14.2 Jade
Very simple
14.3 JSHint
A little bit harder, also trying to shoehorn config details into the plugin
14.4 Markdown, PostCSS
Plugins of markdown-it and using them
15. Data Entry
Getting data to its right place.
15.1 Reading CSV into Template
15.2 Date/Time
both js and command line
15.3 Pulling from web
16. Conditional Compiling
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.
16.1 Flags
16.2 Conditional Syntax
16.3 Multiple Compiles
17. Domain Specific Languages
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.
17.1 Math Algorithms
17.2 Extra Markdownish
18. Making a Subcommand
This is about exploring the mysterious world of subcommands.
19. Linting
Linting little pieces of code.
20. h5 and h6 Headers
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.
20.1 Paths
20.2 Collecting CSS
21. Testing
Here we detail a few different ways that we could use literate programming to help the first bugbear of programming: testing.
21.1 Generating Common Test Environments
21.2 h5 Test Headings
21.3 Inline Eval Testing of Code Snippets
The ultimate in unit testing, we test a variety of pieces of the code immediately.
22. Documentation
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.
23. Debugging
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?