1. REFERENCE MANUAL

1.1. Starting the processor
using the **module** KEYWORD

1.2. The **module** command
The **module** command tells the processor where to start to scan the trees.

We recall that
The **module** command takes several arguments
argument name type of argument possible values Note
lang string py, python, html, cpp, js, javascript, ada, prolog, etc... This argument is mandatory !
see list of supported languages and how to extend languages.
tab integer <= 8 0 .. 8 for indented languages (programming languages) describes the standard equivalent of one tab. One tab = k spaces.
offset integer 0..8 All lines are systematically indented by a constant tab value. The offset is the number of tabs used.
no_start boolean ON/OFF, true/False Standard start lines are for example
  • in python :
    • # coding = utf8
    • # filename = ..
    • etc
  • in html :

  • etc
h_string string '#-----' the h_string will be inserted systematically at the beginning of EACH line of the output. This can be helpful if you need to geenrate a file that is indeented so as to be inserted later into another file.

examples Comment
this will start the processor to interpret sub-trees as python, html, c++, etc
will produce a file with some python code which is all commented


The *collect uses identical parameters (see later).

1.3. Standard icons

1.3.1. The concept

1.3.2. Basic icons for control

Standard macros are available in all KM2 languages.
Standard macros are defined as :
Examples source code generated code
Example of use in Prolog This is the standard way to write programms in KM2, in any language.

Example of use in Python source code

Definition of standard macros

1.4. The GOSUB command
The GOSUB is a command that allows to pass the control from one SGH scheme to another :

SOURCE IN KM2



⇨
Generated by KM2 :



Summary of the GOSUB possible commands.
Command What happens Example Note
GOSUB the processor jumps to the hyperlink

Now we obtain
If GOSUB has sub_nodes, they are ignored

nodes F, G, H are not visited
GOSUB the processor tries to find a sub-tree below the hyperlink
if found : jumps to that sub_tree
the sub tree is designated by : a / b / ... / c where a b c are the names of nodes

We obtain : 3 bis 310 320 		if several nodes have the same title, they can be distinguished by the path that leads to them.
GOSUB {variable} If the name of the variable corresponds to a value, it processes the value
The value of the variable can be :
  • a SGH node
  • a string
  • a list of variables
GOSUB {python _expression} If the python expression has a value, it processes the value.
The value resulting from the eval of the expression can be :
  • an SGH node
  • a string
  • a list of variables

1.5. Special commands


We describe here below the commands that are basically available in the KM2 processor.
special commands use a ! icon and their text start with a *. Example :

1.5.1. List of special commands

Name Type of command
*setf // *seta designation of tree
*collect Control
*if, *else, *case, *switch Control
*loop // *for Control
*warn Control for errors
*flush use external file
*insert use external file
*standard use external file
*import file use external file
*indent parameter
*inline parameter
*controls parameter
*base64 parameter

1.5.2. *setf // *seta


*seta and *setf allow to define trees as variable. They may be bound to a node, a list of nodes, a view or a workspace.

Command What happens Example Note
*setf variable --> nodes the variable is bound to the list of the nodes below the *setf Binds foo to the list of A and B trees
SOURCE IN KM2



⇨
Generated by KM2 :

A B B1 C D E F
*setf variable, path *from other_variable the variable is bound to the resulting node
SOURCE IN KM2



⇨
Generated by KM2 :

B B1
*setf variable , path --> hyperlink if the path (= c1 / ... / cn) leads to a node, then the variable is bound to that node
*setf variable, path // local hyperlink find a given note from the same file
*setf variable, path // file find a given note from another file
*setf variable // file binds the variable to the workspace from the file la valeur de la variable peut être un WORKSPACE, une VUE ou un ARBRE
*seta variable, path if the path (= c1 / .. . cn) leads to a nod N e, then the variable is bound to the node whose text is c1. *seta is used to find a tree which contains some nodes.

*setf binds to a node. *seta works similarly as *setf, but binds to the ROOT where the path was found.

*seta is used to find a tree which contains some nodes.

1.5.3. *collect / *flush


*collect and * flush are important as they allow to collect the mapping into a specific variable, separately, and then flush the result into a file.

Command Example Note What happens
*collect , Sous-sujet 2

Sous-sujet 3 is the name of python variable
are the same as for the **module** command
the KM2 processor visits the nodes, and builds the list of the processed nodes as visited.
*flush , ,
variable : must refer to a PL , knowing that a PL can be :
  • string
  • list of PL

filename : is the name of a file (in relative or absolute terms)
arguments : can be :
  • mode : 'w' for write, 'a' for append (by default mode = 'w')
  • noline does not print a "new line" between strings.
  • newline prints a newline systematically.

Important to know :
  • if the variable in *collect does not exist, it will be initiated with a [] value.
  • after a *flush , it can be useful to reset the variable to []

Main uses for the collect are :
Example This tree will convert the "def foo ..." into python lines, then output to the file ffo_def.py
Source in KM2
Content of file foo_def.py : 
def foo (x) :
return x + 2

1.5.4. *insert


        PURPOSE
                inserts the content of a file into the current file.
                        The lines are inserted as they are, without formatting or processing.
        SYNTAX
                3 possibilities
                        *insert , from, to
                        *insert nom_de_fichier, from, to
                        *insert file = fichier, [from = , to = , ....]
        # insert file, from, to
        USAGES
                *insert , from, to
                *insert nom_de_fichier, from, to
                *insert file = fichier, [from = , to = , ....]
        SYNTAXE :
                fichier : nom de fichier, en absolu ou local
                from_ : un nombre >=0 ou une chaine
                to_ : idem

1.5.5. *import file

# directive pour importer un fichier de macros : *import // note : nom du noeud doit être unique dans le

1.5.6. *indent

*insert
inserts an indentation in the file

1.5.7. *inline

CONCEPT
  • The concept is very specific to python
  • By default, the KM2 processor lists the successive functions one after each other.
  • the *inline allows to declare a local function inside the current context.

Example
SOURCE IN KM2



⇨
Generated by KM2 : 

#*inline by default
#*inline  true
#*inline  true
#*inline  ON

1.5.8. *controls


controls allow to change some internal parmaters of the KM2 processor.

USAGE

Table of parameters :
Parameter Example default value meaning
errors ON/OFF *controls errors OFF ON collects the errors and displays the file
warnings ON/OFF *warnings errors OFF ON collects the warnings and displays the file
base64, base_64, images_base_64 ON/OFF ON for html
error_setf ON/OFF ON generates an error if the node as defined by setf does not exist
*arbre ON/OFF ON for html only : if ON : skip the node if OFF
notes ON/OFF OFF enable the extraction of notes from the nodes
labels ON/OFF OFF for html : interprets labels as html keywords
check_prolog ON/OFF True checks the syntax of prolog expressions and clauses
check_syntax ON/OFF True checks the syntax of programms
trace_step ON/OFF OFF
reset reset all controls to default value

1.5.9. Images : *base64


*base64 allows to control if the bytes of an image are inserted directly into the file or in a separate file (in attachments/name_of_image).
The main use of this feature is to minimize the number of files required to define a text or a programm. outdated. Remplaced by !*controls base64 *else, *case, *switch

1.5.10. Conditions : *if, *else, *case, *switch


Controlling the processing according to values is just very useful for generating documents and programs.

Table of possibilities :
syntax Example meaning
*if condition
collects the errors and displays the file
*elif condition *elif x > 0 collects the errors and displays the file
*else *else default value for a '*if' or a '*case' or a '*switch'
*when condition *when x > 0 collects the information if condition is met
*while condition *when x > 0 loop on collecting the information while condition is met
*case
for html or programms
Can be very useful for the generation of interfaces.
*switch expression
the expression is evaluated. the nth+1 sub tree is choosen if the expression evaluates to an integer n

Logic conditions are very useful in the processing of macros.

1.5.11. *loop // *for


*loop is a natural and usual control structure in programming, which is very useful for the generation of documents.

Execution model
  • A domain is defined as a range or through a python iterable (list, dict, etc)
  • When a variable var is used for iteration
    • the python value of var is directly accessible
    • all the {var} in the sub_tree are replaced by the value of var

Table of possibilities
possible syntax Example
*loop var_name, integer
SOURCE IN KM2



⇨
Generated by KM2 : 

table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
*loop var_name, domain
SOURCE IN KM2



⇨
Generated by KM2 : 

table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
table ['index_{i}']  = {i}
*for var_name in domain
SOURCE IN KM2



⇨
Generated by KM2 : 
















*for var_name, iterable


same as above








1.5.12. *standard







*standard simplifies considerably the use of macros






Syntax


The STANDARD file
X:\KM2\KM2_PARAM\S_MODELES\XMIND\STANDARDS.xmind
(where X can be C, D, etc)
is a very special file than can be defined by the user.
The file has the following structure :









For example : python standards




Python uses several files of macros, which must be loaded in the correct order.
This can become complicated, and also you need some standardization across many files.


Some macros are really generic and language independant.
like 'PY_FILE', 'JS_FILE', HTML_FILE', etc.
and which can be used in any file.


So the standard makes all import very easy, with a single statement.








1.5.13. *warn







*warn
allows to issue an error message


does not stop the programm or generate a run time error.






Syntax




An example :







The following instruction :




Generates the following error message :










1.5.14. {*}

The {*} command allows to substitue variables in a tree.


There are 2 syntaxes :

    

  • 
!{*}
:
will substitute all variables, including expressions like {length (L)} if L is a variable

    • 

  • 
!{*}V1, V2, ... Vn
will substitue only explicit variables V1, V2, ... Vn.
This is useful for complex macros.

    • 





1.6. Notations

There are 2 types of macros

    

  • 
line/text macros

    • 

  • 
tree macros

    • 





1.7. MACROS and KM2





Macros allow to gain in

    

  • 
readability
The writing tool allows to write hierarchically all problems and solutions, making it most suitable for many applications.

    • 

  • 
shortness of expression
macros process easily repetitive tasks and elements.

    • 

  • 
clarity of expression
Graphics can be embedded in source code

    • 

  • 
back processing
:
YDeTO
You Describe Things Once
.

    • 




MACROS are widely used in KM2 to generate :

    

  • 
documentation
textes in html can be easily generated

    • 

  • 
programming

    • 





1.7.1. Text macros

Text macros are designed to replace text INSIDE nodes







They are processed first, before applying tree macros.


They are processed in the order they are declared/found.


test macros are defined in a single node :







example


text before macro


text after macro






before ::= after


some text before the macro


some text after the macro






starts with ::= .startswith ({a1})


if x starts with y


if x.startswith (y)













Variables in tree macros








first level of variables


4 variables are built-in KM2 :

    

  • 
{a1}
the first term on the right of the macro

    • 

  • 
{a1_}
all the text to the right of the macro

    • 

  • 
{a_1}
the first term on the left of the macro

    • 

  • 
{a_1_}
all the text on the left of the macro

    • 




second level of variables







NOTE :
tree macros could be replaced in many cases by simple regex, but no.




1.7.2. Tree macros

Tree macros allow to replace whole expression or complex trees with a simple syntax.





A tree macro can be defined by :

    

  • 
name :
a sequence of words or by an icon.

    • 

  • 
body :
the new tree

    • 




Special variables allow for substitutions :

    

  • 
{L}
represents the whole tree below the macro

    • 

  • 
{a1}
first varioable after the macro

    • 

  • 
{a1_}
all text left of the macro name

    • 

  • 
{a2}
second argument of the macro

    • 

  • 
{a2_}
second rest of text

    • 

  • 
{a3} ... {a9}
successive arguments of the macro

    • 

  • 
{a3_} ... {a9_}
successive remainders for the text of the macro

    • 









examples


definition of the macro


before example


after example


note






return


::=
return {a1_}


value


x, y, z


return value


return x, y, z


this is a standard embedded macro 













1.7.3. External references




More information about the graphic and non linear writing style



Some topics













...