Technology moves fast! ⚡ Don't get left behind.🚶 Subscribe to our mailing list to keep up with latest and greatest in open source projects! 🏆


Subscribe to our mailing list

Literate

A literate programming tool for any language

Subscribe to updates I use Literate


Statistics on Literate

Number of watchers on Github 148
Number of open issues 14
Average time to close an issue 1 day
Main language D
Average time to merge a PR 1 day
Open pull requests 1+
Closed pull requests 0+
Last commit over 1 year ago
Repo Created almost 4 years ago
Repo Last Updated over 1 year ago
Size 2 MB
Homepage http://literate.z...
Organization / Authorzyedidia
Contributors2
Page Updated
Do you use Literate? Leave a review!
View open issues (14)
View Literate activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating Literate for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Literate

What is Literate programming?

Literate programming is a style of programming invented by Donald Knuth, where the main idea is that a program's source code is made primarily to be read and understood by other people, and secondarily to be executed by the computer.

This frees the programmer from the structure of a program imposed by the computer and means that the programmer can develop programs in the order of the flow of their thoughts.

A Literate program generally consists of explanation of the code in a natural language such as English, interspersed with snippets of code to be executed. This means that Literate programs are very easy to understand and share, as all the code is well explained.


Literate is a tool for creating literate programs.

The goal of this project is to create a literate programming tool which keeps most, if not all of the features of Knuth and Levy's original CWEB system, but simplifies the system and adds even more features.

You can view the main website about Literate here including a manual on how to use Literate.

If you like the project, make sure to leave a star :smile:

Features

  • Supports any language including syntax highlighting and pretty printing in HTML
  • Markdown based -- very easy to read and write Literate source.
  • Reports syntax errors back from the compiler to the right line in the literate source
  • Generates readable and commented code in the target language (the generated code is usable by others)
  • Supports TeX equations with $ notation.
  • Literate source code is readable whether you are looking at the .lit file, or the generated HTML.
  • Highly customizable (you can add your own HTML or CSS)
  • Runs fast -- wc.lit compiled for me in 7ms for both code and HTML output
  • Automatically generates hyperlinks between code sections
  • Formatted output similar to CWEB
  • Supported by micro (by default)
  • Compatible with Vim (literate.vim)

Example

Here is a trivial example of a literate program saved in the file hello.lit.

For a full example of a literate program, please see examples/wc.lit which is a literate implementation of the wc (word count) program found on Unix systems. You can find the compiled html here.

@title Hello world in C

@s Introduction

This is an example hello world C program.
We can define codeblocks with `---`

--- hello.c
@{Includes}

int main() {
    @{Print a string}
    return 0;
}
---

Now we can define the `Includes` codeblock:

--- Includes
#include <stdio.h>
---

Finally, our program needs to print "hello world"

--- Print a string
printf("hello world\n");
---

To compile this code simply run

$ lit hello.lit

Which generates hello.c and hello.html.

You can also find this program in examples/hello.lit.

Installation

Prebuilt binaries

Download
Mac OS X
64 bit Linux
32 bit Linux
Arm Linux

Building from Source

Mac

On Mac you can use brew to build Literate from source:

$ brew tap zyedidia/literate
$ brew install --HEAD literate

For now, Literate is head only.


Literate is made with the D programming language so you must install dmd (D compiler) and dub (D package manager). Then you should download the zip or clone the repository and run the following commands:

$ cd Literate
$ make

You can find the binary in path/to/Literate/bin (you may want to add this to your path or move it to /usr/local/bin).

Editors

Micro

The micro editor has support for literate by default. Download it here.

Vim

You might also want to go install the Vim plugin (it has syntax highlighting of the embedded code, linting with Neomake, and jumping to codeblock definitions). I'm sorry that no other editors are supported -- I don't know how to make plugins for other editors.

Usage

Lit: Literate Programming System

Usage: lit [options] <inputs>

Options:
--help       -h         Show this help text
--tangle     -t         Only compile code files
--weave      -w         Only compile HTML files
--no-output  -no        Do not generate any output files
--out-dir    -odir DIR  Put the generated files in DIR
--compiler   -c         Report compiler errors (needs @compiler to be defined)
--linenums   -l    STR  Write line numbers prepended with STR to the output file
--md-compiler COMPILER  Use COMPILER as the markdown compiler instead of the built-in one
--version    -v         Show the version number and compiler information

For more information see the manual.

Contributing

Literate is written in Literate D and you can find the source code in the lit directory. You can also read the source code compiled by Literate here. I am happy to accept pull requests, and if you find any bugs, please report them. Thanks!

Literate open issues Ask a question     (View All Issues)
  • almost 3 years Pandoc compiler and latex
  • almost 3 years Sections with @s vs headers with #
  • almost 3 years Native "raw" @include
  • over 3 years Proposal: A directive for Table Of Contents
  • over 3 years Proposal: Tufte CSS
Literate open pull requests (View All Pulls)
  • Support for hierarchically organized sections
Literate questions on Stackoverflow (View All Questions)
  • No instance for (GHC.Base.Alternative Parser) error running Literate Haskell code
  • Emacs Org-Mode & Literate Haskell
  • How can I implicitly organize literate code with org-mode?
  • How to literate my list
  • Literate programming
  • Best choice of Literate Programming tool for Windows x64
  • How to write Herons Formula in Literate Haskell
  • Intuitive motivation for Literate Programming?
  • Literate programming in intellij IDEA?
  • How Does One Handle Identical Method Names when Using Literate Programming?
  • What's the best way to do literate programming in Python on Windows?
  • Literate PHP to test examples in README
  • Literate programming in multiple langauges
  • Write coffeescript cake file in literate coffee
  • using scons for literate programming
  • How can I enable GHC extensions in a literate Haskell script?
  • For loops with user input (probably easy: just not computer-literate)
  • Examples on Literate Programming with Racket scribble/lp
  • Emacs org mode: how to create literate programs with noweb syntax
  • How to use literate coffeescript with rails?
  • Literate Python
  • Literate Haskell Source for Haskell School of Expression. Confusion
  • How can I use literate coffeescript for my Gruntfile
  • ANTLR and Literate Programming
  • Is there a Sublime Text 2 package that supports literate Haskell files (.lhs)?
  • Is there a way to do test-driven development with literate programming?
  • Natural Language Programming vs. Literate Programming
  • How to set up vim's identation for literate Haskell programming?
  • Does any literate programming environment support on the fly results?
  • How to comment out lines in literate haskell
Literate list of languages used
More projects by zyedidia View all
Other projects in D