MACROS MACROS AND PROLOG






KM2 - PROLOG MACROS REFERENCE GUIDE

12 avril 2022


PROLOG AND KM2

1. PROLOG AND KM2

1.1. MACROS and KM2

 KM2 is a powerful macro-processor which allows to generate automaticaly files written hierarchically.
Today, KM2 uses the XMind format, but will use other sources in the future.
Programms and text in KM2 are described by Xmind trees. The processor uses a depth first walking routine to generate documents in several languages : python, prolog, html, C, java, javascript, etc.

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 experession 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

More information about the graphic and non linear writing style

1.2. Standard macros

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

in Python source code



Definition of standard macros

1.3. Presentation of MACROS in PROLOG
As a programming language, prolog is very interesting
However writing and reading prolog programms is not so easy
The linear structure of the editor and programming style do not allow easily to see the deep structure of programs.
A set of KM2 MACROS in prolog allow to write much more easily all kind of programs
  • for defining databases
  • for defining case as structured by clauses

NOTE : Programming with trees , icons and drawings require some practice, but at the end, it is much more easy to produce and maintain programms.
KM2 some possibilities with macros in prolog

2. KM2 some possibilities with macros in prolog

 Warning In the chapter below, some Prolog clauses are written without comas, for easiness of writing.

We have equivalent formulations :
  • solve_and_show_solutions :- problem (P) solution (P, S) write (solution (P, S)) nl fail
  • solve_and_show_solutions :- problem (P), solution (P, S), write (solution (P, S)) , nl, fail.

KM2 generates commas and points as needed during the generation, as well as indentation, comments, etc

2.1. General use of KM2

2.2. shorten some writing

 Some examples below from a general mechanism that applies to all kinds of programms and documents.

2.2.1. The first way is to have more tree_like programming

which allows to present better programms. Just compare
Expected result

(This is a screen copy) 		Source in KM2
source in Prolog

This example might seems more verbose in KM2, but :
  • it contains much more information than just the source :
    structure of the programm example of test
  • it is more readable and more easy to understand and read
  • it shows that all functions have been tested and validated.

2.2.2. one example is the ALL macro

The ALL macro solves a recuring annoying issue when programming in prolog : generate all solutions one by one to a predicate, then do something with the rersults. Finally this should succeeed.
The classic formula in Prolog looks like this solve_and_show_solutions :- problem (P) solution (P, S) write (solution (P, S)) nl
The above predicate will solve one by one all the instances of P and solutions S, and then print them.
Suppose now we want to show all solutions
One way is to rewrite the predicate :
  • solve_and_show_solutions :- problem (P) solution (P, S) write (solution (P, S)) nl fail
    • solve_and_show_solutions.
The other way with KM2 is just to insert an ALL in the predicate :
  • solve_and_show_solutions :- ALL problem (P) solution (P, S) write (solution (P, S))
Which is obviously more simple

2.3. Easy trace of anything

 The idea is that you can change, just with a macro, a comment into a print

2.3.1. Change a comment to a print statement

This is very easy, just by changing the icon on the statement :

Usually comments are ignored in programms, but here the comment wil be printed at run time. And this can be easily suppressed later.
It is easy to choose to have comments also printed on the backtracking phase.

2.3.2. The echo macro

The "echo" macro is useful in trace.
In many programs we want to insert something like in a predicate: write ("k = ") write (K) nl
Here we just write : echo K
The trick is just to define a macro : echo ::= write ("{a1} =") write ( {a1} ) nl
now we can compare the process with a simple function :
Prolog standard source
  • fact (K, 1) :- k < 2 ! fail
  • fact (K, N) :-
    • k >= 2
    • K1 is K -1
    • fact (K1, N1)
    • N is N1 * K

enhanced source with inside trace
3rd phase : the program is working

We see the power of using icons while programming : we can change the behaviour of the programm very easily.
KM2 - PROLOG MACROS REFERENCE GUIDE

3. KM2 - PROLOG MACROS REFERENCE GUIDE

 NOTE MACROS are defined in the same file under the "notation prolog" topic

3.1. Macros for lists and automatic macros

3.1.1. Prolog 2 notation inside swi-prolog

This notation was added to ease the writing and reading of source code.
Base equivalent to
X . Y .. L [X, Y | L]
X . Y [X, Y]

3.1.2. White spaces


in Prolog, the designation of a term is in the form "f (X, ...)".
The term "f (X, ...)" will generate an error, just because of the 'space' between the 'f' and the '('.
The KM2 preprocessor supppresses all leading whites.
NAME Purpose Appearance Result
remove excedent spaces for functions in prolog, "f (x)" is correct, but "f    (x)" is not
The purpose of this macro is to remove all 'spaces' between function and first parenthesis of argumenst


3.2. Macros for defining functions
NAME Purpose Syntax Source Result
define a database use a fully tabular description for tabled data
NOTE : an alternative in swi-prolog is
  • to load a csv file
  • define a predicate from this table
  • (use function
© DEF_DB {pred_name}
  • {table with colums as arguments}


define a just regular predicate simplify and standardize the expression of predicates © DEF {pred_name}, {arguments}
  • {table args, goals and notes columns}


define a predicate with inputs and outputs identified simplify and standardize the expression of predicates © DEF_IO {pred_name}, {arguments}
  • {table input_args, outpu_args, goals and notes columns}
The order of columns is not important :

3.3. Control macros
NAME Purpose Syntax Source Result
DOC Define a simple and more readable way to define herarchical text.
Also, for the source in Xmind, graphics can be added, but which will not appear in the prolog file. 		© DOC
  • {L}
with images in the source !

IF readable and stackable format of IF
there are 2 forms of 'IF' depending if the condition is placed just after the 'IF' or is a subtree in itself 		© IF {Condition}
  • {YES}
  • {No}

© IF
  • {CONDITION}
  • {YES}
  • {No}


OR readable and stackable format of OR © OR
  • {OPTION_A}
  • {OPTION_B}


NOT NOT of a sequence © NOT {tree}
ALL : all answers and succeed In prolog, you need frequently to write functions to process all elements of a list or solutions to an equation. And at the end you want the predicate to succeed
For exemple
  • print_all ([X|L]) :- print (X) print_all (L)
  • print_all ([]).

Now you can just use
  • print_all (L) :- ALL member (X, L) print (X)



3.4. Trace and debug macros

3.4.1. Definitions

NAME Purpose Appearance Result
trace comment display the comment while the prolog processor runs on it


mnemotechnics : the comment will just fly to the user 		write ('this is a comment")
trace comment and trace backtrack display the comment while the prolog processor runs on it

mnemotechnics : the comment will return the call to the user 		(
  • write ("==> this is a comment")
  • ;
  • write ("<== this is a comment") fail
  • )
echo value echoes the term on the terminal
equivalent to write (" = ") write ()
echo foo (X)
  • write ("foo(X)")
  • write (foo (X))
  • nl

3.4.2. Full examples of trace macros

In KM2 , just by changing (one click) the icon on a node allows to change the generated code :
Case source code generated code execution
trace all


trace nothing


Some examples

4. Some examples
We present hereafter some simple examples for comparisons:
  • the queens problem
  • a small graphics animation

4.1. The queens problem

 The queens problem tries to solve the problem of the position of N queens with the rules of the chess game on a board of size NxN, where the queens can not take each other.
SOURCE CODE IN KM2

The documentation in the source file looks like this :

The code part
code in Pure Prolog

Code documentation :

Standard Prolog code :

4.2. Drawing an animation

 The goal is to generate a small animation using the pce library.
SOURCE IN KM2

DOCUMENTATION

drawing what we want in the code makes the programm clear in its objectives
Code :

  1. As there is a systematic way to create graphic objects, we use a table to describe what we want, and the correct order : this makes sure that we don't forget anything
  2. We use the blue arrow symbol as a macro to specify the "send" process in much more readable maner.
  3. The structure of the programm is clearly visible through the indentation inKM2, while it is not anymore in Pure Prolog.
SOURCE IN PROLOG


  1. The code is very flat : the underlying structure is not visible
  2. Some lines are quite "encrypted"
  3. The systematic aspect of creating and displaying obects is not visible anymore
  4. Need of a large screen to display all the code at once.
Trace of animation on terminal :
SOMMAIRE