вторник, 25 октября 2011 г.

ypweb literate programming tool

After I tried LP technique, I decided that it help me to understand my code better and cuts many possible errors. But I need easier tool, lesser verbose... I implemented very lightweight Python 3 tool (about 20Kb) and called it ypweb. It's hosted on Google.
Main differences with other LP tools are:
  • produces only reStructuredText output
  • very lightweight (only one Python 3 file) about 20Kb
  • doesn't need comment line symbols for document strings (like #!) and code-chunks: only plain text
  • document and code context are switched by special line with short variants
  • generated index contains used by user (not predefined) classifiers
  • doesn't allow code-chunks "placeholders" (defining in one place/inserting in another)
  • supports any input and output charsets (see -h)
Short example:

  1 | Some definitions (macroses) used in COM module:
  2 | ;; x.h; defs; COM definitions
  3 | ;; Port number
  4 | #define PORT 1
  5 | ;; Baudrate
  6 | #define BAUD 9600
  7 | ;; funs; open()
  8 | int open(char *name, char *mode);
  9 | ;;
 10 | Another doc strings...
 11 | ;; x.c; funs; open()
 12 | code of open function here...
 13 | ;; x.h; defs; XXX
 14 | #define XXX
 15 | ;;
 16 | docs strings again...

Line 1 is the document chunk (file may starts with any chunk: doc or code). Line 2 is the special kind of line which switch context to code and begins with special marker (;;) and consists of 3 parts (may be lesser) splited by ;. Both symbols (;; and ;) may be changed to another in command line. It "says": next chunk is code, generates x.h file with some definitions ("defs" but may be any word preferred by user) and is the "COM definitions". These fields will be used also in index generating.

Line 3 is short form of switch-context-line (only caption, no file name or classifier). Line 4 is code and will be saved in the source file. Line 4 is like line 3, next is source line again...

Line 7 is short switch-context-line too and consists of classifier and caption, no filename, so will be saved in the same file - x.h.

Line 9 is empty switch-context-line, so it ends code chunk, nothing else. Next is always doc chunk.
Line 11 is switch-context-line which starts new source file: x.c. Line 13 begins code chunk for early created x.h file. Well, switch-context-line switch into code chunk and defines what is the code if not empty, empty - switches into doc chunk.

It's very clean and simple format. And is the reStructuredText too. So, you can use in it any kind of usual reSt markup!

After processing this file, .rst file and x.h, x.c will be generated. Also .rst file will have index section in the end with references to definitions of the code chunks.

Комментариев нет:

Отправить комментарий

Thanks for your posting!