Literate programming

From Wikipedia, the free encyclopedia

Literate programming is a philosophy of computer programming based on the premise that a computer program should be written with human readability as a primary goal, similarly to a work of literature. According to this philosophy, programmers should aim for a “literate” style in their programming just as writers aim for an intelligible and articulate style in their writing. This philosophy contrasts with the more mainstream view that the programmer’s primary or sole objective is to create source code that can be effectively executed by a computer.

In practice, literate programming is achieved by combining human-readable documentation and machine-readable source code into a single source file, in order to maintain close correspondence between documentation and source code. The order and structure of this source file are specifically designed to aid human comprehension: code and documentation together are organized in logical and/or hierarchical order (typically according to a scheme that accommodates detailed explanations and commentary as necessary). At the same time, the structure and format of the source files accommodate external utilities that generate program documentation and/or extract the machine-readable code from the same source file(s) (e. g., for subsequent processing by compilers or interpreters).

Contents 1 History and current implementations 2 Related concepts 2.1 Outlining 2.2 Embedded documentation 2.3 Doctests 3 Example of a simple literate program and interpreter 3.1 Program 3.2 Interpreter 4 See also 5 References 6 External links

[edit] History and current implementations

The first published literate programming environment was WEB, introduced by Donald Knuth in 1981 for his TeX typesetting system; it uses Pascal as its underlying programming language and TeX for typesetting of the documentation.

The complete commented TeX source code was published in Knuth's TeX: The program, volume B of his 5-volume Computers and Typesetting. Knuth had internally used a literate programming system called DOC as early as 1979; he was inspired by the ideas of Pierre Arnoul de Marneffe. The free CWEB, written by Knuth and Levy, is WEB adapted for C and C++, runs on most operating systems and can produce TeX and PDF documentation. Other implementations of the concept are noweb and FunnelWeb.

[edit] Related concepts

[edit] Outlining

Outlining editors are sometimes seen as providing a variant of the original concept of literate programming as used by Knuth. In particular, Leo combines outlining with interfaces to noweb and CWEB processors.

[edit] Embedded documentation

There are also less powerful systems to integrate documentation and code than literate programming; examples are pod for perl, doc++ for C, C++ and Java, javadoc for Java, and Doxygen for many languages. See documentation generator.

These however do not quite follow the literate programming philosophy since they typically just produce documentation about the program, such as specifications of functions and parameters, and not documentation of the program source code itself. They also do not allow rearrangement of presentation order, which is critical to the effectiveness of literate programming.

Haskell is a modern language that makes use of a limited form of literate programming: this semi-literate style does not allow code re-ordering or multiple expansion of definitions but lets the programmer intersperse documentation and code freely.

It is the fact that documentation can be written freely whereas code must be marked in a special way (see the example below) that makes the difference between semi-literate programming and excessive documenting, where the documentation is embedded into the code as comments.

[edit] Doctests

Similarly to source code, testing code that exercises an API can be embedded within human-readable documentation, along with the expected output of the calls. A test runner extracts and executes the code and verifies its output against the expected output. This idea originated from the Python programming language. An implementation is provided by the Python standard library's doctest module.

[edit] Example of a simple literate program and interpreter

[edit] Program

This section contains a literate program, which can be run using the example literate interpreter in the Interpreter section

For this particular interpreter, all the program code must be written on lines starting with a dash. Everything else is ignored by the interpreter. This does not support some important aspects of advanced literate programming like code rearrangements or multiple expansion and so should only be called basic literate programming or "semi-literate" literate programming.

Program to calculate the area of a circle and rectangle

Firstly, in the interests of putting the user at ease, the program will simulate personal interest in the user by asking for their name, accepting the input and generating a greeting based on the input text.

- clearscreen
- print text Please type your name:
- store input
- print Hello there,
- print value
- print .  Nice to meet you.
- newline
- newline

The area of a circle

Continuing the "query-response" mode of operation, prompt the user for the radius of a circle, which is then used to calculate the area of a circle using the standard formula for the area of a circle: A = πr². Due to syntax limitations, this is done by multiplying the input value by itself, then by π. This calculated value is returned to the user.

Note: the value of π used is an approximation that is sufficiently accurate for our purposes.

- print text Let's work out the area of a circle.
- newline
- print text Please enter the radius of the circle in furlongs:
- store input
- multiplyby value
- multiplyby 3.14159
- print Thank you
- newline
- print text The area of the circle is
- print value
- print text square furlongs.
- newline
- newline

Finally the user is asked for the required information, and the area of the rectangle is worked out using the standard width by height formula.

- print text Now let's work out the area of a rectangle.
- newline
- print text Please enter the width of the rectangle in ells:
- store input
- print text Please enter the length of the rectangle in ells:
- multiplyby input
- print Thank you
- newline
- print text The area of the rectangle is
- print value
- print text square ells.
- newline
- newline
- print text Goodbye,

[edit] Interpreter

The following simple interpreter program is written using BASIC. When compiled using the QuickBASIC compiler it is a straightforward interpreter but when run on the QBASIC interpreter, it is an example of an interpreted interpreter.

DECLARE SUB SplitFirst (aFirst AS STRING, aRest AS STRING)
LET Q$ = "TESTPROG.TXT"
LET F = FREEFILE
OPEN Q$ FOR INPUT AS #F
DO WHILE NOT EOF(F)
  LINE INPUT #F, FileInput$
  LET FileInput$ = LTRIM$(FileInput$)
  SplitFirst KeyWord$, FileInput$
  SELECT CASE KeyWord$
  CASE "-"
    SplitFirst KeyWord$, FileInput$
    GOSUB InterpretKeyword
  END SELECT
LOOP
CLOSE #F
SYSTEM

InterpretKeyword:
  SELECT CASE UCASE$(KeyWord$)
  CASE "STORE"
    GOSUB AssignToValue
  CASE "ADD"
    GOSUB AddToValue
  CASE "MULTIPLYBY"
    GOSUB MultiplyWithValue
  CASE "PRINT"
    GOSUB PutOutput
  CASE "CLEARSCREEN"
    GOSUB ClearScreen
  CASE "NEWLINE"
    PRINT
  CASE ELSE
    PRINT
    PRINT "I don't know what "; KeyWord$; " "; FileInput$; " means."
  END SELECT
  RETURN

AssignToValue:
  GOSUB GetArg
  LET Value$ = Arg$
  RETURN

AddToValue:
  GOSUB GetArg
  LET Value$ = LTRIM$(STR$(VAL(Value$) + VAL(Arg$)))
  RETURN

MultiplyWithValue:
  GOSUB GetArg
  LET Value$ = LTRIM$(STR$(VAL(Value$) * VAL(Arg$)))
  RETURN

GetArg:
  Split KeyWord$, FileInput$
  SELECT CASE UCASE$(KeyWord$)
  CASE "INPUT"
    GOSUB GetInput
    LET Arg$ = UserInput$
  CASE "VALUE"
    LET Arg$ = Value$
  CASE "TEXT"
    LET Arg$ = FileInput$
  CASE ELSE
    LET Arg$ = KeyWord$ + " " + FileInput$
  END SELECT
  RETURN

GetInput:
  LINE INPUT "", UserInput$
  RETURN

PutOutput:
  GOSUB GetArg
  PRINT Arg$; " ";
  RETURN

ClearScreen:
  CLS
  RETURN

NewLine:
  PRINT
  RETURN

SUB SplitFirst (aFirst AS STRING, aRest AS STRING)

  DIM J AS INTEGER

  LET J = INSTR(aRest + " ", " ")
  LET aFirst = LTRIM$(LEFT$(aRest, J - 1))
  LET aRest = LTRIM$(MID$(aRest, J))

END SUB

To try with the above program, save the interpreter as INTERP.BAS and then save the program section as TESTPROG.TXT in the same folder. Run INTERP.BAS with either QBASIC or QuickBASIC.

[edit] See also

• Intentional Programming

[edit] References

• Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.
• Pierre Arnoul de Marneffe, Holon Programming. Univ. de Liege, Service d'Informatique (December, 1973).
• Major Literate Programming website
• Literate Programming newsgroup

[edit] External links

• Select: A literate programming example using noweb
• LiteratePrograms is a literate programming wiki.
• comp.programming.literate FAQ at internet FAQ archives