    :PROPERTIES:
    #+title: literate programming test document
    #+author: bsp

    A program is divided into ~macro~ snippets, interwoven by documentation.

    The macros are then tangled into an executable source (see Define the tangled program structure)

    * COMMENT execute code block under cursor with C-c C-c (org-babel-execute-src-block)
    * COMMENT execute all code blocks with C-c C-v C-b OR C-x C-c (org-babel-execute-buffer)
    * COMMENT the test_host saves the tangled source to "autogen_debug.tks"
    * COMMENT macros may contain tangled snippets (default recursion depth = 20)

    See also: cellular programming

    ** TKS-remote test host
      * start ~test_host~
       Must done in a shell (editor hangs otherwise)
       #+begin_src shell :results output replace :eval never
         #!/bin/zsh
         #setopt NO_HUP
         tks app:test_host &!
       #+end_src
       #+results:
       :

    *** test 1 (live coding)
       Connects to script host ~test_host~ and evaluates some code in the context of the running host program.
       The host ~MyAPI~ provides a few members and methods to play with.
       #+begin_src tks-rs :host "test_host" :results output replace
         trace "hello, world.";
         trace "i="+MyAPI.i+" f="+MyAPI.f+" s=\""+MyAPI.s+"\"";
         trace "MyAPI.Add(23, 42)="+MyAPI.Add(23, 42);
         trace "MyAPI.Add(1.23, 4.56)="+MyAPI.Add(1.23, 4.56);
       #+end_src
       #+results:
       : hello, world.
       : i=42 f=3.14159 s="mystring"
       : MyAPI.Add(23, 42)=65
       : MyAPI.Add(1.23, 4.56)=5.79

    *** test 2 (literate)

    **** Define a string var
         #+begin_src tks-rs :host "test_host" :results output replace
           // string <<msg>>
           hello, "world".
         #+end_src
         #+results:
         :

    **** Define the program prologue
         #+begin_src tks-rs :host "test_host" :results output replace
           // macro <<init>>
           trace "calculating earth<>moon distance..";
         #+end_src
         #+results:
         :

    **** Define the program body
         #+begin_src tks-rs :host "test_host" :results output replace
           // macro <<body>>
           trace msg;
         #+end_src
         #+results:
         :

    **** Define the program epilogue
         #+begin_src tks-rs :host "test_host" :results output replace
           // macro <<exit>>
           trace "cu";
         #+end_src
         #+results:
         :

    **** Define the tangled program structure
         #+begin_src tks-rs :host "test_host" :results output replace
           trace "pre";
           // tangle <<init>>
           // tangle <<body>>
           // tangle <<exit>>
           trace "post";
         #+end_src
         #+results:
         : pre
         : calculating earth<>moon distance..
         : hello, "world".
         : cu
         : post