usr_zip works (again)
[gule-log:guile-log.git] / doc / guile-log.texi
1 \input texinfo @c -*-texinfo-*-
2 @c
3 @setfilename guile-log.info
4 @settitle Preliminary Manual
5 @c
6
7 @copying
8 This is a preliminary manual of guile-log package for guile-2.0
9 Copyright @copyright{} 2012 Stefan Israelsson Tampe
10 @end copying
11
12 @titlepage
13 @title Guile Log
14
15 @c The following two commands start the copyright page.
16 @page       
17 @vskip 0pt plus 1filll
18 @insertcopying
19 @end titlepage
20
21 @ifnottex
22 @node Top
23 @top Guile Log
24      
25 Documentation for the Guile-Log Logic Programming Environment for Guile 2.0 v0.4
26 @end ifnottex
27      
28 @menu
29 * umatch::                 low level infrastructure.
30 * guile-log::              This is the guile-log basic macro environment
31 * acumulators/generators:: Hot to collect and generate sequences of solutions.
32 * postpone::               To postpone a search.
33 * dynamics::               catch prompt abort
34 * dynamic-functions::      Dynamicaly add, remove and execute clauses
35 * parsing::                A parsing framework.
36 * sed/grep::               Sed and grep functionalities for scheme
37 * kanren::                 Kanren implemented ontop of guile-log
38 * prolog::                 iso-prolog 
39 * Index::                  Complete index.
40 @end menu
41
42
43 @node umatch
44 @chapter Overview
45 umatch in (logic guile-log umatch) represent the lower level routines 
46 implemented in C code and loaded by that module. A matcher targeted to be
47 used in code handling the unify variables is defined as well.
48
49 @section umatch
50 @findex umatch
51
52 umatch is a matcher that derives from (ice-9 match) with some extra features that relates to unifying variables. The usage is
53
54 @verbatim
55   (umatch [#:status s] [#:mode *] [#:status #f] [#:tag w] [#:name "anon"] [#:raw #f] (m ...) 
56      (pat ... code) 
57      ...)
58    
59    with pat utilizing: 
60
61      (p . q) _ , and set! get! #(...) = `
62
63    form ice-9/match plus ',' and the following symbols should not be used in 
64    fuctional position: 
65
66       or not cond ... ___ ,@ *** <> arguments $   
67 @end verbatim
68 ',' can be used to quote a variable from the outside of the match 
69
70 @code{(set! s)} will define a setter @code{s} that can be used in e.g. @code{(<and> (s 1) ...)}, for @code{<and>} refere to guile-log.
71
72 @code{(get! g)} will define a getter g used with an argument representing the current state like e.g. @code{(g S)}, with @code{S} beeing define in the guile-log section.
73
74 [#:mode +] is used to set the kind of matcher that is initially valid it can be 
75 either of + ++ - * (see below for an explanation of these)
76
77 [#:tag w], that tag that related to backtracking to the next matcher. e.g.
78
79 @verbatim
80   (umatch #:tag next ('(1 2 3))
81       ((x y z) (if (number? x) (next) x))
82       ((x . l) l))
83   => '(2 3)
84 @end verbatim
85
86 [#:name "anon"], this is used when outputting error messages
87
88 [#:raw #f], do not use this, this + #:mode + is the same as #:mode ++
89
90 [#:status #f], This is where the state variable should be it must be a variable
91 which contains the current state at the entering of the matcher. This syntax symbol is resetted with new state at unifications and similar constructs which may enter new information onto implicit stack or explicit state info.
92
93 @code{(m ...)}, is a sequence of elements to be matched in parallel
94
95 @code{(pat ... code)}, if pat is a pattern to use to match a m the last form is the code to execute if all patterns matches.
96
97 @section Directives
98 The following feature is added to the ice-9 matchers
99 @itemize
100 @item
101 @code{(+ p ...)} will match @code{(p ...)} with the framework @code{+}
102 @item
103 @code{(+ + p)} will match @code{p}       with the framework @code{+}
104 @end itemize
105
106 The frameworks are,
107 @verbatim
108   (*  (car    cdr    pair?     null?       equal?        id)))))
109   (+  (gp-car gp-cdr gp-pair!? gp-null!?   gp-unify!     gp-lookup))
110   (++ (gp-car gp-cdr gp-pair!? gp-null!?   gp-unify-raw! gp-lookup))
111   (-  (gp-car gp-cdr gp-pair?  gp-null?    gp-m-unify!   gp-lookup))
112 @end verbatim
113
114 Toe explain more,
115 @itemize
116 @item
117 @code{*} : the usual list framework
118
119 @item
120 @code{+} : @code{(match (+)  (1 v) (w 2))} matches and @code{v=2,w=1}
121  with a recurrence check e.g. if any self referenceing will appera in the matcher then the match fails. This is the safe way to do a unifying match.
122
123 @item
124 @code{++} : @code{(match (++) (1 v) (w 2))} matches and @code{v=2,w=1} without 
125 a recurrence check. Do this with care cause cyclisity is unsupportand and can
126 lead to a blowup of the stacks.
127
128 @item
129 @code{-} : @code{(match (-)  (1 (v = 2)) ((w = 1) 2))} matches unify 
130 variable @code{v = 2} at the start e.g. unify variable is looked up but never bounded.
131 @end itemize
132
133 Also unquote directive is used in the matcher to signal an evaluation e.g. in 
134 @verbatim
135   (umatch (x) 
136     ((a ,(+ z w)) a)) 
137      (+ z w)))
138 @end verbatim
139 @code{(+ z w)} will be first evaluated and then used in matching.
140
141 @section low level api
142 in (logic guile-log umatch) a large set of unify constructs are loaded from a
143 library defined in C, this api are,
144
145 @section stack banks
146 @findex *current-stack* 
147 @findex gp-make-stack
148 @findex gp-clear
149 The work is done with state objects containing appropriate stacks, rewind information and the assoq list of bindings. You will have the notion of a current 'gp' state that is a fluid representing the current stack in use. Also there is a *current-state* fluid that holds the current assoq binding list/tree. You can create new stacks. The setup can be thread safe in the meaning that if you try to set a logic variable that is not associated to the supplied stack then a binding will be done by logically consing it to a datastructure that has the same functional behavior as an assoq list on the supplied state data and returned. This means that a large class (but certainly not all) of interop issues between multiple threads is solved. A state or stack datastructure will hold information on what thread-id it belongs and also have a unique id. The stack consists of actualy 4 stacks, one control stack (nc) one datastack (ns) and a stack of allocated cons cells (ncs) and one that holds the equivalent of fluids and guards. The control stack will contain unwind information, dynwinds and binding information. The cons stack is not used currently, it can be used to implement closure objects that is created from the stack in stead of the heap, we currently do not use this becuase other overhead is more significant currently e.g. the guile call overhead to C-funcitons. The dynstack is specaial in that its data is recreated at each wind. It represent the expensive winding that essentially originates from the guards and from the equivalent of fluids. Note that multiple reinstation of the other stacks are really cheap in that it does no consing, by allowing e.g. gp-fluid-set! we must pay with copying the stack at each wind, now by separating the small dynstack from the rest we get an important optimization.
150
151 @code{*gp*}, fluid that holds the current gp-stack
152 @code{*current-stack*}, fluid that holds the current assoq
153 @code{(gp-make-stack id thread-id nc ns ncs)}
154 Allocate a new state datastructure with identity number @code{id}, thread identity number @code{thread-id} and the sizes of the different stacks. Also it will be stupped so it can be used to unwind to e.g. w can reset the stack to the initial state calling @code{gp-unwind} with it.
155
156 @code{(gp-clear state)}, Reset the state to it's initial setup.
157
158 @section Redo safe variables and redo safe parameters.
159 @findex gp-undo-safe-variable-guard                
160 @findex gp-undo-safe-variable-lguard                
161 @findex gp-undo-safe-variable-rguard                
162
163 A redo safe variable is a ordinary scheme variable object or fluid object that has the property that its state will be intelligently stored and retrieved under various premisses. Essentially if there is no mutattion further down the stack we can use the @code{guard} version. Else between lguard and rguard the variable is guaranteed to have restorage property independent of mutation or not.
164
165 @code{(gp-undo-safe-variable-guard var kind s}
166 @code{(gp-undo-safe-variable-lguard var kind s}
167 @code{(gp-undo-safe-variable-rguard var kind s}
168
169 @code{var} is a guile variable or fluid. We have a control parameter @code{kind} which must not be a GP variable. and s containes the guile-log assoq state.
170
171 At rewind in context @code{K}, the rules for restoring the state is as follows
172 @itemize @bullet
173 @item @code{kind = #t}, restore the state.
174 @item @code{kind = #f}, do not restore.
175 @item @code{K = #t}, restore the state.
176 @item @code{K = #f}, do not restore.
177 @item @code{kind, number and K, number} Then we will restore the state if @code{K <= kind}.
178 @item else do not restore the state.
179 @end itemize
180
181
182 @section Managing stack frames
183 @findex gp-newframe
184 @findex gp-unwind
185 @findex gp-store-state
186 @findex gp-restore-state
187 @findex gp-restore-wind
188
189 Stack has a stack pointers to undo stacks a data stack and a cons stack and dynstack, by walking up and down these stacks we can recreate a state. The most lightweight way of winding is to use @code{gp-newframe} and @code{gp-unwind} where you can only go to a previous stack point stored by @code{gp-newframe} and doing that the system forgets everything. This is fast and with no memory overhead. The other mode of operation using @code{gp-store-state},@code{gp-restore-state} and @code{gp-restore-wind} will go the full way and keep everything in memory until you drop and references to the returned state information and the gc can kick in at recollect the data. @code{gp-store-state} will make a state data structure suitable to be for this mode of operation and @code{gp-restore-state} will restore the infromation either backward or forward in time. Then the setup will be precisely as when the store operation was issued. To note here is that sometimes you would like to use the store and restore operation in a mode that follows a calculation like with the interleaving constructs for this operation it is very nifty to have global variables like if they lived on the heap to implement the logic. The downside is that with heap objects you typically cannot restore a state if you would like to do that. Guile log has a nifty framework to define variables that behaves just like these heap variables but with the difference that they are automagicaly restored when the user issues the @code{gp-restore-state}. In order for this to work we use @code{gp-restore-wind} internally when we store and restore information as we follow an algorithmic calculation path.
190
191 @code{(gp-newframe s)}, returns the current frame incorporated in a state variable state of the stack in order to be able to backtrack.
192
193 @code{(gp-unwind s)}, backtrack to state represented by @code{s} that should have been returned by @code{(gp-newframe s)} e.g. a state data structure.
194
195 The next two command is mirroring the two commands above. But for these we don't impose the restriction to only go back in time, we can freely restore a state. Memory wise and performance this is heavier. But to note is that we do tree compression e.g. we try to reuse as much data as possible.
196
197 @code{(gp-store-state s) -> state}, Gives a state that can be used to restore a state, this makes the unify stack act well together with call/cc constructions or using continuation closures e.g. it is possible to do continuations with these prolog stacks. Note that this is a very effective storage mechanism, basically the continuation is stored in a tree like structure.
198         
199 @code{(gp-restore-state state)}, Restore a state that is saved by gp-store-state
200
201 @code{(gp-restore-wind state wind)}, the same as above, but they will not change the dynamic globals e.g. guarded variables to the old state depending an the algorithm described in teh beginning of this section.
202
203 @section The gp fluid
204 @findex gp-fluid-set
205 For a guile variable or more prefereble (it is thread safe) for a fluid we can model it as a guile fluid but living on the guile-log stacks in stead. For this to work just use @code{variable-ref, variable-set!, fluid-ref, fluid-set!} and 
206
207 @code{(gp-fluid-set var val)}
208 This will bind var to val for the rest of the guile log stacks, e.g. similar to guile's with-fluids.
209
210 @section The guile log variables
211 @findex gp-var!
212 @findex gp->scm
213 @findex gp-budy
214 @findex gp-var?
215 @findex gp-lookup
216 @findex gp-var-number
217 @findex gp-set!
218
219 @code{(gp-var!)}, generate a new unify variable. E.g.
220 @verbatim
221   scheme(guile-user)> (define a (gp-var!))
222   scheme(guile-user)> (define b (gp-var!))
223   scheme(guile-user)> a
224   $7 = <#0>
225   scheme(guile-user)> b
226   $8 = <#1>
227   scheme(guile-user)> (gp-unify! a b)
228   $9 = #t
229   scheme(guile-user)> a
230   $10 = <#1>
231   scheme  (guile-user)> b
232   $11 = <#1>
233
234 If executed under logical kanren assq feature then the variable is created on the heap, else it is created on the stack.
235 @end verbatim
236
237 @code{(gp->scm x s)},  Take a unify variable and a state and turn it into a 
238 list representation, variables is transfered as is.
239
240 @verbatim
241   scheme(guile-user)> (u-set! a '(1 2))
242   scheme(guile-user)> a
243   $17 = <#gp (1 2)>
244   scheme(guile-user)> (gp->scm a)
245   $18 = (1 2)
246 @end verbatim
247
248 @code{(gp-budy x)}, it is possible to pair variable if you do
249 @verbatim
250   (let ((x (gp-var!))
251         (y (gp-var!)))
252     ...)
253 @end verbatim
254 Then inside ...  @code{y = (gp-budy x)}.
255
256
257 @code{(gp-var? x s)}, @code{#t} if @code{x} is a not bounded unify variable.
258 @code{s} is the current state.
259
260
261 @code{(gp-lookup x s)} If @code{x} is a unify variable it tries to find the element it points at using state information in @code{s}. If it is a unify variable that is returned, if it's a scheme object that is returned If it's a unify cons, that is returned.
262
263 @code{(gp-var-number x)}, the variable number identifying a gp variable.
264
265 @code{(gp-set! v a s) -> s}, set looked up unify variable @code{v} to @code{a}.
266 using state @code{s} e.g. @code{v} is looked up until the last variable pointing to a scheme variable. It may change the state and a new state is returned.
267
268 @section guile log pairs
269 @findex gp-cons!
270 @findex gp-pair?
271 @findex gp-car
272 @findex gp-cdr
273
274 @code{(gp-cons! x y)}, makes a unify cons variable out of @code{x} and @code{y}. To note here is that these conses are faster to allocate and they work well with rebounding later on and backtracks correctly.
275
276 @code{(gp-pair? x s) -> s}, checks to see if @code{x} is a pair or a unify pair
277 not a variable is will retrun false- Here the returned state is always the same
278 as the input. @code{x} is assumed to have been looked up.
279                      
280 @code{(gp-car x)}, takes the car of a unify pair or ordinary pair. @code{x} is
281 assumed to have been looked up.
282
283 @code{(gp-cdr x)}, takes the cdr of a unify pair or a ordinary pair @code{x} is assumed to have been looked up.
284
285
286 @section unifying
287 @findex gp-unify!
288 @findex gp-unify-raw!
289 @findex gp-m-unify!
290
291 @code{(gp-unify! x y s) -> s or #f}, @code{s} if @code{x} and @code{y} 
292 unifies with a recurrence check e.g. loop detection. @code{#f} if they do not 
293 unify (note that although this is false variables could have been unified so @code{#f} is usually followed by a @code{(gp-unwind Frame)}) e.g.
294 @verbatim
295   (let ((Fr (gp-newframe)))
296      (if (gp-unify! x y)
297           #t
298          (begin (gp-unwind Fr) #f)))
299 @end verbatim
300      
301
302 @code{(gp-unify-raw! x y s) -> s or #f}, the same as @code{gp-unify!} but now loop detection e.g. we can end up in an infinite c-recursive loop and the stack will eventually be consumed and an error reported.
303
304 @code{(gp-m-unify! x y s) -> s or #f}, the same as @code{gp-unify!} but now variables are not bounded, if x is a variable then y must be the same variable and vice verse in order to unify.
305
306
307                      
308 @section guile log fluids guile log dynwinds
309 @findex gp-make-var
310 @findex gp-var-set!
311 @findex gp-var-ref
312 @findex with-gp-vars
313 @findex gp-dynwind
314 @findex push-setup
315 @findex que-setup
316
317 Fluids functions does not change the stack parameters it is a buggy interface because the kind of stack sign should be in the state parameter that should be used as well as input.
318
319 @code{(gp-make-var),(gp-make-var init)} makes guile log variable on the heap and an optional init value, @code{init}.
320
321 @code{(gp-var-set! v x)} set! a guile-log variable without backtracking !danger! do not use this anywhere else then a before a first @code{gp-var-set} have 
322 been issued on the variable.
323
324 @code{(gp-var-set v x)} set a guile-log variable with backtracking the guile 
325 stack is forced to be used to handle the backtracking.
326
327 @code{(gp-var-ref v)} reference a guile-log var.
328                      
329 @code{(gp-dynwind Redo Do Undo)} a similar tool as the dynwind construction but this one follows the current bank stack and not the call stack. Again 
330
331 These two should only be used by experts.
332 @code{(push-setup thunk)}, this will push a @code{thunk} on the push stack, a setup is code that is run after the winding has ben done, typically this is used inside a dynwind.
333
334 @code{(que-setup thunk)}, this will que @code{thunk} on the setup que  that is executed after the winding of the stack have been done.
335
336 N.B. the setup stack is executed before the setup que.
337
338
339
340
341 @section Kanren logical variables support
342 @findex use-logical
343 @findex leave-logical
344 @findex gp-stack-set
345
346 In kanren the interpretation of a variable is goverend in a state that behaves
347 as an assq list. To find a value of a binding that list are searched for a 
348 binding. now this datastructure need not be a assq list, only sematically 
349 behave like it and that it need to be functional. The benifit is mainly that 
350 multiprocessor support is trivial by having such a feature. The intention is to
351  execute the usage seamlessly in the background but uit can be beneficial to 
352 force the usage of them and therefore there is a public interface with
353 primitives.
354
355 @code{SCM (use-logical)}
356 @code{SCM (leave-logical)}
357 To mark that the engine enters a region where it uses kanren logical structure 
358 excecute the @code{use-logical} function, and to leave use the other form. 
359 These codes will add guards on the stack as well in order for it to work 
360 seamlessly with regards to backtracking and state restorage.
361
362 @code{(gp-stack-set! x v s) -> s}, forces the usage of the stack as
363 a method of doing an undoable set.
364
365 @section spurious commands
366 @findex gp-print
367 @findex gp-printer
368 @findex gp-copy
369 @findex gp-get-stack
370
371 @code{(gp-print x)} debug tool, prints out information of the internal representation of @code{x}.
372                                                   
373 @code{(gp-printer port x)}, the printer used to print unify variables
374
375
376 @code{(gp-copy x)} Makes a copy of @code{x}, but copy the references to variables and not the variables them self
377
378 @code{(gp-get-stack)}, a debug tool. Yields the control stack containing undo information.
379
380
381
382 @node guile-log
383 @chapter Guile-log
384 Guile log is a basic framework of macrology that implements functionality that can be compared to both kanren and prolog plus some extra features. The feature set is close to what can be accomplish with plain kanren but more at the speed of prolog. Usually kanren is a more expressive way of implementation and can many times easier be extended with new features, on the other hand, most features in kanren is available in guile-log and performs about 10x faster then scheme kanren. Other possibilities are using the kanren interface ontop of guile-log and then the speed difference is about a factor of 2 slower then guile-log close to the speed that kanren does in compiled chicken.
385
386 Guile log performs it's actions in a guile-log mode e.g. small scheme like language that behaves in a certain way defining functions for this environment can be done with sugared functions or with a special macro definition.
387
388 A guile log function is a function where the first argument represent the current state, the second argument the failure thunk and where the third argument represent a continuation lambda. It's possible to write macros that works in guile log mode.
389
390 A failure thunk is a thunk that is evaluated at failure and usually the stack backtracks in this lambda. The continuation lambda takes a satte and a failure thunk as it's argument which represent the current failure and then execute it's body as the continuation of the algorithm. e.g.
391
392 guile-log has one aspect that kanren does not have and this is the notion of going up and down a stack at redo and undo. With this we have a notion that is very similar to a dynamic-wind, which can guard constructs. With this it is pretty simple to instrument tracing to not only trace upward but also at the same point track the backtracking. This is not possible in kanren. With this it is possible to keep the number of guarded variables to a minimum something kanren cannot do due to the lack of stack notion. On the other hand it is possible like in the reference implementation of kanren to get away with guarded variables by either using delimited continuations or using special return values. But for some constructs guarded variables is pretty much needed e.g. acumulator like constructs and delimeted continuations.
393
394 Kanren does one thing pretty well and that is that it can support a notion of tail-call's. We do have options for guile-log to accomplish this as well and hence it is possible to write algorithms in guile-log without risk blowing the stack.
395
396 To see how the code is designed we can describe,
397
398 the failure thunk semantic,
399 @code{(lambda () (unwind) (try-alternative-path))}
400
401 the continuation lambda (cc)
402 @code{(lambda (state fail) (execute-next-fkn state fail))}
403
404 To see how they work consider the @code{(<and> (f) (g))}, @code{<and>} is a directive that represent a sequencing of facts and here the guile-log functions @code{f} and @code{g} will be tried in sequence e.g.
405
406 @verbatim
407   (<and> (f) (g)):
408      (lambda (state fail cc)
409        (f state fail (lambda (state2 fail2) (g state2 fail2 cc))))
410 @end verbatim
411
412 Likewise an or (e.g. try @code{f} and if @code{f} fails try @code{g}) clause could be defined 
413 @verbatim
414   (<or> (f) (g)):
415     (lambda (state fail cc)
416       (let ((fr (gp-newframe)))
417         (f state
418            (lambda () 
419               (unwind fr)
420               (g satte fail cc))
421             cc)))      
422 @end verbatim
423
424 Writing these forms in plain scheme is a bit tedious so it is nice to have
425 macros that does this for us. Note here that Kanren very much the same way (A read and understanding of the Kanren source code and/or Reasoned Schemer is a good background in using this tool)
426
427 You do find the notion of a cut in prolog and you do have it in guile-log as well. Kanren does not have it explicitly. But basically a cut is maintaining a failure thunk that typically represent backtracking from the function etc. The cut is not a parameter in the functions and hence is a notion that relates to the macrology in the source code, hence typically a guile-log macro looks like
428
429 @verbatim
430 (define-guile-log macro
431   (syntax-rules ()
432     ((_ (cut s p cc) code ...)
433       do-something-here)))
434 @end verbatim
435
436 So we see that guile-macros by convention have that quadruple as a first 
437 argument. Note the cut parameter, the rest is just the plain old parameters you got in the first three function arguments.
438
439 The guile-log is simply looking at forms and if it sees a sexp where the car is
440 a guile-log macro it will insert the @code{(cut s p cc)} as a first argument 
441 and evaluate that macro. Else the sexp is assumed to be a function and guile log
442 will put the @code{p} and the @code{cc} in front and execute that. e.g. to define or a non guile-log macro you typically use,
443
444 Kanrens version of or-i and and-i e.g. the interleaving versions of 'or' and 'and', and scale better, the reason is that in guile-log the stack is moved back and forth between states which is unnecesary in kanren where the interpretation of variables is via a state consisting of a list representing a stack or via a functional tree. On the other hand, in guile-log we can make use of dynamic wind constructs which are impossible to get right in kanren.
445
446 Threading is not supported in the lower levels, e.g. umatch in guile-log and here Kanren is much better off. In principle this is something that can be improved uppon, but we postpone that to later versions of guile-log.
447
448 guile-log is safe with respect to undo/redo, you can stall everywhere and expect to be able to store the state, and later retrieve it.
449
450 Functions @code{(f args ...)} in guile-log is defines as
451 @verbatim
452   (define (f s p cc args ...) code ...)
453 @end verbatim
454
455
456 @section Basic logic
457 @findex <and>
458 @findex <or>
459 @findex <and!>
460 @findex <and!!>
461 @findex <not>
462
463 @code{G.L. (<and> p1 p2 ...)}, perform @code{p1}, if success then @code{p2} and so on.
464
465 @code{G.L. (<or> p1 p2 ...)}, perform @code{p1}, if @code{p1} fail then backtrack and try @code{p2} ...
466
467 @code{G.L. (<and!> p1 p2 ...)}, same as @code{<and>} but yields at most one answer.
468
469 @code{G.L. (<and!!> p1 p2 ...)}, the same as @code{(<and> (<and!> p1) (<and!> p2) ...)} e.g. at most one answer from @code{p1} and at most one answer from @code{p2} etc. 
470
471 @code{<and!>} and @code{<and!!>}, are useful when we  want to restrict the search space and when a local success correlates to a global one.
472
473 @code{G.L. (<not> p ...)}, successes if @code{(<and> p ...)} fail and fails otherwise. In either case the form will always backtrack and no variables will be bound inside this form.
474
475 @findex <if>
476 @findex <if-some>
477 @findex <cond>
478 @findex <or-i>
479 @findex <or-union>
480 @findex <zip>
481 @findex <call>
482 @findex <//>
483 @findex <update>
484 @findex <succeeds>
485 @findex <and-i>
486 @findex interleave
487 @findex interleave-union
488 @findex and-interleave
489 @code{G.L. (<if> p x)}, if @code{p} is a success then @code{x}, @code{p} will only success at most one time.
490
491 @code{G.L. (<if> p x y)}, if @code{p} is success then @code{x}, else backtrack and use @code{y}, the same condition holds on @code{p} as the previous version of if.
492
493 @code{G.L. (<if-some> p x)}, the same as @code{(<and> p x)}.
494
495 @code{G.L. (<if-some> p x y)}, logicaly the same as @code{(<or> (<and> p a) (<and> (<not> p) b))}.
496
497 @code{G.L. (<cond> (P X) ...)}, like the ordinary cond, but using @code{<if>} in stead of @code{if}
498
499 @code{G.L. (<or-i> p1 p2 ... pn)}, if @code{p1} successes and we later backtrack then try @code{p2} etc and so on until @code{pn} if @code{pn} successes and we later backtrack then @code{p1} is tried again and interleave like that. To note here is that this form uses both bank a and b and in order to function correctly when storing a state both bank a and bank b need to be stored.
500
501 @code{G.L. (interleave l)}, the same as @code{<or-i>} but with the difference l is a list of lambdas typically made by @code{(</.> ...)}.
502
503 @code{G.L. (<or-union> p1 ...)}, this is like @code{<or-i>} but if @code{pk} has a success and if, the goal @code{pl}, l > k,  succeses like in (<and> pk pl) then we will backtrack, this means that duplication of results is in a sense removed.
504
505 @code{G.L. (interleave-union l)}, see @code{interleave}.
506
507 @code{G.L. (<and-i> p1 p2 p3 ...)}, and interleaving! this is an and which will in parctice behave as
508 @verbatim
509   (<and-i> (<or> A B) (<or> C D))
510   <=>
511   (<or> (<and> A C) (<and> B C) (<and> A C) (<and> B C))
512 @end verbatim
513 e.g. backtracking is shallow and we will backtrack all the first combinations, then all the second combinations then all the third ones etc. To accomplish this state information needs to be stored hence using this tool can be slow and memory intensive.
514
515 @code{G.L. (and-interleave l)}, the same as @code{<and-i>} but with the difference l is a list of lambdas typically made by @code{(</.> ...)}.
516
517 @code{G.L. (<succeeds> p)} will try @code{p} and if it succeeds undo any bindings and continue.
518
519 @verbatim
520 G.L. (<zip>  (w        g ...) 
521              ((v ...)  h ...) ...)
522 @end verbatim
523 This is executing n guile-log programs in paralell e.g. when backtracking all
524 of the programs are backtracked in one go. The interface to the outside is via
525 variables @code{w} @code{(v ...)} etc. (one can either specify a variable or a list of variables. The variables represents the interface for the continuation of the program. So all the programs are executed one by one staring with the first one yielding a construction of what for example w should be bound to, that information is stored and then everything done from the state at the start of the @code{<zip>} is unwinded and restored. Then the stored representation of @code{w} etc. are at the end of the zip where we have unwinded back to the start the information is unified with the original variables and then the code will continue with the continuation. A backtracking to the zip will backtrack all of the goal sets in paralell again starting with the first and new values for the interfacing variables are constructed.
526
527 Conside the following definition of a function @code{f},
528
529 @verbatim
530 (<define> (f x n)
531   (<or> (<=> x n)
532         (f x (+ n 1))))
533 @end verbatim
534
535 this function can be used to illustrate the zip by,
536
537 @verbatim
538 (<run> 5 (x y) 
539   (<zip> (x (f x 0)) 
540          (y (f y 1))))
541
542 > ((0 1) (1 2) (2 3) (3 4) (4 5))
543 @end verbatim
544
545 @code{G.L. (<call> ((l x) ...) code ...)}, This will call @code{(<and> code ...)} and at success it will store the values x ... and then backtrack and unify the copied @code{x} to @code{l}. At backtracking the state will be reinstated. Use this when you want to avoid side effets when calling a stub.
546
547 Example:
548
549 @verbatim
550 (<run> 5 (x y) 
551    (<call> ((x y)) (f y 10))
552    (<=> y -1))
553
554 => ((10 -1) (11 -1) (12 -1) (13 -1) (14 -1))
555 @end verbatim
556
557 @code{G.L. (<//> ((fail ((xx x) ... ) code ...) ...) body ...)}
558 @code{G.L. (<update> (fail vals ...) ...)}
559 This is close to functionality to @code{<zip>} but somewhat on steroids and a few 4 - 5 times slower. The main usage is when we need to try out two logics in paralell and they are not nessesary in sync. In @code{(fail ((xx x) ...) code ...)}, @code{(<and> code ...)} will be evaluated and any resulting values @code{x} will be copied and stored in the introduced variable @code{xx}. The failure tag can be used to tell guile-log to only backtrack that part of the arm. This is done via a @code{(<update> (fail vals ...) ... )}. Typically the first part of the @code{body} is a guard that evaluates if they are on synch and if not, say branch @code{f1}, needs to update you can do so by @code{(<update> (f1))} or @code{(<update> (f1 p))} with @code{p} a variable containing a failure thunk captured inside the arm. Typically @code{p} has before been intrioduced with @code{(letg ((p #f)) co ...)} and then @code{p} is setted to for example the Current failure thunk @code{P} inside the arm.
560
561 Example:
562
563 @verbatim
564 (<run> 1 (x y) 
565    (<//> ((f1  ((xx x)) (f x 1))
566           (f2  ((yy y)) (f y 10)))
567       (if (< (<scm> xx) (<scm> yy))
568           (<update> (f1))
569           <cc>)
570       (<=> (xx yy) (x y))))
571
572 => ((10 10) (11 11) (12 12) (13 13) (14 14))
573 @end verbatim
574
575 @section Probing The Control Variables                          
576 @findex S
577 @findex CC
578 @findex CUT
579 @findex P
580 It is possible to probe the curretn variables that is transported behind the sceene, use the syntax-parameters @code{S,CC,CUT,P} to reach them inside guile-log code.
581
582 @section Guarded variables
583 @findex <let-with-guard>
584 @findex <let-with-lr-guard>
585 @findex let-with-guard
586 @findex let-with-lr-guard
587 This are lower level constructs usable for designers of logical ideoms. Their
588 purpose is to allow for constructs that need to add variables to store a state 
589 across multiple backtrackings to mix well with postpone and undo/redo.
590
591 @code{G.L. (<let-with-guard> wind guard ((var init) ...) code ...)}, This construct will bind @code{var ...} with init values @code{init ...} just as with @code{let}. The difference is that we can guard execution of no mutation with e.g.
592
593 @code{G.L. (guard Lam)} e.g. @code{Lam} neede to be a guile log closure for 
594 which the code should be safe to undo and redo if not mutated. @code{wind} 
595 refers to the current wind level and use it in
596
597   @code{(gp-restore-wind state wind)
598
599 To restore at the current wind level meaning that any @code{let-with-guard}
600  construct inside @code{code ...} will be restored but the defined @code{var ...} will not be restored, if that is wanted then use @code{(- wind 1}} instead.
601
602 @code{G.L. (<let-with-lr-guard> wind lguard rguard ((var init) ...) code ...)}
603 This is very similar to the previous construct but for this ideom we define a
604 @code{lguard} and @code{rguard} in stead. That stack space between @code{lguard}
605  and @code{rguard} is strongly guarded e.g. one can mutate @code{var ...} 
606 inside that space. To the right of @code{rguard} the variables are guarded if 
607 no mutation is done in that space.
608
609 @code{scm (let-with-guard s wind guard ((var init) ...) code ...)}
610 @code{scm (let-with-lr-guard s wind lguard rguard ((var init) ...) code ...)}
611 This is scheme macro that will defined scheme macros @code{lguard} and 
612 @code{rguard} or just a @code{guard}. And the code executed inside them e.g.
613
614   @code{(guard gcode ...)}
615
616 will be protected accordingly the description above for the guile log macrology
617 versions. Finally note that @code{s} should be a symbol bounded to the current
618 environment.
619
620
621 @section Unify Constructs
622 @findex let<>
623 @findex <=>
624 @findex <==>
625 @findex <r=>
626
627 In the forms below remember to use @code{unquote} for forms that need to be scheme evaluated inside the patterns.
628
629 @code{G.L. (let<> ((m pat val) ...) code ...)}, this will pattern-match @code{val} using @code{m = (+ ++ - *)} and then pattern-match the next and so on and lastly execute a @code{(<and> code ...)}.
630
631 @code{G.L. (<=> X Y)}, unifies @code{X} and @code{Y} with occurs check 
632
633 @code{G.L. <==>}, the same as @code{<=>} but using the @code{-} matcher in stead of @code{+} meaning that no unifying is used.
634
635 @code{G.L. <r=>}, the same as @code{<=>} but using @code{++} in stead of @code{+}.
636
637
638 @section variable binding
639 @findex <let>
640 @findex <let*>
641 @findex <letrec>
642 @findex <var>
643 @findex <hvar>
644
645 @code{G.L. (<let> ((V X) ...) code ...)}, Will introduce bindings @code{V} with values @code{X} and then evaluate code in guile-log mode with an implicit @code{<and>}.
646
647 @code{G.L. <let*>}, relates to @code{<let>} as @code{let*} relates to @code{let}
648
649 @code{G.L. <letrec>}, this th @code{letrec} version of @code{<let>}.
650
651 @code{G.L. (<var> (v1 v2 ...) code ...)}, will make fresh new unify variables @code{v1 v2 ...} and use them in a G.L. @code{(<and> code ...)} e.g. the same as @code{(<let> ((v1 (gp-var!)) ...) code ...)}.
652
653 @code{G.L. (<hvar> (v1 v2 ...) code ...)}, like @code{<var>}, but variable identities is located on the heap instead.
654
655 @section failure and cc
656 @findex <cc>
657 @findex <fail>
658 @findex <cut>
659 @findex <next>
660
661 @code{G.L. <cc>}, represent a continuation or success can be used like @code{(<if> P <cc> Y)}
662
663 @code{G.L. <fail>}, will issue a failure and start backtracking.
664
665 @code{G.L. (<fail> p)}, will use @code{p} as a failure backtracking object.
666
667 @code{G.L. <cut>}, will issue a cut e.g. we will stop backtracking from here on used like @code{(<and> P1 <cut> P2)} if @code{P2} fails it will typically jump over @code{P1} and back to where the cut point is defined.
668 @code{G.L. (<cut> code ...)}, the same as @code{(<and> <cut> code ...)}
669
670 @code{G.L. (<next>)}, will backtrack to the next clause in a match (TODO: this has not been tested).
671
672 @findex <with-fail>
673 @findex <with-cut>
674 @findex <with-cc>
675 @findex <with-s>
676 @findex <peek-fail>
677 @code{G.L. (<with-fail> p code ...)}, this will use @code{p} as a failure for @code{G.L. (<and> code ...)}
678
679 @code{G.L. (<with-cut> cut code ...)}, this will use @code{cut} as a cut failure for @code{G.L. (<and> code ...)}
680
681 @code{G.L. (<with-cc> cc code ...)}, this will use @code{cc} as the continuation.
682
683 @code{G.L. (<with-s> s code ...)}, this will use @code{s} as the state.
684
685 @code{G.L. (<peek-fail> p code ...)} This will bind @code{p} to the failure thunk at this instruction.
686
687
688 @section defining function and matching
689 @findex <define>
690 @findex <lambda>
691 @findex </.>
692 @findex <recur>
693 @findex <letrec>
694 @findex <match>
695 @findex <def>
696 @findex <def->
697 @findex <<define>>
698 @findex <<define->>
699 @findex <funcall>
700 @findex <apply>
701 @findex <<lambda>>
702 @findex <case-lambda>
703 @findex <<case-lambda>>
704
705 @code{Scm (<define> (f x ...) code ...)}, this will define a guile-log function named @code{f} with arguments @code{x ...} the code will be executed under the G.L environment with an implicit @code{<and>} around @code{code ...} then @code{f} can be used inside G.L. like @code{(<and> (f x y) ...)}
706
707 @code{Scm (<<define>> (f a ...) (p ... code) ...)}, default @code{#:mode = +}
708
709 @code{Scm (<<define>> (#:mode mode f a ...) (p ... code) ...)},
710
711 This is close to prolog functions. E.g. @code{a ...} is the signature, @code{p ...} is the pattern that umatches the arguments and if there is a match then @code{code} is evaluated in @code{G.L.} context. if code failes the next line is tried unless there is a @code{<cut>} that forses a return from the function.
712
713 @code{Scm (<<define->> (f a ...) (p ... code) ...)}, default @code{#:mode = -} e.g. non unifying match.
714
715 @code{Scm, (<def> (f a ...) (p ... code) ...)}, 
716
717 @code{Scm, (<def-> (f a ...) (p ... code) ...)}, 
718
719 This is as with @code{<<define>>,<<define->>} but if @code{code} fails it will issue a cut and leave the function.
720
721 @code{Scm (<lambda> (x ...) code ...)}, this similar like define but an anonymous function.
722
723 @code{Scm (<<lambda>> (p ... code) ...)}, this is anonymous @code{<<define>} without explisit arguments and mode. 
724
725 @code{Scm (<case-lambda> ((a ..) code ...) ...)}, th guile-log @code{case-lambda} version.
726
727 @code{Scm (<<case-lambda>> ((p ... code) ...) ...)}, this is the @code{case-lambda} version of @code{<<lambda>>}.
728
729 @code{Scm (</.> code ...)} This is @code{(<lambda> () code ...)}.
730
731 @code{G.L. (<recur> n ((w v) ...) code ...)}, this works like the corresponding named let but in guile-log mode but it defines the loop function @code{n} to work inside G.L. and the form itself is in G.L.
732
733 @code{G.L. (<letrec> ((v x) ...) code ...)}, this will bind @code{v ...} with @code{x ...} in a letrec manner and then execute @code{code ...} with an implicit @code{<and>} around it.
734
735
736 @code{G.L. (<match> [#:mode +] (pat ... code) ...)}, this is a small wrapper around umatch the difference is that if works under G.L. and that code is evaluated under G.L. and that backtracking is correctly setup-ed.
737
738 @verbatim
739 Scm (<def>      (f [#:mode +] a ..) (p ... code) ...))
740 Scm (<<define>> (f [#:mode +] a ..) (p ... code) ...))
741 @end verbatim
742 This is a sugar for essentially, @code{(<define> (f a ...) (<match> [#:mode +] (a ...) (p ... code) ...))}. The difference is that @code{<<define>>} will never backtrack to a new match row and @code{<def>} will backtrack to the next matcher if the code part fails.
743
744
745 @code{G.L. (<funcall> f . l)}, this is actually funcall with the difference is that it will make sure to lookup @code{f} if it is a unify variable pointing to a lambda.
746
747 @code{G.L. (<apply> f a ... l)}, this is as with @code{apply}, but logic variables will be looked up.
748
749 @section printing information
750 @findex <pp>
751 @findex <pp-dyn>
752 @findex <format>
753 @findex tr
754 @findex *gp-var-tr*
755
756 @code{Scm (tr x)}, translate unbound variables with a prefix governed by @code{*gp-var-tr*} fluid.
757
758 @code{Scm (tr pre x)}, the same as above but using @code{pre} as the prefix.
759
760 @code{G.L. (<pp> x)}, this will pretty-print @code{x} and print it as a list-version of the code
761
762 @code{(<pp-dyn> redo-print undo-print)}, when the current unify stack backtracks across the current position in the stack it will do a @code{(<pp> undo-print)}, it redoes across this dynwind it will pretty-print e.g. @code{(<pp> Redo-print)}.
763
764 @code{G.L. (<format> port str arg ...)}, as with format, but under G.L.
765
766 @section evaluate scheme expressions
767 @findex <code>
768 @findex <tail-code>
769 @findex <when>
770 @findex if
771 @findex cond
772 @findex case
773 @findex <return>
774 @findex <ret>
775 @findex <dynwind>
776
777 @code{G.L. (<code> code ...)}, will execute @code{(begin code ...)} as scheme and then success.
778
779 @code{G.L. (<tail-code> (p cc) code ...)}, this will bind the failure thunk @code{p} and continuation @code{cc} inside @code{code ...} which is evaluated under Scm e.g. an implicit begin. It is the scheme code's responsibility to continue using @code{cc} or backtrack using @code{p}.
780
781 @code{G.L. (<when> S)}, the same as @code{(if S <cc>)}.
782
783 @verbatim
784 G.L. (if S X)
785 G.L. (if S X Y)
786 @end verbatim
787 @code{S} is an ordinary scheme expression and if true will execute @code{X} in G.L else @code{Y} in G.L. or fail if the scheme expression return @code{#f}.
788
789 Similarly there is (without @code{=>})
790 @verbatim
791 G.L. (when p c ...)
792 G.L. (cond (p a ...) ...)
793 G.L. (case a (p a ...) ...)
794 @end verbatim
795
796 @code{G.L. (<return> code ...)}, this will do a Scm: @code{(begin code ...)} and simply return that form in the guile log pass.
797
798 @code{G.L. (<ret> val)}, the same as @code{(<return> (u-scm val))}
799
800 @code{G.U. (<dynwind> redo-thunk undo-thunk)}, dynwind that when the unify stack is going in forward direction the redo-thunk is evaluated and else when we backtrack over this barrier the undo-thunk is evaluated.
801
802 @section go from scheme to guile-log
803 @findex <with-guile-log>
804 @findex <ask>
805 @findex <eval>
806 @findex <run>
807 @findex <clear>
808 @findex <stall>
809 @findex <continue>
810 @findex <take>
811 @findex <state-ref>
812 @findex <state-set!>
813
814 @code{Scm (<with-guile-log> (p cc) code ...)}, this will start a guile-log session using failure think p and continuation @code{cc} and use @code{p} as a cut as well.
815
816 @code{Scm (<with-guile-log> (cut p cc) code ...)}, this will start a guile-log session using failure thunk @code{p} and continuation @code{cc} and use @code{cut} as the cut failure thunk.
817
818 @code{Scm (<ask> P ...)}, will execute @code{(<and> P ...)} and if success return @code{#t} else if fail return @code{#f}
819
820 @code{Scm (<eval> (v1 ...) code fini cc)}, this will bind new variables @code{v1 ...} and execute code with failure thunk @code{fini} and continuation @code{cc} under G.L.
821
822 @code{Scm (<run> n (v ...) code ...)}, bind @code{v ...} with variables and execute the code and collect the list of list of bindings of @code{v} at success if @code{(v ...) = (w)} then it will return a list of values. @code{n} is the maximum numbers of success results and skipping @code{n} results in no limit on the number of successes.
823
824 @code{Scm (<clear>)}, cleares the stack back to start, use this when finished with @code{<take>,<run>} etc.
825
826 @code{G.L. (<stall>)}, this will stall a computation and allow it to continue at the users will and also be able to store the state.
827
828 @code{Scm (<continue>)}, this will make it possible to continue a stalled run, but if the run opted out after n successes then must ask for the number of more successes as well by using:
829
830 @code{Scm (<continue> n)}, with @code{n} the number of more successes to returnif we started with @code{(<run> n () ...)}.
831
832 @code{Scm <take>}, this is the same as @code{<continue>}.
833
834 @code{Scm (<state-ref>)}, this returns a value of the current state for which the system can restore later on.
835
836 @code{Scm (<state-set!> s)}, restores the state represented by the datadtructure @code{s} that was produced by @code{<state-ref>}.
837
838 @section Using logical variables in scheme mode.
839 When the guile-log system enters scheme mode one may for example need to use state information. But as entering scheme from guile-log the state is implicitly marked for the following macros to work without actually explicitly bound a state variable as may be done as well e.g.
840
841 @findex <scm>
842 @findex <cons>
843 @findex <car>
844 @findex <cdr>
845
846
847 @code{(<scm> x)}  returns essentially a scheme representation of @code{x} but where logical variables are included as themselves.
848
849 @code{<cons>, <car>, <cdr>}, used exactly as with corresponding scheme functions.
850
851 If by some reason one need to do the whole program using (almost) only the state
852 information, one can do so by setting the variable @code{*kanren-assq*} to 
853 @code{#t}. Doing this will mean that the program almost works as plain kanren.
854
855 @section Guile-log macro definitions
856 @findex define-guile-log 
857 @findex log-code-macro 
858 @findex define-and-log
859 @findex <define-guile-log-rule>
860 @findex parse<>
861
862 @code{(define-guile-log name . l)}, this works like define-syntax, but it will mark the symbol as a guile-log macro.
863
864 @code{(log-code-macro x)}, marks x as a log-code macro e.g. it will inline it's code into the continuation in an and sequence hence reduce the number of needed closures.
865
866 @code{Scm (parse<> (cut w fail cc) code)}, used to continue guile-log macro
867 expansion e.g. we could define @code{<and!!>} using
868 @verbatim
869   (define-guile-log <and!!>
870      (syntax-rules ()
871        ((_ meta arg ...)
872         (parse<> meta (<and> (<and!> arg) ...)))))
873 @end verbatim
874
875 That is a guile-log macro is an ordinary macro but in guile-log expansion it 
876 will add the first argument a meta to that macro that are then used in an ordinary expansion where we indicate a continue in guile-log mode by using @code{parse<>}.
877
878 @code{<define-guile-log-rule>}, this is a fast one-liner version of define-guile-log and throws one into the @code{G.L.} context of the producer without explisitly using @code{(cut s p cc)}.
879
880 @code{Scm (define-and-log name . l)}, used in and log context to get the next lines in the @code{<and>} into the macro. the match matching signature in the macro is 
881
882 @code{(f (cut s p cc) (f . l) e ...)}, for a function like signature and
883
884 @code{(f (cut s p cc) ()      e ...)}, for a symbol like signature.
885
886 An example using this is to for example have constructs that avoids nesting.
887 For example we can define @code{G.L. (<v> v ...))} through,
888
889 @verbatim
890 (define-and-log <v>
891   (syntax-rules ()
892     ((_ w (<v> v ...) e ...)
893      (<let> w (v ...) e ...))))
894 @end verbatim
895
896 And we would use it as
897
898 @verbatim
899 (<define> (f x)
900   (<v> y z)
901   (<=> x (y . z))
902   (g y z))
903 @end verbatim
904
905
906
907 @section Controling the kind of variable binding used, kannren assq, or a prolog stack.
908
909 @findex <logical++>
910 @findex <logical-->
911 @findex *kanren-assq*
912
913 @code{(<logical++>),(<logical-->)}, turn on/off the usage of assq logical variables. Works by introducing a 
914
915 To make the whole session in kanren assq mode one can set *kanren-assq* to #t.
916
917 Example:
918 @verbatim
919 (<run> 1 (x) (<=> x 1) (<pp> (pk S)))
920 ;;; ((<gp-stack> 5404676))
921
922 (<run> 1 (x) (<logical++>) (<=> x 1) (<pp> (pk S)))
923 ;;; ((<gp-stack> 5404676 (<#0 : 1> . 1)))
924
925 (<run> 1 (x) (<logical++>) (<var> (y) (<=> y 1) (<pp> (pk S))))
926 ;;; ((<gp-stack> 5404676 (<#0 : 1451764> . 1)))
927 @end verbatim
928
929 The format of the state is for the car to be the stack object and the cdr will 
930 represent the association list. Here we see how we associated 1 to the guile-variable @code{<#0 : 1>}. Also note in the last example how @code{<#0 : 1451764>} indicates that it has been allocated on the heap in @code{logical++} mode.
931
932 @section Returning multiple values.
933 @findex <values>
934 @code{(<and> (<values> (v ...) (f args ...)) ...)}
935 This is a way to define multiple values @code{v ...} as a return from @code{f}. For this to work we need to add @code{(<cc> x ...)} at the logical end of the definition of the functione.
936
937 Example:
938 @verbatim
939 (define-syntax s-pair!? 
940   (syntax-rules ()
941     ((_ x)   (gp-pair!? (s-lookup x)   S))
942     ((_ x S) (gp-pair!? (s-lookup x S) S))))
943
944 (define-syntax s-lookup 
945   (syntax-rules ()
946     ((_ x)   (gp-lookup x S))
947     ((_ x S) (gp-lookup x S))))
948
949 (define (<pair?> s p cc x)
950   (let ((ss (s-pair!? x s)))
951     (if ss
952         (cc ss p)
953         (p))))
954
955 (<define> (!car! x)
956   (<pair?> x)
957   (<cc> (<car> x)))
958
959 and use it as,
960
961 (<run> 1 (x y) (<=> x '(1 2)) (values (z) (!car! x)) (<=> y z))
962 => (((1 2) 1))
963 @end verbatim
964
965 @section Acumulators
966 @findex <fold> 
967 @findex <fold-step> 
968 @findex <fix-fold> 
969 @findex <fix-fold-step> 
970
971 These constructs will accumulate all possible values of a construct.
972
973 @code{G.L. (<fold> kons knil Lam X L)}, This will initiate an accumulator to @code{knil} and then use @code{kons} as the acumulating function. The guile log closure  @code{Lam} is executeded and @code{X} will represent the result that will be accumulated. The final result is then added to @code{L}.
974
975 @code{G.L. (<fold-step> kons knil Lam X L)}, the semantic is similar to @code{<fold>}, but the form will at each iteration succeeds with @code{L} bound to the current accumulator value.
976
977 Example:
978 @verbatim
979 (<define> (f x n m) (if (< n m) (<or> (<=> x n) (f x (+ n 1) m))))
980
981 (<run> * (l) (<var> (x) (<fold> + 0 (</.> (f x 0 10)) x l)))
982 => (45)
983
984 (<run> * (l) (<var> (x) (<fold-step> + 0 (</.> (f x 0 10)) x l)))
985 => (0 1 3 6 10 15 21 28 36 45)
986 @end verbatim
987
988 @code{G.L. (<fix-fold> kons knil Lam X Y L)}, 
989
990 @code{G.L. (<fix-fold-step-> kons knil Lam X Y L)}, 
991
992 this is as with @code{<fold>} etc, but the acumulation is done for each fixed @code{Y}.
993
994 Example:
995 @verbatim
996 (<define> (f x n m) 
997    (if (< n m) (<or> (<=> x n) (f x (+ n 1) m))))
998
999 (<run> * (l) 
1000   (<var> (x y) 
1001     (<fix-fold> cons '() 
1002          (</.> (f x 0 5) (f y 0 (<scm> x))) 
1003          x y l)))
1004 => ((4 3 2 1) (4 3 2) (4 3) (4))
1005
1006 (<run> * (l) 
1007    (<var> (x y) 
1008      (<fix-fold-step> cons '() 
1009         (</.> (f x 0 5) (f y 0 (<scm> x))) 
1010         x y l)))
1011 => ((1) (2 1) (3 2 1) (4 3 2 1) (2) (3 2) (4 3 2) (3) (4 3) (4))
1012 @end verbatim
1013
1014 @node acumulators/generators
1015 @chapter Acumulators/generators
1016 In the guile-log chapter we defined the basic framework to fold a sequence of solutions into a variable. With this we can support e.g prolog's bagof and similar constructs. In the module @code{(guile-log logic collects)}, we have defined a few specialisations of the fold operator in order to standardize these common abstractions. 
1017
1018 @section Acumulators API
1019 To explain the Api we have a @code{gl-thunk}, e.g. a guile-log lambda with zero arguments. @code{it}, will be the pattern to store. when it successes typically this variable will be copied and added to the resulting data structure which is @code{list, sum, ...}. There is a possibility to keep some elements fixed and this is the @code{-2} forms with the variable @code{fixed} naming the variable that needs to be fixated. e.g. first all solutions for the first found representation of the variable @code{fixed} will be found and added, then the then all solutions with the next found variant of the @code{fixed} will be used and so on, very much like how bagof in prolog is working. The @code{-step} versions of the acumulators will produce produce all the intermediate acumulator solutions.
1020
1021
1022 @findex <collect>
1023 @findex <collect-2>
1024 @findex <collect-step>
1025 @findex <collect-step-2>
1026 The following forms will cons all solutions to a list e.g. prodice lists in 
1027 reverse order.
1028
1029 @code{G.L. (<collect>        gl-thunk it list)}
1030
1031 @code{G.L. (<collect-2>      gl-thunk it fixed list)}
1032
1033 @code{G.L. (<collect-step>   gl-thunk it list)}
1034
1035 @code{G.L. (<collect-step-2> gl-thunk it fixed list)}
1036
1037 --------------------------------------------------------------------
1038
1039 @findex <sum>
1040 @findex <sum-2>
1041 @findex <sum-step>
1042 @findex <sum-step-2>
1043 The following forms will sum all solutions.
1044
1045 @code{G.L. (<collect>        gl-thunk it sum)}
1046
1047 @code{G.L. (<collect-2>      gl-thunk it fixed sum)}
1048
1049 @code{G.L. (<collect-step>   gl-thunk it sum)}
1050
1051 @code{G.L. (<collect-step-2> gl-thunk it fixed sum)}
1052
1053 -------------------------------------------------------------------
1054
1055 @findex <prod>
1056 @findex <prod-2>
1057 @findex <prod-step>
1058 @findex <prod-step-2>
1059 The following forms will take the product of all solutins
1060
1061 @code{G.L. (<collect>        gl-thunk it prod)}
1062
1063 @code{G.L. (<collect-2>      gl-thunk it fixed prod)}
1064
1065 @code{G.L. (<collect-step>   gl-thunk it prod)}
1066
1067 @code{G.L. (<collect-step-2> gl-thunk it fixed prod)}
1068
1069 --------------------------------------------------------------------
1070
1071 @findex <max>
1072 @findex <max-2>
1073 @findex <max-step>
1074 @findex <max-step-2>
1075 The following forms will take the max of all solutions.
1076
1077 @code{G.L. (<max>        gl-thunk it max)}
1078
1079 @code{G.L. (<max-2>      gl-thunk it fixed max)}
1080
1081 @code{G.L. (<max-step>   gl-thunk it max)}
1082
1083 @code{G.L. (<max-step-2> gl-thunk it fixed max)}
1084
1085 --------------------------------------------------------------------
1086
1087 @findex <min>
1088 @findex <min-2>
1089 @findex <min-step>
1090 @findex <min-step-2>
1091 The following forms will take the max of all solutions.
1092
1093 @code{G.L. (<min>        gl-thunk it min)}
1094
1095 @code{G.L. (<min-2>      gl-thunk it fixed min)}
1096
1097 @code{G.L. (<min-step>   gl-thunk it min)}
1098
1099 @code{G.L. (<min-step-2> gl-thunk it fixed min)}
1100
1101 --------------------------------------------------------------------
1102
1103 @findex <soland>
1104 @findex <soland-2>
1105 @findex <soland-step>
1106 @findex <soland-step-2>
1107 The following forms will take the and of all operations returning the last one
1108 as a solution.
1109
1110 @code{G.L. (<soland>        gl-thunk it and)}
1111
1112 @code{G.L. (<soland-2>      gl-thunk it fixed and)}
1113
1114 @code{G.L. (<soland-step>   gl-thunk it and)}
1115
1116 @code{G.L. (<soland-step-2> gl-thunk it fixed and)}
1117
1118 --------------------------------------------------------------------
1119
1120 @findex <solor>
1121 @findex <solor-2>
1122 @findex <solor-step>
1123 @findex <solor-step-2>
1124 The following forms will take the or of all operations returning the first solution.
1125
1126 @code{G.L. (<solor>        gl-thunk it or)}
1127
1128 @code{G.L. (<solor-2>      gl-thunk it fixed or)}
1129
1130 @code{G.L. (<solor-step>   gl-thunk it or)}
1131
1132 @code{G.L. (<solor-step-2> gl-thunk it fixed or)}
1133
1134 @section Local Non backtracking Genrators API
1135 This tool is found directly in the module @code{(logic guile-log)},
1136
1137 @code{G.L. (<with-generators> ((var init) ...) code ...)}, This will bound the variables @code{var ...} initiated to @code{init ...} inside @code{code ...}.
1138
1139 These variables can then be changed by using @code{set!} and if the updating is functional, the state of the variables will be managed and store and restore will be managed in such a way that jumping below the initiation with @code{<with-generators>} and back will produce the same values, but inside this form it will not be restored to the old value. Especially a simple generator can be applied by using,
1140
1141 @code{G.L. (<next-generator-value> sum var val)}, e.g. perform @code{var <- (sum var val)} each time this line is executed and no backtracking will be done.
1142 --------------------------------------------------------------------
1143
1144
1145
1146 @node postpone
1147 @chapter Postpone, a framework for postponing guile-log evaluations.
1148 This code is available from @code{(logic guile-log postpone)} You may have noticed that guile log is a framework to do tree searches to meet a certain criteria and during the path in the tree create data structures that are able to undo and also redo it's state. Most people when approaching this will sooner or later be bitten by the NP hardness of many interesting problems. The solution might then be to try intelligent guesses in which branch the gold is hiding. What one would like to do is try a set of branches, freeze the different states and at that point create some sort of index that represent the likelihood of the gold lying buried beneath. Then an overall global decision can be taken and only the most promising paths will be further examined. It is for this use case the following system is constructed. Postpone mix well with the rest of prolog, but especially the @code{<zip>}, forms might behave unexpectedly due to teh postpone mechansim interfering with the synch and produce bad result.
1149
1150 @section Api.
1151 @findex postpone
1152 @findex postpone-frame
1153
1154 @verbatim
1155 G.L. (postpone val power)
1156 G.L. (postpone-frame limit fact maxsize)
1157 @end verbatim
1158 To be able to postpone we must have a baseline from which we will base our restarts e.g. @code{postpone-frame}. The @code{postpone} command will basically evaluate @code{val} and postpone if it's larger then a certain limit that is governed by an initial value @code{limit} and @code{fact} - a factor that adds to the limit each postpone turn. The @code{power} is the sorting index used to manage a list of possible restarts for and this list is sorted so that we at restarts will try to use @code{maxsize} first elements of the list. The list is never larger then @code{10 * maxsize}.
1159
1160
1161 @node dynamics
1162 @chapter Dynamics
1163 The main work has been to enable delimeted continuation in guile-log. To do this is not easy because we want to support interleaving, postponing, store/restore, zip like construct as well as acumulation all in one theoretically and computationally sound environment. It's not just to store and restore a stack as in scheme. Guile log is targetted to be effective reinstating states and keep a huge number of states in memory, to do this we note 1. we store a tree of states to compress the overall memory need and keep consing to a lower degree. 2. reinstating state information multiple times is cheap because there is no consing the second time for the main stack (we keep another dynamic stack where we need to reinstate new datastructures at each reinstation. All this means that we must reinstate the same datastructure. Also generally the cc and p fields at the in and out of the generated continuation needs to be patched and in order to support all of guile-log seamlessly one need to make use of guarded variables. In all stackless dynamics like kanren employ is not well suited because this is a nonfunctional modification. The resulting continuation will work almost as one would expect, but one can imagine problematics if the evaluation of the continuation returns a failure thunk intended to jump back into the continuation without normal backtracking. This is not a serious flaw and we do not try to add functionality to support this more than that we would implement new versions of the frameworks, looking at that source code it would be clear how to proceed.
1164
1165 @section Api
1166 @findex <prompt>
1167 @findex <abort>
1168 @findex <catch>
1169
1170 @code{G.L. (<prompt> tag data thunk handler)}, This will evaluate the guile-log version of a thunk and continue just as with any other thunk. But if an abort with a tag that matches the prompt tag or if the prompt tag is true, any abort will be catched. data will be guile-log dynamic data that will be captured at the abort and transferd back to the prompts context. The handler is of the form
1171
1172 @code{(handler tag next kk args ...)}, @code{tag} is the abort tag, next is a guile-log thunk, that evaluated will try the next handler in the stack. kk is a meta continuation. typically to get the continuaiton @code{k}, you do 
1173
1174 @code{(let ((k (kk))) ...)}
1175
1176 But we can also do
1177
1178 @code{(let ((k (kk new-handler))) ...)}, in cases where one want to use a new 
1179 handler for the continuation which is a common pattern in producing generators.
1180 Technically this is not needed, but doing so means the difference between dog 
1181 slow code and performant code. Finally we can use,
1182
1183
1184 @code{(let ((k (kk tag new-handler))) ...)}, with the obvious interpretation. The return continuation k will have a few arguments that represents the arguments used in the continuation of the abort.
1185
1186 The arguments @code{(args ...)} are the arguments returned by the abort.
1187
1188
1189
1190 @code{G.L. (<catch> tag data thunk handler)} this is exactly the same interface
1191 as with prompts, but with the difference that the handler has the form
1192
1193 @code{(handler tag next args ...)}, This is the same as prompts, but does not have any continuation argument. This ideom has significantly lower overhead.
1194
1195 @code{G.L. (<abort> tag lambda args ...)}, will look for a handler matching 
1196 the tag and then call the handler with @code{(args ...)}, see the doc for @code{<prompt>}. The lambda should be a guile-log lambda and defines the signature that the continuation inside the handler have.
1197
1198 @section Example
1199
1200 @verbatim
1201 (use-modules (logic guile-log))
1202 (use-modules (logic guile-log umatch))
1203
1204 (<define> (f)
1205   (<values> (i x) (<abort> 'tag (<lambda> (i x) (<cc> i x))))  
1206   (<or-i>
1207    (<or> (<=> x i)      (<=> x ,(+ i i)))
1208    (<or> (<=> x ,(- i)) (<=> x ,(- (+ i i))))))
1209
1210
1211 (<define> (test x y)
1212   (<prompt> 'tag #f f
1213     (<lambda> (tag next kk)
1214         (<let> ((k (kk)))
1215            (<zip> (x (k 1  x))
1216                   (y (k 10 y)))))))
1217
1218 (<run> 10 (x y) (test x y))
1219
1220 --> $1 = ((1 10) (-1 -10) (2 20) (-2 -20))
1221 @end verbatim
1222
1223 @node dynamic-functions
1224 @chapter Dynamic functions
1225 An interesting category of functionality in prolog is their dynamic function framework. They are a generalization of databases and allow to do matching in a scalable manner through indexing. Guile log also support a full indexer for a simplified matcher. And for all matched clauses they will be executed in order acording to how the database is setuped. One can add clauses to the head or to the end, remove clauses according to a pattern and also store states for later rewinding. The state guarding mechanism is either cheap (weak) e.g. it will not remember states as long as the action is above in the stack, else if it backtracks below the stack, state will be stored and restored at reentrence. We also support strong state storage at e.g. postpone support. 
1226
1227 To use the api use @code{(use-modules (logic guile-log functional-database))}.
1228
1229 @section Api
1230 @findex define-dynamic
1231 @findex <push-dynamic>
1232 @findex <lambda-dyn>
1233 @findex <append-dynamic>
1234 @findex <remove-dynamic>
1235 @code{SCM (define-dynamic f)}, this will make a dynamic function object and bind it to @code{f}
1236
1237 @code{G.L. (<push-dynamic> f lambda-dyn)}, push a match onto the head of dynamic function @code{f}. @code{lambda-dyn} is a special lambda typically created through,
1238
1239 @code{SCM (<lambda-dyn> pat ... code)}, here @code{pat ...} will be simplified patterns only supporting @code{quote,unquote} all else directive is not allowed. @code{code} is evaluated in guile-log mode.
1240
1241 Similarly we can add code to the end of the dynamic function, e.g.
1242
1243 @code{G.L. (<append-dynamic> f lambda-dyn)}. 
1244
1245
1246 Also to remove elements one can use,
1247
1248 @code{G.L. (<remove-dynamic> (f a ...))}, where @code{f} is the dynamic function and @code{a ...} the patterns for the arguments that, which matches will be retracted.
1249
1250 @findex <with-dynamic-functions>
1251 @findex <guard-dynamic-functions>
1252 The previous set of API is typically what you get to use in prolog. The 
1253 downside is that they posses problem w.r.t. leaking data and therefor the next ideom is preferable to use in order to make sure both that one undo any changes to the dynamic variable, but also at reinstation of a state inside the form, it will resore to the same state as when control left the inner of the ideom e.g. The design is to favor fast lookup and adding and removing information is a bit expensive.
1254
1255 @code{G.L. (<with-dynamic-functions> (f ...) code ...)}, for this form @code{f ...}, will be weakly guarded throughout the form e.g. if control leaves the form  then the state is stored if needed and at reinstation of state inside @code{code ...}, the old state of the dynamic variable will be reinstated. But inside the form state of the dynamic functions is not saved or restored.
1256
1257 A stronger form of guard can be used in case one would like to make sure that the dynamic functions state can be reinstated in case of e.g. postpone is used, then use,
1258
1259 @code{G.L. (<guard-dynamic-functions> (f ...) code ...)},
1260
1261 Finally the last section conserns the ability to compile the dynamic function for as fast lookup as possible, use
1262
1263 @findex <dynamic-compile>
1264 @code{G.L. (<dynamic-compile> f ...)}, comiles the dynamic functions @code{f ...} for fast lookup. This ideom takes time and if used freely can cause a high memory consumption.
1265
1266
1267 @node parsing
1268 @chapter Parsing
1269 Prolog has historically been used for setting up parsers for various languages and has an extensible expression parser where one congigure the operator handling. We continue in this tradition to produce elements to do backtracking enabled parsing for guile. With this, one can explore the new interesting constructs in guile-log to enable new features with respect to parsing. 
1270
1271 Generally in guile-log a parser is a function that follows a certain call semantics. It is a guile log function e.g. it takes the standard arguments @code{S P CC}. But ontop of this it takes @code{X XL N M} e.g. current char on line (@code{X}), current line in stream of lines (@code{XL}), current line column (@code{N}) and current line number (@code{M}). Typically in code these elements are hidden in return values as calling signatures and hence the resulting code is less littered with standard ideoms and tons of variables. This design allows the programmer to easier spot errors and also produce fewer of them and we belive that it is a boon for productivity when writing parsers. Ontop of this semantics an extra output stream field in both imputt and output may be supplied e.g. the tool needed to produce a syntax tree. Code look typically like this,  when using this tool to produce a parser function
1272
1273 @verbatim
1274 (<p-lambda> (c)
1275   (.. (c) (ws c))                                    ;; Match whitespace
1276   (<let> ((n N) (m M))                               ;; store M and N
1277     (.. (c) (exponent c))                            ;; The actual number
1278     (.. (q) (ws c))                                  ;; Match whitespace
1279     (<p-cc> `(#:number ,(string->number c) ,n ,m)))) ;; Ret value
1280 @end verbatim
1281
1282 We see that we use @code{<p-lambda>} in stead of @code{<lambda>}. '@code{..}' is a special @code{<values>} form that has the effect to rebind @code{X,XL,N,M} to the new returned values. We also see the technique to bind e.g. @code{N,M} to different values. this code would look like this if we did use pure guile-log.
1283
1284 @verbatim
1285 (<lambda> (x xl n m c)
1286   (<values> (x xl nn mm c) (ws x xl n m c))
1287   (<values> (x xl n m c) (exponent x xl nn mm c))
1288   (<values> (x xl n m q) (ws x xl n m c))
1289   (<cc> x xl n m `(#:number ,(string->number c) ,nn ,mm))))
1290 @end verbatim
1291 Not nice on the eye's right. Anyway a bonus point is that we have a framework to create stream like translaters like parsing this through a little macrology and hence it is a 'notime' thingie to change the call idioms. This is the power of guile in action. Ontop of this we build parser combinators which is a functional kanren influenced way of combining parser functions. If we have parser functions @code{f,g} we would like to combine them into new parser functions, there are typical ideoms suitable for all translators of sequences e.g. combinators that can be employed e.g. @code{(f-and f g)} that successes if both does and outputs the last translation into the value stream. Se the combinators subsection to find out more.
1292
1293 The parsing lib is structured in subnodes according to,
1294 @menu
1295 * stream ideom::        How to create arbritrary streams in generality
1296 * parser combinators::  Constructing parser using higher order functions 
1297 * expressions::         Configurable Expression Parser
1298 @end menu
1299
1300 @node stream ideom
1301 @section Stream ideom api
1302 @findex define-guile-log-parser
1303 There is a little framework in guile-log imported with @code{(logic guile-log)} that enables the setup of syntactic sugar for streams. The api is
1304
1305 @code{SCM: (define-guile-log-parser-tool (lam (X ...)) def oo xx cc)}
1306
1307 @code{lam} will be the name of the new lambda object that can be used to produce a matcher. @code{X ...} will be the name of the syntax parameters and also define the standard positions for them in call and return. @code{def} is the corresponding define. To do an actual match in guile-log with parser function call one need to use @code{oo} and when one issues a whole new expression we use @code{xx}. To return values from the matcher we use @code{cc}. The use of @code{oo} is twofold. First
1308 @code{G.L (oo (v ...) (f a ..))}, does a call in nontail possition.
1309 @code{G.L (oo         (f a ..))}, does a call in tail position.
1310
1311 @code{xx} is used to capture the return of a subexpression like in the example below. It cannot be used to call parser funcitons.
1312
1313 @subsection Example
1314 The parsing framwork is using 
1315
1316 @verbatim
1317 (define-guile-log-parser-tool (<p-lambda> (X XL N M)) <p-define> .. xx <p-cc>)
1318 @end verbatim
1319
1320 An example to use @code{xx} is, 
1321 @verbatim
1322 (<p-define> (f c1)
1323   (xx (c2) (<or> (.. (g c1)) (.. (h c1))))
1324   (<p-cc> `(g-or-h ,c2)))
1325 @end verbatim
1326
1327 in practice one keeps the numbers of needed uses of all of the above framework by using functional combinators of matchers. But it is practical to just use this framework to e.g. define a c-parser.
1328
1329
1330 @node parser combinators
1331 @section Parser Combinators
1332 The combinators are basic elements that you get from the module @code{(logic guile-log parser)}. To note here is with these we define elements to do parsing in a ``functional'' way together with som utilities to memoize sections and produce tokens. Tokens are more interned scheme data then the standard way of matching that is lightweight and just represent sequences of the incoming chars. They are also cheap to backtrack over but will put a demand on the supply of prolog variables.
1333
1334 @subsection higher order elements
1335 @findex f-and
1336 @findex f-and!
1337 @findex f-and!!
1338 @code{(f-and f ...)}, higher order function, matches if all @code{f ...} matches and returns the values from the last one. Similarly @code{and!} only successes ones and for @code{and!!} all @code{f ...} only sucesses once.
1339
1340 @findex f-or
1341 @findex f-or!
1342 @code{(f-or f ...)}, higher order funciton, matches if at least one of @code{f ...} matches, similarly @code{f-or!} matches only once.
1343
1344 @findex f-seq
1345 @findex f-seq!
1346 @findex f-seq!!
1347 @code{(f-seq f ...)}, higher order function. Matches if @code{f ...} macthes in sequence. Similarly @code{f-seq!} only matches once and for @code{f-seq!!} each @code{f} only matches once.
1348
1349 @findex f-not
1350 @findex f-not!
1351 @findex f-not-pr
1352 @code{(f-not f)}, higher order function. matches one char if not @code{f} maches. Similarly @code{f-not!} stores and returns the matched character in the match standard way of storing data and @code{f-not-pr} prints the character on standard output.
1353
1354 @findex f*
1355 @code{(f* f)}, higher order function, matches @code{f} 0 or more times.
1356
1357 @findex f+
1358 @code{(f+ f)}, higher order function, matches @code{f} 1 or more times.
1359
1360 @findex fn
1361 @code{(fn f n m)}, matches @code{f} n to m times
1362
1363 @subsection Basic parser functions
1364 @findex f-tag
1365 @findex f-tag!
1366 @findex f-tag-pr
1367 @code{(f-tag str)}, produces a matcher of the tag @code{str}. @code{f-tag!} stores that match the standard way and @code{f-tag-pr} prints the match on standard output.
1368
1369 @findex f-reg
1370 @findex f-reg!
1371 @findex f-reg-pr
1372 @code{(f-reg char-regexp)}, produces a matcher that will macth one char according to @code{char-regexp}. Similarly we have @code{f-reg!} to store the standard way and @code{}
1373
1374 @findex f-true
1375 @findex f-false
1376 @code{f-true}, @code{f-false} macthers that represt a successful match and a failed match. These are mute constructs and does not consume any data.
1377
1378 @findex f-eof
1379 @findex f-nl
1380 @findex f-nl!
1381 @findex f-nl-pr
1382 @code{f-eof}, matches end of file.
1383 @code{f-nl}, do not use newlines with e.g. @code{f-reg}, it will not work use this in stead to match a newline. There is also @code{f-nl!} and @code{f-nl-pr} versions.
1384
1385 @findex tok-ws*
1386 @findex tok-ws+
1387 @code{tok-ws*, tok-ws+}, this is an non token generator token e.g. it returns the input state of the out stream. But it does tokenizing by issuing a freeze so it memoizes and will not reparse whitespace. the * version is for 0 or more whitespaces and + for one or more whitespaces. A whitespace is here defined as 'space' 'tab' and 'newline'.
1388
1389
1390
1391 @subsection utilities
1392 @findex p-freeze
1393 @code{(p-freeze tok f mk)} This will freeze the interpretation of the comming characters according to the parser function @code{f} as token @code{tok}. Using backtracking, one can get into the unfourtunate stage of reparsing things over and over again. WIth p-freeze we will memoize the reseult and the second time we try to parse the token at the same position we will just use the memoized data. this is how we tokenize and gives the guile-log parsing system a slower tokenizer on one hand, then traditional tokenizers, but on the other hand allows far more advanced tokens to be builed e.g. tokenize a parenthesied expression in C. @code{mk} is a function whos purpose is to construct that value that should be memoized it has the signature
1394
1395 @code{(mk s in-value out-value)}, where @code{s} is state value neede to tarnslate any prolog variables, @code{in-value} is the value that get's into the resulting parser function, and @code{out-value} is the value out of the parser function @code{f} above. typical uses are @code{(define (mk s cin cout) cout)}.
1396
1397 @findex mk-token
1398 @code{(mk-token f)}, this is the lower level tokenizer that just produces a string token out of the all the matched characters by the parser function @code{f}.
1399
1400 @findex Ds
1401 @code{(Ds f)}, will delay the evaluation of the parser matcher @code{f}. This function is needed in recursive definitions in order to avoid infinite recursion.
1402
1403 @findex parse
1404 @code{(parse f)}
1405 @code{(parse string f)}
1406 The first version will read from standard input and produce an output as 
1407 returned by the parser function @code{f}. We may also in the second version use a string as input to the parser as per convinience.
1408
1409 @node expressions
1410 @section Expressions
1411 This is a configureable expression parser that can be used for prolog parsing as well as parsing C and C++ expressions. To note is that the data is functionally updated and hence one can store the state at will and later reinstate the parser. The parser ideom is a direct translation of the commonly described prolog parser written in prolog to guile-log. It is then extended to allow ternial operators like @code{?} in c as well. To use it load the module @code{(logic guile-log parsing operator-parser)}
1412
1413 @subsection Api
1414 @findex make-opdata
1415 @code{(make-opdata)}, initiates a datastructure to containe needed operator data. The result is a fluid pointing to a functional datastructure.
1416
1417 @findex add-operator
1418 @code{(add-operator data type name level lf)}, This will add operator data to the opdata fluid @code{data}. @code{type} is the type of operator e.g. any of @code{xf,yf,fx,fy,xfx,xfy,yfx}, as of the standard meaning of these operators in prolog. @code{name} is a string or symbol representing the name of the operator and @code{level} is the anti binding strength of the operator e.g. higher value bind less. @code{lf} is a parser function that represents possible values to the right of the op-symbol matched, typically this will be @code{tok-ws}, but also for e.g. @code{?} it can be a parser function matching the middle part of in this operayor which ends with @code{:}.
1419
1420 @findex rem-operator
1421 @code{(rem-operator data type name)}, removes from the opdata fluid @code{data}, the slot represented by the type @code{type} and the operator name @code{name}.
1422
1423 @findex mk-operator-expression
1424 @code{(mk-operator-expression atom rest-atom data)}, will return a parser meta function representing the operator configuration in @code{data}, with atom parser function @code{atom} and a secondary choised atom if that fails in @code{rest-atom}. The returned meta parser function, say @code{ff} is typically turned into a parser function for the expression through:
1425
1426 @code{(ff high-level)}, with @code{high-level}, the highes level found in the table.
1427
1428 The generator parser @code{f} can then be used to match an expression and outpits a syntactic tree with nodes according to e.g.
1429 @verbatim
1430 (parse ``1 + -2'' f)
1431
1432 -->
1433
1434 (('xfy ``+'' _ _) (#:number 1) (('yf ``-'' _ _) (#:number 2) 4 0) 2 0)
1435 @end verbatim
1436
1437 That is a binary oparator is of the form,
1438
1439 @code{((type operator-name level _) term-left term-right column line)}
1440
1441 And a unary operator is matched by
1442
1443 @code{((type operator-name level _) term column line)}.
1444
1445 @node sed/grep
1446 @chapter Sed/grep overview
1447 To overengineer and test out the framework a simple grep and sed utility has been designed. It knows about scheme and can locate and translate scheme files as well as having traditional grep/sed funcitonality. The main interface is in the module @code{(logic guile-log grep)}.
1448
1449 @section Api
1450 @code{(grep match code #:key (a 0) (b 0) (c 0))}, this will evaluate @code{code} in a separate thread and capture standard output and only print what the parser function @code{match} matches. @code{a,b,c} defines an interval @code{[min(-b,-c),max(a,c)]} around the matched line which is printed.
1451
1452 @code{(sed match code)}, will print everything but if match matches, it's output will be printed instead by the matcher, e.g. use the pr versions of the parser combinators for printing matches.
1453
1454 @code{(par-grep match code #:key (str q-false) (com q-false) (a 0) (b 0) (c 0))}, This is a grep funciton that knows about scheme, it works as before but will print the sexp or part of sexp that is matching. The extra fields are, @code{str}, the matcher used inside strings, @code{com}, the matcher used in comments, and @code{d} prints the lines containing the @code{d} level enclosing sexp.
1455
1456 @code{(par-sed match code #:key (str q-false) (com q-false))}, This is a sed utility that knows about scheme.
1457
1458 @section The scheme matcher.
1459 In order to translate scheme code we have a nice little monster framework to to the grunt work. You may use it by importing (logic guile-log parsing sch-match).
1460 To use this one need to know about how syntax-parse works. We only support a subset of the syntax-parse interface, namlely the directives @code{~and ~or ~not ~var _)} added to this we make use of ice-9 match notation for symbols.
1461
1462 To define a match abstraction use,
1463
1464 @code{(define-match-class [nm | (nm . args)] (pattern pat l ...) ...)},
1465 just use this as with define-syntax-class, but with the exception that you will build and match according to some whitespace rules stated below. 
1466
1467 @code{(define-splicing-match-class [nm | (nm . args)] (pattern pat l ...) ...)},
1468 This works just as with @code{define-splicing-syntax-class} in syntax-parse, but again with some extra twarts.
1469
1470 The actual matchers are,
1471
1472 @code{(scm-sed (pat res ...) ...)}, this works just as with syntax-parse, but with the extra build-rules.
1473
1474 @code{(scm-match pat)}, use this as a matcher in par-grep, but with the syntax-parse pattern interface to define a match.
1475
1476 @section Building the result.
1477 The philosophy is to treat the sed translation as a special syntax transform. A variable @code{x} in the pattern will produce three sub matches, @code{x.l,x.it.x.r}. e.g. left whitespace, sexp, right whitespace. By matching @code{#(l it r)} l will be left whitespace, it the sexp and r the right whitespace, and this is how you define the output as well in order to surround an element with whitespace.
1478
1479 @section Example
1480 This is an example how one may define a sed translator that swaps the meaning of variable and value in a let form and preserving whitespace as much as possible.
1481
1482 @verbatim
1483 (define-match-class swap
1484   (pattern #(l (x y) r) 
1485      #:with tr #'#(l (x.l y.it x.r y.l x.it y.r) r)))
1486
1487 (define-match-class (tr-it oldval newval)
1488   (pattern #(l ,oldval r)
1489      #:with tr #`#(l #,(datum->syntax #'a newval) r)))
1490
1491 (define (test f)
1492   (par-sed (scm-sed (#(l ((~var let (tr-it 'let 'tel))
1493                               #(a ((~var bind swap) ...) b)
1494                          body ...) r)
1495                      #'#(l (let.tr #(a (bind.tr ...) b) body ...) r)))
1496       (f)))
1497 @end verbatim
1498
1499 @node kanren
1500 @chapter Kanren
1501 Almost all of the kanren interface is implemented ontop of guile-log to use it import @code{logic guile-log kanren}. One could say that the kanren interface is the functional sister to guile-log which is more a macro framework as such guile-log is about 2x faster the kanren, but kanren has more beutifull semantics. 
1502 E.g. the kanren operation maps function arguments to functions. The kanren interface is divided into two categories of functionals, facts and relations. One combine facts into relations. The main difference is that fact functions have standardized arguments and relations have customized arguments. Also conversely evaluating the relation will return back a fact.
1503
1504
1505 @section The fact building blocks
1506 @findex succeed 
1507 @findex fail 
1508 @findex sfail 
1509 @findex all 
1510 @findex all! 
1511 @findex all!! 
1512 @findex all-interleave
1513 @findex any 
1514 @findex any-interleave 
1515 @findex any-union
1516 @findex if-only 
1517 @findex if-some 
1518 @findex fails 
1519 @findex succeeds 
1520 @findex ==
1521 @findex let-lv
1522 @findex project
1523 @findex project/no-check
1524 @findex predicate 
1525 @findex *equal? 
1526 @findex var? 
1527 @findex reify 
1528 @findex _
1529
1530 @code{succed}, This functional item repressents a term that always succeeds.
1531
1532 @code{fail,sfail}, Both of these will always fail.
1533
1534 @code{(all f ...)}, @code{all} will produce a functional item representing success if all @code{f ...} will success.
1535
1536 @code{(all! f ...)}, @code{all!} will produce only one success where all @code{f ...} successes.
1537
1538 @code{(all!! f ...)}, @code{all!!} sucesses where all @code{f ...} successes only one time.
1539
1540 @code{(all-interleave f ...)}, As with @code{all}, this construct sucesses if all of the parts sucesses, but the backtracking is designed so that it backtracks evenly and hence avoids problems due to some of the constructs can backtrack an infinite amount of times berfore the success is found. To note is also that this construct has exponential memory complexity with the depth of the search.
1541
1542 @code{(any f ...)}, this will success if any of @code{f ...} sucesses.
1543
1544 @code{(any-interleave f ...)}, as @code{any}, but one at a time will be tried cyclically and hence will find a solution in finite time if there exists one, else it could risk getting stuck in an infinite bacltracking sequence.
1545
1546 @code{(any-union f ...)} This is similar to @code{any-interleave}, but it will 
1547 skipp multiples of similar sucesses e.g. if @code{(all f1 f2)} is a success, it will skipp the f1 and continue trying with the @code{f2} which will success. Esentially this capture the case when all @code{f ...} bind the same variable to a value and we do not backtrack to the same value multiple times.
1548
1549 @code{(if-only pred x), (if-only pred x y)}, The first form is equivalent to @code{(all (all! pred) x)}. For the second form if @code{pred} successes then the form will fail if @code{x} fails. If @code{pred} first fails, then @code{y} is executed.
1550
1551 @code{(if-some p x), (if-some p x y)}, The first form is equivalent to @code{(all p x)} and in the second form @code{y} is executed if @code{p} fails.
1552
1553 @code{(succeeds f ...)}, is similar to @code{(all f ...)} but if this success it will backtrack and undo any bindings and continue.
1554
1555 @code{(fails f ...)}, if @code{(all f ...)} fails then this form will backtrack and undo any bindings and continue with a success.
1556
1557 @code{(== a b)}, unifies the terms.
1558
1559 @code{(*equal? a b)}, this will try to unify without any variable binding.
1560
1561 @code{(let-lv (id ...) code)}, this will bind @code{id ...} to new fresh variables inside @code{code}.
1562
1563 @code{(project (var ...) gl)}, This will take a specification of a functional item represeting a fact, gl and use the lookuped values of @code{var ...} inside the @code{gl} spec. This logic is captured in a new functinal fact. If the lookup results in a variable an error will be produced.
1564
1565 @code{(project/no-check (var ...) gl)}, As with project, but there is no error reported if the lookup results in a variable.
1566
1567 @code{(predicate scheme-expr code)}, Succeeds if @code{scheme-expr} is true.
1568
1569 @code{(var? x)}, true if x is a logical variable.
1570
1571 @code{(reify x)}, will produce a scheme representation of @code{x}.
1572
1573 @code{_}, produces a fress new logical variable in it's place.
1574
1575 @section relations
1576 @findex relation 
1577 @findex fact 
1578 @findex extend-relation 
1579 @findex extend-relation-with-recur-limit
1580 @findex lift-to-relations
1581 @findex intersect-relation
1582 @findex let-gls
1583
1584 This is documentation derived from the kanren sources.
1585         
1586 @code{(relation (VAR ...) (to-show TERM ...) [GL]}, Defines a relation of arity @code{(length '(TERM ...))} with an optional body @code{GL. VAR ...} are logical variables that are local to the relation, i.e., appear in @code{TERM ...} or @code{GL}. It's better to list as @code{VAR ...} only logical variables that appear in @code{TERM ...}. Variables that appear only in @code{GL} should be introduced with exists. That makes their existential quantification clearer. Variables that appear in @code{TERM ...} are universally quantified.
1587
1588 @code{(relation (head-let TERM ...) [GL])}
1589 A simpler, and more efficient kind of relation. The simplicity comes from a simpler pattern at the head of the relation. The pattern must be linear and shallow with respect to introduced variables.  The gl is optional (although omitting it doesn't make much sense in practice) There are two kinds of head-terms.  One kind is an identifier. This identifier is taken to be a logical identifier, to be unified with the corresponding actual argument.  Each logical identifier must occur exactly once.  Another kind of a head-terms is anything else. That anything else may be a constant, a scheme variable, or a complex term that may even include logical variables such as @code{_} -- but not logical variables defined in the same head-let pattern.  To make the task of distinguishing logical identifiers
1590 from anything else easier, we require that anything else of a sort of a manifest constant be explicitly quoted or quasiquoted. It would be OK to add `, to each 'anything else' term.
1591
1592 Examples:
1593
1594 @code{(relation-head-let (x y z) (foo x y z))}
1595 Here @code{x} @code{y} and @code{z} are logical variables.
1596
1597 @code{(relation-head-let (x y '7) (foo x y))}
1598 Here we used a manifest constant that must be quoted
1599
1600 @code{(relation-head-let (x y `(1 2 . ,_)) (foo x y))}
1601 We used a quasi-quoted constant with an anonymous variable.
1602
1603 @code{relation (ANNOT-VAR ...) (to-show TERM ...) [GL]}
1604 where @code{ANNOT-VAR} is either a simple @code{VAR} or @code{(once VAR)} where 'once' is a distingushed symbol. The latter form introduces a once-var, aka linear variable. A linear variable appears only once in @code{TERM ...} and only at the top level (that is, one and only one @code{TERM} in the to-show pattern contains @code{ONCE-VAR}, and that term is @code{ONCE-VAR} itself). In addition, @code{ONCE-VAR} must appear at most once in the body @code{GL}. (Of course, then @code{ONCE-VAR} could be _, instead.) If these conditions are satisfied, we can replace a logical variable @code{ONCE-VAR} with a regular Scheme variable.
1605
1606 @code{(fact (VAR ...) TERM ...)}, this is syntactic sugar for @code{(relation (VAR ...) (to-show TERM ...) succeed)}.
1607
1608 @code{(extend-relation (id ...) rel ...)}, this relation will simply try each 
1609 sub relation @code{rel} one at a time acording to @code{any} calling them with arguments (id ...) which is the arguments of the resulting relation.
1610
1611 Example:
1612
1613 @verbatim
1614 (extend-relation (a1 a2)
1615    (fact () 'sam 'rob)
1616    (fact () 'roz 'sue)
1617    (fact () 'rob 'sal))
1618 @end verbatim
1619
1620 Here @code{a1} and @code{a2} will be tried with one fact after the other until a match is found. At backtracking this process will continue untill another match is found.
1621
1622 @code{(extend-relation-with-recur-limit limit (id ...) rel ...)}, this is the same as the previous term, but the resulting relation cannot be called recursively more then @code{limit} times.
1623
1624 @code{(lift-to-relations (id ...) (g rel ...))}, This will generate a 
1625 combination of the relation @code{rel ...} according to @code{g} and with the argument 
1626 variables @code{id ...}. E.g.
1627
1628 Example:
1629
1630 @verbatim
1631 (lift-to-relations (a1 b1) 
1632   (any  (fact () 'sam 'rob)
1633         (fact () 'roz 'sue)
1634         (fact () 'rob 'sal)))
1635 @end verbatim
1636
1637 Is equivalent to the previous example in the section for @code{extend-relation}.
1638
1639 @code{(intersect-relation (id ...) rel ...)}, This is the same as extend-relation, but it will use @code{all} in stead of @code{any}.
1640
1641
1642
1643 @code{(let-gls (id ...) ((name rel) ...) code)}, this will create a new realation with arguments @code{id ...} and in that create a set af relations names @code{name ...} representing @code{rel ...} and the names are used in @code{code}.
1644
1645
1646 @section Queries
1647
1648 @findex query 
1649 @findex solve 
1650 @findex solution 
1651
1652 @code{query (redo-k subst id ...) A SE ...) -> result or '()}, The low level macro 'query' runs the goal @code{A} in the empty initial substitution, and reifies the resulting answer: the substitution and the redo-continuation bound to fresh variables with the names supplied by the user e.g. @code{redo-k} and @code{subst}. The substitution and the redo continuation can then be used by Scheme expressions @code{SE ...} Before running the goal, the macro creates logical variables @code{id ...} for use in @code{A} and @code{SE ...} If the goal fails, '() is returned and @code{SE ...} are not evaluated. Note the similarity with shift/reset-based programming where the immediate return signifies "failure" and the invocation of the continuation a "success" Returning '() on failure makes it easy to create the list of answers.
1653
1654 @code{(solve n (v ...) g ...)}, This will create fresh new variables @code{v ...} and solve @code{(all g ...)}. It will output a list of solution which depends on the value of @code{n}. If this is equal to @code{*} then all solutions will be included. Else if n is a number at must that number of solutions will be publishied in the list.
1655
1656 @code{(solution (v ...) g ...}, This is the same as @code{(solve 1 (v ...) g ...)}.
1657
1658 @section Misc                             
1659 @findex trace-vars
1660 @findex partially-eval-sgl
1661
1662 @code{(trace-vars title (var ...))}, Will print out a trace expression for @code{var ...}.
1663
1664 @code{partially-eval-sgl}, not implemented, because guile-log is also directed towards stacks and assq lists and hence usually uses another kind of implementation for the interleaving constructs.
1665
1666 @section Examples
1667 @verbatim
1668 Example 1, any-union,
1669 (let* ((fact1 (fact () 'x1 'y1))
1670        (fact2 (fact () 'x2 'y2)) 
1671        (fact3 (fact () 'x3 'y3))    
1672        (fact4 (fact () 'x4 'y4))
1673
1674        ; R1 and R2 are overlapping
1675        (R1 (extend-relation (a1 a2) fact1 fact2))
1676        (R2 (extend-relation (a1 a2) fact1 fact3))
1677        ; R1 will first try fact1 then fact2
1678        ; R2 will first try fact1 then fact3, hence overlapping
1679        )
1680     
1681     (solve 10 (x y)
1682            (any-union (R1 x y) (R2 x y))))
1683 =>    '((x1 y1) (x2 y2) (x3 y3)))
1684
1685 Note how R1 and R2 first both bind x and y to the same values in their first 
1686 match and how any-union avoid duplicate the results. This works independent of 
1687 the orders of fact1 and fact2 etc in the definitions of R1 and R2.
1688 @end verbatim
1689
1690 @node prolog
1691 @chapter Prolog
1692 Guile log sports also a iso-prolog interface as a logic programming interface besides kanren. The interface is pretty complete at this point appart a few points that have not yet been resolved but shure it is alpha software. With this most programs written in iso prolog should work. The intention is to enhance this interface so that the bulk of already written prolog programs should be able to be run on guile. We will also add the fetures unique to guile-log and hence enhance the prolog experience. Featurewise guile-log prolog is taking over many properties of scheme like closures, continuations, delimeted continuations, the interleaving constructs of kanren and a delicate system to treat dynamic objects like dynamic functions, dynamic hashes and a well thought out library to tell how you want the dynamism to work at a very fine grained level.
1693
1694 @menu
1695 * running::           How to hook in prolog code
1696 * deviations::        What is different and not according to standard and why.
1697 * modules::           How to handle name spacing
1698 * scheme::            Hooking in scheme expressions
1699 * closures::          Using closures in prolog
1700 * prolog-dynamic-functions:: A discussion of guile log's version of this
1701 * dynamic-features::  Special construct to manage dynamic objects
1702 * prolog-libraries::  Libraries that exposes guile-log features
1703 * internals::         A short discussion of the prolog internals used.
1704 @end menu
1705
1706 @node running
1707 @section Seting up and running prolog programs
1708 At this point we do not support an interactive shell for prolog. A task on the todo list, but you can run macros that takes a string and outputs a compiled guile log snippet and by this e.g. define logic functions using prolog. It is also possible to refere to a file and by that load a prolog file's contents into a scheme file. There is also tools to reset the prolog parser in case it changes it's state by e.g. defining operators or character translations. The typical usecase is to provide a small module wrapper, reset the parser and then add the prolog file.
1709
1710 @subsection Api
1711 @findex compile-prolog-string
1712 @findex compile-prolog-file
1713
1714 The iso-prolog library is resolved by,
1715
1716 @code{(use-modules (logic guile-log iso-prolog))}
1717
1718 First the compiler macros,
1719
1720 @code{(compile-prolog-string string)}, this will compile a prolog program in @code{string} and output a guile-log program at macro expansion time.
1721
1722 @code{(compile-prolog-file filename)}, this will replace the form with a macroexpanded scheme verision of the a prolog program referenced by filename.
1723
1724
1725
1726 Then to reset the parser and prolog flags use,
1727
1728 @findex reset-operator-map
1729 @findex reset-char-conversion
1730 @findex reset-flags
1731 @findex reset-prolog
1732 @code{(reset-operator-map)}
1733
1734 @code{(reset-char-conversion)}
1735
1736 @code{(reset-flags)}
1737
1738 @code{(rest-prolog)}, will do all of the above rest functions.
1739
1740 To run a prolog program one need to use a special program that essentially will
1741 setup an suitable error handler for prolog and issue a guile-log @code{<run>} command e.g.,
1742
1743 @code{(prolog-run n (v ...) code ...)}, here  @code{n} is the maximum number of 
1744 solutions to search for, or @code{*} to search for all solutions.  @code{v ...} is a set of logical variables used and for which solution are collected, @code{code ...} is a guile-log command, but to make it simple just call a startup prolog function with it.
1745
1746 @subsection Example
1747
1748 @verbatim
1749   (use-modules (logic guile-log iso-prolog))
1750   (reset-prolog)
1751   (compile-prolog-string "f(X,Y) :- (X=1,Y=2;Y=3);X=Y.")
1752   (prolog-run * (X Y) (f X Y))
1753 $1 = ((1 2) (v0 3) (v0 v0))
1754 @end verbatim
1755
1756 @node deviations
1757 @section Known deviations from iso prolog specification.
1758 The known deviations are
1759
1760 @subsection function/arity 
1761 In prolog the module + function/arity combination identifies the actual predicate. Scheme does not have such a distinction and in order to keep a tight interface between scheme functions and prolog functions a function is identified with its module + name only. This can create problems for certain prolog programs.
1762
1763 @subsection 'nm' is not nessesary atoms.
1764 The logic is currently,
1765
1766 @code{'nm'(x,...)}, here @code{nm} is translated to an atom.
1767
1768 @code{f(...,'nm',....)}, here @code{nm} is translated to a scheme string. and likewise for list arguments. There is a distinction here because characters in prolog is also atoms and then the namespacing mechanism currently used, makes prolog code a headache to use if we translated everything to atoms directly (an 'a' in one module would not be an 'a' in another module). In stead it is possible to call with a string in which case the current module is used for lookup. And unification of a string 'a' and a atom a is always true whatever the module is involved. (two atoms does not translate well). This is again a tweak to support modules sanely and it is expected to always work. To note, it is possible to namespace a @code{'nm'}  item by forcing a namespace on it. The story is a bit complex, the main thing to remember is to explicitly sigil a @code{'nm'} with the namespace operator if one want and atom and in case one suspect a string is gotten as an argument, it is possible to make an operator through a unification with a namespaced variable.
1769
1770 @subsection closed files
1771 Closed files cannot be gotten through a general seek of streams.
1772
1773 @subsection seek
1774 seek in binary files is not supported (yet).
1775
1776 @subsection modules
1777 there is some effort to standardize modules, we do not explicitly add module functionality to prolog, users are advised to write scheme wrappers or inlined scheme code in the prolog file/string.
1778
1779
1780 @node modules
1781 @section Module system and prolog
1782 We support @code{@@} and @code{@@@@} operators to resolve atoms module meaning. The syntax is @code{name@@module} which names files in a special module directory in the guile namespace @code{(language prolog modules)}. @code{@@} is refering to symbols in the public interface and @code{@@@@} refers to symbols in the whole private module namespace. We also support a guile-log reference through e.g. @code{name@@(logic,guile-log,iso-prolog)}. atoms can either be namespaced in or are strings, that will be namespaces as soon it touches a construct with a namespace in, e.g. @code{X@@module = Y} will make sure that if @code{X} gets bounded, it will if @code{Y} is a string, try to produced a namespaced item. Managing modules will either be done by the scheme wrapper or by inlined scheme expression.
1783
1784 @subsection Example
1785 @verbatim
1786 :- scm[(use-modules (logic guile-log guile-prolog zip)]
1787 :- scm[(export a b c)]
1788 :- scm[(re-export e f g)]
1789 @end verbatim
1790
1791 @node scheme
1792 @section hooking in scheme expressions,
1793 We can insert scheme expressions with the construct @code{scm[sexp]}. You can insert it like 
1794
1795 1) directives
1796 @code{:- scm[(export a b c)]}
1797
1798
1799 2) function arguments and list arguments
1800 @code{f(X) :- g(X, scm[(dub (<scm> X))], scm[*global-variable*])}
1801
1802 3) In expression constructs
1803 @code{f(X) :- X is scm[(dub X)]}.
1804
1805
1806 @node closures
1807 @section closures in prolog
1808 Closures is an interesting construct and we support three variants of them.
1809
1810 1) Full blown @code{letrec} environment,
1811 @verbatim
1812 f(X,Y,L) :- h(X,Y,Z), 
1813             k(lambda{ flam(X,Y) :- X = [v[Y],Y]. 
1814                       lambda(U) :- flam(v[Z],U).}).
1815 @end verbatim
1816 E.g. the ideom are
1817 @code{name@{just usual prolog definitions here@}} with @code{name} naming
1818 the function which will be the lambda handle.
1819
1820 2) simple one line lambdas
1821 @code{name@{X,Y | code ...@}}
1822
1823 and 3)
1824 @code{name@{@{code ...@}@}}, e.g. a closure with no arguments.
1825
1826 The @code{name} will be used in printed representations, refering not to the closure object but the closure code. Therefore it must be unique to the module or it will clobber or be clobbed.
1827
1828 To be able to refere to a variable in the outer context onen need to enclose it with @code{v[Var]}. Then it will match a variable named @code{Var} that has normally been lexically bound in a prolog program. You may refer to global scheme variables as well by @code{scm[...]}.
1829
1830 Closures will be transparent e.g. two closures unifies when all the closure
1831 variables unifies and the code is equvalent. Also the system works with 
1832 @code{copy_term}, can be put into @code{asserta} and @code{read-term}'ed and 
1833 @code{write-term}'ed. All should work smoothly.
1834
1835 @node prolog-dynamic-functions
1836 @section Explaing the guile-log dynamic functions
1837 Dynamic functions in guile-log prolog follows the iso prolog interface. But they are more powerful. They belong to a class of object that we can call dynamic objects for which dynamic features can be added how to backtrack store and restore state. The driving feature is that the state infromation is updated in a funcitonal manner and that its encapsulated with a thread safe handle. But the datastructure are not only functional, in order to have decent properties in prolog program and let them for example back track with the logic program we allow a mark and reset feature. To understand this scope please read about dynamic features. The dynamic functions are optimized for fast lookup and guile log prolog is fully indexed and can yield the matching items faster than it takes to actually perform any common match consequent. The target is for systems that update seldom and do lookup often. The dynamic functions @code{assert*} compainion will compile the program to bytecode/native for faster execution. Do not use dynamic functions as a hash table that updates often, for that use the hash table library. Also currently at most 10000 elements can be stored for a dynamic function. (The algorithm scales badly after that and we do not support larger than that).
1838
1839 @node dynamic-features
1840 @section Dynamic features
1841 A dynamic feature is a feature that can be added to the update flow of a dynamic variable, you may want it's state to be saved and restored when a continuation is stored and later executed. You may want the state to be started and restored in a more fine grained pattern when you do paralell. You may want the state to be restored when controls leaves a function either by sucessing or by back tracking and so on. Guile log sports the feature to allow all stateful data such as dynamic functions dynamic vlists, vhashes, operator tables, character translations, flags, and any functional datastructure you can think of that you define in guile scheme and exposed to prolog. 
1842
1843 @subsection API.
1844 There is a section about the scheme part of this interface, here we concentrate on the prolog part. The dynamin objects constructures will be defined in their associated library section, here we just describes what we can impose on them 
1845
1846 @subsubsection handles
1847 Use the below accessors to get a handle of various prolog aspects like operator table char conversion table and prolog flags table for defining dynamic features on them.
1848
1849 @code{get_prolog_operators_handle(Handle)}
1850
1851 @code{get_prolog_flags_handle(Handle)}
1852
1853 @code{get_prolog_conversion_handle(Handle)}
1854
1855 @subsubsection backtracking versions
1856
1857 @code{backtrack_dynamic_object(o, ...)} Make sure that after this position and forward in the execution @code{o,...} will follow any backtracking and also backtrack to the value that they had at the junction unless a new dynamic feature is encountered.
1858
1859 @code{not_backtrack_dynamic_object(o, ...)} Make sure that after this position and forward in the execution @code{o,...} will not follow a backtracking unless a new dynamic feature is encountered.
1860
1861 @code{with_backtrack_dynamic_object(o, ...,code)} Make sure that inside @code{code} the execution @code{o,...} will follow any backtracking unless a new dynamic feature is encountered
1862
1863 @code{with_not_backtrack_dynamic_object(o, ...,code)} Make sure that inside @code{code} the execution @code{o,...} will not follow any backtracking unless a new dynamic feature is encountered
1864
1865 @subsubsection guarding states
1866
1867 @code{state_guard_dynamic_object(o, ...)}, A left limit for which state is restored if the state reinstated over the guard, unless other guards are encountered after this guard.
1868
1869 @code{state_guard_dynamic_object_zip(o, ...)}, A left limit for which state is restored if the state reinstated over the guard, unless other guards are encountered after this guard. The difference to the above is that this can be placed before a control construct that do parallell execution like interleaving disjunciton or zipping of goals. Hence we do not need to place it in each branch essentially meaning that when each branch is reinstated the dynamic objects value is reinstated for that branch else the control would not pass over the guard and no reinstation would result.
1870
1871 @code{always_state_guard_dynamic_object(o, ...)}, A left limit for which state is restored always independentof if the state reinstates over the guard, unless other guards are encountered after this guard.
1872
1873 @code{with_state_guard_dynamic_object(o,...,code)}, will guard the state only in @code{code}. But reinstation will not happen unless reinstation is from a backtracked state. That is if reinstation i essentially back tracking it will not restire the state.
1874
1875 @code{with_state_guard_dynamic_object_zip(o,...,code)}, will guard the state only in @code{code}. The same as above but the state will be reinstated when zip et all switches branches.
1876
1877 @code{with_always_state_guard_dynamic_object(o,....,code)}, ditto but inside @code{code} always reinstate state.
1878
1879
1880 @subsubsection guarding values
1881
1882 @code{fluid_guard_dynamic_object(o,...)}, this will make sure that @code{o,...} is resetted to the value they had when the program passed over the guard, and reset to the value it had when control backttraced over it at reinstation over the guard.
1883
1884 @code{with_fluid_guard_dynamic_object(o,...,code)}, the same as above, but with an extra fluid guard at the success edge of @code{code}.
1885
1886 @code{with_fluid_guard_dynamic_object_once(o,...,code)}, the same as above but takes an optimization by forcing the @code{code} to only succeeds once.
1887
1888 @subsubsection utils,
1889 There are a few general util funcitons used to manage the state of the dynamic objects in a safe way.
1890
1891 @code{set_dynamic_object(m1 -> m2)}, the state @code{m1} state is transferd to @code{m2}
1892
1893 @code{copy_dynamic_object(m1 -> M2)},   @code{M2} will bind to a newly created object containing the state of @code{m1}.
1894
1895
1896 Added ontop of this is how to evolve the state data like asserting new facts or to add a new pair on a map. But these operations is defined in each of the library sections.
1897
1898 @node prolog-libraries
1899 @section Prolog libraries exposing guile-log features
1900 There are a few interesting datastructures and algorithm taken from guile-log that can be directly used in guile-log prolog, here we describe them:
1901
1902 @menu
1903 * prolog interleaving::    Kanren's interleving constructs.
1904 * prolog continuations::   Delimeted Continuation goals.
1905 * prolog zip::             Evaluating goals in parallell.
1906 * prolog hash::            VHashes and Vlists.
1907 * prolog postpone::        Postpone facilities.
1908 @end menu
1909
1910 @node prolog interleaving
1911 @subsection Interleaving constructs.
1912 Generally prolog empowers a depth first search. But with the interleaving constructs it is at least in principle possible to do a wide search. Especially if there is branches that are huge or infinite, a solver can get stuck in that branch, missing a simple shallow solution in another branch. The interleaving constructs can cure this.
1913
1914 @subsubsection Api
1915 @code{or_i(branch,...)}, will execute @code{branch...} cyclically e.g. first try @code{branch1}, if that fails, then try @code{branch2} and if @code{branch-n}, the end branch fails, then start all over from the beginning with the next try of @code{branch1} and so on.
1916
1917 @code{and_i(factor,...)}, will interleave the backtracking of @code{factor...} when the whole expression backtracks.
1918
1919 @code{or_union(branch,...)}, The same as with @code{or_i}, but any results will be unique.
1920
1921 @subsubsection Examples
1922 @verbatim
1923 /* X = A,A+1,A+2,...,A+10  */
1924 c(X,A)   :- c(X,A,0). 
1925 c(X,A,N) :- N < 10, 
1926               (X = A ; (B is A + 1, M is N + 1, c(X,B,M))).
1927
1928 /* or_i test */
1929 f1(X) :- or_i(c(X,0),c(X,100)).
1930
1931 /* and_i test */
1932 f2(X,Y) :- and_i(c(X,0),c(Y,100)).
1933
1934 /* or_union test */
1935 f3(X) :- or_union(c(X,0),c(X,2)).
1936
1937 (prolog-run 10 (X)   (f1 X))
1938 $1 = (0 100 1 101 2 102 3 103 4 104)
1939
1940 (prolog-run 10 (X Y) (f2 X Y))
1941 $2 = ((0 100) (1 100) (0 101) (2 100) (1 101) 
1942       (0 102) (3 100) (2 101) (1 102) (0 103))
1943
1944 (prolog-run 10 (X)   (f3 X))
1945 $3 = (0 2 1 3 4 5 6 7 8 9)
1946 @end verbatim
1947
1948 @node prolog continuations
1949 @subsection Delimited continuation goals.
1950 Continuations are a freezed state that is encapsulated by a lambda and can resstart at the stored location when one executes the lambda. Delimited continuations means that one can compose the continuations freely and basically mean thta from a control point the continuation evaluation returns what the lambda inside the control point returns, delimited continuations can therefore be construted and used like any other funciton in a composable way, normal continuatins can be more difficult to handle and does not compose nicely. The delimited continuation goal will fail if the enclosing code fails and it will fail according to the new setup. Also when a delimeted continuation goal succeeds if the continuated enclosed code suceeds (that we restarted in) and the goal works just like any other goal.
1951
1952 @subsubsection Api
1953 @code{with_prompt(tag,code,handler_data,handler)}, The enclosing code is @code{code}, which will first executed, if inside this, a @code{abort_to_prompt} is executed with a @code{tag}, matching this ideoms @code{tag}, then the @code{handler} will be executed with @code{handler_data} unified to,
1954
1955 @code{handler_data = [intag,next,kont,data_from_abort]}, The actual intag will be @code{intag}. A goal, @code{next()}, will be supplied which can be used to instruct the code to search for the next handler if executed. The actual continuation goal @code{kont}, is supplied as well as data send from the @code{abort_to_prompt} in @code{data_from_abort}. @code{kont} is a term with one argument and is executed like @code{call_k(kont,Arg)}, sending an @code{Arg} to the restart to the continuation. @code{kont} is live for the rest of the execution and the handler will at backtracking fail the whole @code{with_promt} ideom.
1956
1957 @code{call_k(kont,A)}, execute a continuation goal.
1958
1959 @code{abort_to_prompt(tag,data_to_handler, data_from_continuation)}, will abort with tag @code{tag}, for which a handler is searched. @code{data_to_handler}, is data sent to the handler, and @code{data_from_continuation}, is the data that is put inside the argument of the continuation.
1960
1961 @code{re_prompt(tag,kont,handle_data handle kont_data))}
1962
1963 @code{re_prompt(kont,handle_data handle kont_data))} (old tag is reused),
1964  
1965 an efficiency hack to handle the case when a continuation is executed, but with a new handler in stead of the old one that that continuation came from. This is useful because with this a generator built with this tool does not build up stack.
1966
1967 @subsubsection Example:
1968 @verbatim
1969 (use-modules (logic guile-log guile-prolog continuations))
1970
1971 /* produce a value X to the user */
1972 yield(X) :- abort_to_prompt(generator,X,_).
1973
1974 /* consume a value X from the user */
1975 eat(X)   :- abort_to_prompt(generator,_,X).
1976
1977 /* execute Goal and put the resulting generator state in F */
1978 generator(Goal,F) :- 
1979        with_prompt(generator, Goal,[generator,_,K,X], F=[K,X]).
1980
1981 /* [K,X] is the state argument, X will be the next value argument, F will
1982    bind to the new state */
1983 next([K,X],X,F)        :- re_prompt(K,[generator,_,K2,XX],F=[K2,XX],_).
1984
1985 /* same as next, but Y will be a value fed to the consumer generator */
1986 feed([K,_],Y,F)        :- re_prompt(K,[generator,_,K2,_ ],F=[K2,_ ],Y).
1987
1988 /* the full two way ideom */
1989 translate([K,X],X,Y,F) :- re_prompt(K,[generator,_,K2,XX],F=[K2,XX],Y).
1990
1991
1992 /* sum consumes via eat(X) and add X to the S */
1993 sum(S) :- eat(X),
1994           SS is S + X,
1995           sum(SS).
1996
1997 /* yields N,N+1,..,9 */
1998 iter(N) :- N < 10 -> ( yield(N),
1999                        N2 is N + 1, 
2000                        iter(N2) ).
2001
2002 /* create a producer F and a consumer S */
2003 run :-  generator(iter(0),F),       
2004         generator(sum(0),S),
2005         pr(F,S).
2006
2007 /* transfers data from the producer to the feeder */
2008 pr(F,S) :- next(F,X,FF) -> feed(S,X,SS), pr(FF,SS).
2009
2010 @end verbatim
2011 @node prolog zip
2012 @subsection Zip like constructs
2013 This is a construct that let you execute several goals in paralell. currently this is not the same as executing it on multiple threads or processors, it's more that you want to synch solutions to several goal at the same time. The interface sports two commands, one simpler @code{zip}, for use, when the goal's are synchronized, and another one @code{usr_zip}, for the case when one would like to test the output and in depending on the outcome take the next solution for a subset of the branches.
2014
2015 @subsubsection Api
2016 @code{zip(lane(V,Goal),...)}, will execute @code{Goal ...}, in parallel and output the values of the variables @code{V...}, for the different branches. 
2017
2018 @code{usr_zip(lane(tag,V,Goal),...,guard)}, this is the same as @code{zip}, but we will tag the @code{lane} as well. Inside @code{guard}, one can execute a command
2019
2020 @code{update(tag,...)}, where the lanes associated to the tags @code{tag ...} is backtracked and updated with new solutions.
2021
2022 @subsubsection Examples
2023 @verbatim
2024   c(X,A)   :- c(X,A,0). 
2025   c(X,A,N) :- N < 10, 
2026                 (X = A ; (B is A + 1, M is N + 1, c(X,B,M))).
2027
2028   f(X,Y) :- zip(lane(X, c(X,0)    ),
2029                 lane(Y, c(Y,100)  )).
2030
2031   (prolog-run * (X Y) (f X Y))
2032
2033 $1 = ((0 100) (1 101) (2 102) (3 103) (4 104) 
2034       (5 105) (6 106) (7 107) (8 108) (9 109))
2035
2036
2037   g(X,Y) :- usr_zip(lane(Tag_a,X,c(X,0)),
2038                     lane(Tag_b,Y,c(Y,0)),
2039                     (((X mod 2) == 0 -> update(Tag_a)),
2040                      ((Y mod 1) == 0 -> update(Tag_b)))).
2041
2042 $2 = ((1 100) (3 102) (5 104) (7 106) (9 108))
2043 @end verbatim
2044
2045 @node prolog hash
2046 @subsection Hash datastructure
2047 The main hash datastructure is a vhash datastructure which is a assoc like hash with good lookup properties.
2048
2049 @subsubsection API.
2050
2051 @code{make_vhash(Handle)}, Constructor, generate a dynamic featured vhash unified to @code{Handle}.
2052
2053 @code{vhashp(Handle)}. Succeeds if @code{Handle} is a vhash datastructure.
2054
2055 @code{vhash_ref(Handle, Key)}. References the vhash datastructure.
2056
2057 @code{vhash_cons(Handle, Key, Val)}. (conses a @code{Key,Val} pair onto the @code{Handle}.
2058
2059 @code{vhash_for_each(Handle,Key,Val)}. Will successivly at backtracking bind new values in @code{Key} and @code{Val}. The generated values will be those defined at the start of the execution of this ideom.
2060
2061
2062 @node prolog postpone
2063 @subsection Postpone.
2064
2065
2066 @node internals
2067 @section Prolog internals
2068
2069
2070
2071
2072
2073
2074
2075 @node Index
2076 @chapter Index of the guile-log api
2077 @unnumbered Index
2078      
2079 @printindex cp
2080 @printindex fn
2081 @printindex vr
2082             
2083 @bye