trac_lang 0.1.0

data/examples/meta.trl

@@ -0,0 +1,254 @@
+
+Meta Programming
+
+#(PS,Loading examples/meta.trl...)'
+
+Anonymous forms
+---------------
+
+We want to be able different classes of anonymous forms.  The following does
+that, creating a class of anonymous forms with the given name.  We first save a
+special prefix for the name of all the forms in the class.  Next we create the
+creating form, that will create members of the class.  It creates the member
+and then returns its name.  We can use the name like a function pointer to call
+the form wherever we want.  We next create a test form, that checks if the
+given name is a name of a form in our class.  We both test if the name is the
+name of a form and if the name starts with the form prefix.  The last form we
+create is for cleaning up.  When called it will delete all the forms of the 
+given class.
+
+#(DS,anonymous,(
+  #(DS,name-prefix,name..)
+  #(DS,name,(
+    #(DS,name-seq,#(AD,1,#(name-seq)))
+    #(DS,#(name-prefix)#(name-seq),(value))
+    #(SS,#(name-prefix)#(name-seq),args)
+    #(name-prefix)#(name-seq)
+  ))
+  #(SS,name,args,value)
+  #(DS,name-current,(#(name-prefix)#(name-seq)))
+  #(DS,name?,(
+    #(and,(exists?,(obj)),(starts-with,(obj),#(name-prefix)),(T),(F))
+  ))
+  #(SS,name?,obj,T,F)
+  #(DS,name-gc,(
+    #(DD,#(list-prefix,#(name-prefix),(,)))
+  ))
+))
+#(sss,anonymous,name)'
+
+We'll use lambda to define anonymous functions.
+
+    #(anonymous,lambda)'
+
+It can be used as follows:
+(
+   #(lambda,n,(#(AD,1,n)))    => successor function
+   
+   #(lambda?,x,if-so,if-not)  => test if something is a lambda
+   
+   #(lambda-gc)               => deletes all lambdas
+)
+
+We'll use data to define anonymous pieces of data.
+
+    #(anonymous,data)'
+
+We use it similarly to lambda:
+(
+    #(data,(,),(1,2,3,4))           => array of numbers
+    
+    #(data?,formname,if-so,if-not)  => test if something is a data form
+    
+    #(data-gc)                      => delete all data forms
+)
+
+Curry
+-----
+
+Currying is to take a script that takes multiple arguments, fill in some of its
+arguments and return a script that will take the rest of the necessary 
+arguments and can be called at a later time.
+
+#(DS,curry,(#(lambda,(<y>),##(CL,<f>,<x>,<y>))))
+#(SS,curry,<f>,<x>)'
+
+Usage:
+(
+  #(DS,func,#(curry,multi-arg-func,(a,b,c)))
+  ...
+  #(#(func),(some,more,args))
+  
+  Or another more concrete example:
+  
+  We need to redefine primitives to curry them:
+  #(DS,mult,(#(ML,a,b)))
+  #(SS,mult,a,b)
+  
+  Now we define something that prints an action for each number 1 through 10.
+  
+  #(DS,1-10,(
+    #(EQ,count,10,,(
+      #(PS, #(action,#(AD,1,count)))
+      #(1-10,#(AD,1,count))
+    ))
+  ))
+  #(sss,1-10,(action,count))
+  
+  Print ten even numbers
+  #(1-10,#(curry,mult,2))
+  
+  Print ten multiples of five
+  #(1-10,#(curry,mult,5))
+)
+
+Currying doesn't have to be that formal with TRAC.  Since TRAC is a string
+language, you can define pieces of functions and then assemble them when
+necessary.  In the following, we define a sum function that takes two 
+lambdas, a test and a func.  
+
+#(DS,sum,(
+  #(#(test,start),total,(
+    #(sum,#(AD,1,start),test,func,#(AD,total,#(func,start)))
+  ))
+))
+#(sss,sum,(start,test,func,total))'
+
+You see here how we would sum up all the squares from one to five.  Notice that
+the first lambda is simply the first three arguments of the GR primitive.  When
+it is replaced in the definition of sum above, if GR is true, the running total
+if returned, otherwise sum is called again.  The GR primitive has been
+effectively curried, changed into a test that takes a single argument.
+(
+#(sum,1,#(lambda,n,(GR,n,5)),#(lambda,n,(#(ML,n,n))))
+)
+
+
+Combinators
+-----------
+
+TRAC can't support real combinators, since it doesn't have truly anonymous 
+functions.  But with a little creativity, you can create something that looks
+an awful lot like the Y combinator, and does the same kind of work.
+
+Of course these combinators aren't necessary for TRAC.  TRAC already supports
+recursion, so there's no need to create a script that can make scripts 
+recursive.  However, this does show the power of TRAC and it also helps clear
+up some of the mystique of these combinators.
+
+U Combinator
+------------
+The U combinator takes as an argument the name of a script whose only argument
+is a script name.
+
+#(DS,U,(#(<f>,<f>)))
+#(SS,U,<f>)'
+
+Using the U combinator we can create a recursive function from a special sort
+of function.  Here's an example for calculating the factorial.
+
+(
+#(DS,fact,(
+  #(lambda,<n>,(
+    #(EQ,<n>,0,1,(
+      #(ML,<n>,#(#(U,<f>),#(SU,<n>,1)))
+    ))
+  ))
+))
+#(sss,fact,<f>)
+#(DS,!,(#(#(U,fact),<n>)))
+#(SS,!,<n>)
+)
+
+How does the U combinator work?  If you turn trace on and trace through the
+operation of ! you get a good idea of what's happening.  The "fact" script
+creates an anonymous function which does the work of testing the end condition
+and setting up the multiplication necessary. The U combinator passes a script
+to itself, allowing it to call itself without direct recursion.  The doubling
+in the U combinator is what makes the recursion work.  It passes a copy of the
+script to be called to itself.  
+
+The U combinator must be called inside the script that's being made recursive,
+which isn't as neat as we would like.  If we factor the U combinator out of 
+our script, we get the famous Y combinator.
+
+
+Y Combinator
+------------
+
+This version of the Y combinator uses the U combinator in its definition.  Pass
+in a script that takes a single argument and returns the name of a script.  
+Looking at it this way and comparing it to the factorial definition above helps
+make it understandable.  The outer U corresponds to the U in the definition of 
+!, while the inner U corresponds to the U in the definition of fact.  The
+definition of an anonymous function is necessary because that's the only real
+way TRAC has of passing a function around as an object.  As a result this
+creates a lot of identical anonymous functions.
+
+#(DS,Y,(
+  #(U,(
+    #(lambda,<x>,(
+      #(<f>,(#(U,<x>)))
+    ))
+  ))
+))
+#(sss,Y,<f>)'
+
+
+Y Combinator w/o U
+------------------
+
+Here's the closest TRAC is going to get to having a real Y combinator.  We take
+the version of Y above and expand the definition of the U combinator.  If 
+you've seen the Y combinator in other forms, you will see the resemblance here.  
+
+#(DS,Y,(
+  #(#(lambda,<x>,(
+    #(<f>,(#(<x>,<x>)))
+  )),#(lambda,<x>,(
+    #(<f>,(#(<x>,<x>)))
+  ))
+  )
+))
+#(sss,Y,<f>)'
+
+What's interesting is how the Y combinator is thought of as an airy abstraction
+in computing, but here it's being defined in a language which is nothing but
+strings, which is about as concrete as you can get.
+
+Here's how you would create the factorial function using the Y combinator.  We
+create a script that takes an anonymous function as an argument and returns a
+new anonymous function.  The anonymous function returned takes a single integer
+argument and returns one if the input was zero, otherwise multiplies the input
+by the output of the script passed in.
+
+(
+#(DS,fact,(
+  #(lambda,<n>,(
+    #(EQ,<n>,0,1,(
+      #(ML,<n>,#(<f>,#(SU,<n>,1)))
+    ))
+  ))
+))
+#(sss,fact,<f>)
+#(DS,!,(#(#(Y,fact),<n>)))
+#(SS,!,<n>)
+)
+
+Here's how you would count characters in a form using the Y combinator.
+
+(
+#(DS,count,(
+  #(lambda,<s>,(
+    #(EQ,#(CC,<s>,**),**,0,(
+      #(AD,1,#(<f>,<s>))
+    ))
+  ))
+))
+#(sss,count,<f>)
+#(DS,*,(#(#(Y,count),<s>)))
+#(SS,*,<s>)
+)
+
+#(PS,(success!
+))'

data/examples/ratio.trl

@@ -0,0 +1,107 @@
+
+Definition of rational numbers
+
+#(PS,Loading examples/ratio.trl...)'
+
+Basics
+-------------------------------------------------------------------------------
+
+The format of our rational numbers will be:
+
+numerator/denominator
+
+To work with them we will need a way of extracting the numerator and
+denominator from them.  So we need our anonymous data form.  We use the default
+values for the segment form to make 0/1 the default rational.  The default
+denominator of one also means that whole numbers will be interpreted correctly,
+and so can be mixed in with rationals without a problem.
+
+#(DS,numr,(#(segment,1,#(data,/,x),0)))
+#(SS,numr,x)'
+
+#(DS,dnmr,(#(segment,2,#(data,/,x),1)))
+#(SS,dnmr,x)'
+
+Often we are going to need to pass a rational into a form as a separate
+numerator and denominator.  So it will be useful to have a function that
+changes a rational into a set of two parameters.  The following will replace
+the slash in a rational with a comma.  I could use CL to call the data and
+put the comma in the space between segments, but that wouldn't give me my
+default denominator of one which makes it possible to mix rationals and
+integers.  Also notice that I use the data-current call here, so that I don't
+have to duplicate the creation of the temporary data form.
+
+#(DS,argr,(#(segment,1,#(data,/,x),0),#(segment,2,#(data-current),1)))
+#(SS,argr,x)'
+
+Next we need a way of reducing fractions to standard form.  
+
+First we have something to reduce the faction by a given value.
+
+#(DS,reduceby,(#(DV,#(numr,x),by)/#(DV,#(dnmr,x),by)))
+#(SS,reduceby,x,by)'
+
+Next we have a function to normalize the sign of a fraction.  Notice that if
+the denominator is zero, we change the fraction to 0/0, our form for NaN.
+
+#(DS,reducesign,(#(sgn?,denom,numer/denom,0/0,(#(-,numer)/#(-,denom)))))
+#(SS,reducesign,numer,denom)'
+
+We need a GCD that's works the same with negative and positive numbers.
+
+#(DS,gcd+,(#(gcd,#(abs,x),#(abs,y))))
+#(SS,gcd+,x,y)'
+
+Finally we combine all these functions into one that will put all our rationals
+in normal form.
+
+#(DS,reduce,(#(reducesign,#(argr,#(reduceby,x,#(gcd+,#(argr,x)))))))
+#(SS,reduce,x)'
+
+
+Arithmetic
+-------------------------------------------------------------------------------
+
+#(DS,[addr],(#(reduce,#(op,#(ML,<a>,<d>),#(ML,<b>,<c>))/#(ML,<b>,<d>))))
+#(SS,[addr],op,<a>,<b>,<c>,<d>)'
+
+#(DS,addr,(#([addr],AD,#(argr,x),#(argr,y))))
+#(SS,addr,x,y)'
+
+#(DS,subr,(#([addr],SU,#(argr,x),#(argr,y))))
+#(SS,subr,x,y)'
+
+#(DS,mulr,(#(reduce,#(ML,#(numr,x),#(numr,y))/#(ML,#(dnmr,x),#(dnmr,y)))))
+#(SS,mulr,x,y)'
+
+#(DS,divr,(#(reduce,#(ML,#(numr,x),#(dnmr,y))/#(ML,#(numr,y),#(dnmr,x)))))
+#(SS,divr,x,y)'
+
+#(DS,rcpr,(#(dnmr,x)/#(numr,x)))
+#(SS,rcpr,x)'
+
+
+Tests
+-------------------------------------------------------------------------------
+
+#(DS,grr,(#(GR,#(ML,#(numr,x),#(dnmr,y)),#(ML,#(numr,y),#(dnmr,x)),(T),(F))))
+#(SS,grr,x,y,T,F)'
+
+#(DS,eqnr,(#(and,(eqn,#(numr,x),#(numr,y)),(eqn,#(dnmr,x),#(dnmr,y)),(T),(F))))
+#(SS,eqnr,x,y,T,F)'
+
+#(DS,NaN?,(#(eqn,#(dnmr,x),0,(T),(F))))
+#(SS,NaN?,x,T,F)'
+
+
+Now we can use rational numbers, and even mix integers in with them. 
+(
+    #(subr,1,1/3)              => 2/3
+    #(mulr,5/7,14)             => 10/1
+    #(grr,5/7,2/3,true,false)  => true
+    #(rcpr,2)                  => 1/2
+)
+
+
+#(PS,(success!
+))'

data/examples/struct.trl

@@ -0,0 +1,176 @@
+
+Data Structures
+
+#(PS,Loading examples/struct.trl...)'
+
+Stack
+-----
+
+Here's an implementation of a stack in TRAC.  
+
+Our first definition is push.  The complicated expression at the start is
+checking if our stack exists yet or if it is empty.  If either is true, set the
+stack to the value given.  Otherwise, add the value to the top of the stack.
+Because of the error checking, we don't have to create a stack before using it.
+We can just push something onto it to create it.
+
+#(DS,push,(
+  #(or,(not,(exists?,name)),(EQ,##(CL,name),),(
+    #(DS,name,(value))
+  ),(
+    #(DS,name,(value)#(.)##(CL,name,#(.)))
+  ))
+  #(SS,name,#(.))
+))
+#(sss,push,(name,value))'
+
+Now, pop a value off the top of the stack.  If the stack is empty, return the
+ifempty parameter.  Here we see the form pointer in action.  The CS call moves
+the form pointer after the end of the first segment, so the CL call in the next
+line only returns the rest of the stack.  This works because DS and SS return
+the empty string, so the return from CS is the return from the pop function.
+If the stack doesn't exist, this will have the side-effect of creating an empty
+stack.
+
+#(DS,pop,(
+  #(CS,name,ifempty)
+  #(DS,name,##(CL,name,#(.)))
+  #(SS,name,#(.))
+))
+#(sss,pop,(name,ifempty))'
+
+Finally, peek at the top of the stack without removing the value.
+
+#(DS,peek,(
+  #(CS,name,ifempty)
+  #(CR,name)
+))
+#(sss,peek,(name,ifempty))'
+
+
+Queue
+-----
+
+A queue is very similar to a stack, we just add things to the end of the string
+instead of the beginning.  Dequeue is just a synonym for pop, and peek works on
+both stacks and queues.
+
+#(DS,enqueue,(
+  #(or,(not,(exists?,name)),(EQ,##(CL,name),),(
+    #(DS,name,(value))
+  ),(
+    #(DS,name,##(CL,name,#(.))#(.)(value))
+  ))
+  #(SS,name,#(.))
+))
+#(sss,enqueue,(name,value))'
+
+#(DS,dequeue,##(CL,pop,name,ifempty))
+#(SS,dequeue,name,ifempty)'
+
+
+Hash
+----
+
+A hash piggybacks on the form dictionary.  The hash name and key are mashed
+together to make the name of the form that holds the corresponding value.  From
+this we can easily define all the typical hash methods.
+
+#(DS,put,(#(DS,name:key,value)))
+#(SS,put,name,key,value)'
+
+#(DS,get,(#(name:key)))
+#(SS,get,name,key)'
+
+#(DS,contains,(#(exists?,name:key,(T),(F))))
+#(SS,contains,name,key,T,F)'
+
+#(DS,keys,(#(list-prefix,name:,delimiter)))
+#(SS,keys,name,delimiter)'
+
+#(DS,delete-hash,(#(DD,#(list-prefix,name:,(,)))))
+#(SS,delete-hash,name)'
+
+An array is just a special kind of hash that uses numbers for keys, and a set
+is just a hash where you ignore the values set.
+
+There's one other trick you can do with hashes.  By creating the following two
+functions, you can make a hash into a primitive object, with methods as well as
+data.
+
+#(DS,define,(
+  #(DS,name:method,(action))
+  #(SS,name:method,args)
+))
+#(sss,define,(name,method,args))'
+
+#(DS,call,(#(CL,name:method,args)))
+#(SS,call,name,method,args)'
+
+A hash with such methods isn't a true object - it doesn't have a defining class
+and there's no such thing as inheritance.  But it's still an example of data
+and functions bound together in one object.
+
+
+Case
+----
+
+Here's the case statement, so TRAC can be routed to different actions based on
+the value of something.  It may seem strange to have a control structure in the
+example file for data structures, but really, control structures *are* data
+structures.  The case statement is just a special kind of hash with a default
+value.  
+
+#(DS,case,(#(DS,case-prefix,name)))
+#(SS,case,name)'
+
+#(DS,when,(
+  #(DS,#(case-prefix):(value),(action))
+  #(scrub,#(case-prefix):(value))
+))
+#(SS,when,value,action)'
+
+#(DS,default,(
+  #(DS,#(case-prefix):default,(action))
+  #(sss,#(case-prefix):default,value)
+))
+#(sss,default,action)'
+
+#(DS,end-case,(
+  #(DS,[end-case],(
+    #(DS,prefix,(
+      #(exists?,prefix:(value),(
+        #(prefix:(value))
+      ),(
+        #(prefix:default,(value))
+      ))
+    ))
+    #(SS,prefix,value)
+  ))
+  #(SS,[end-case],prefix)
+  #([end-case],#(case-prefix))
+))
+#(sss,end-case,name)'
+
+These are defining words - in other words, they define pieces of code, so they
+should be used at the same level as you use DS and other defining words.  The
+example will make things more clear.  
+
+(
+  Defining the code to run:
+  
+  #(case,execute-option)
+  #(when,d,(#(delete-file)))
+  #(when,g,(#(get-file)))
+  #(when,q,(#(HL)))
+  #(default,(#(PS,#(help-text))))
+  #(end-case)
+  
+  Actually calling the code:
+  
+  #(execute-option,#(RC))
+)
+
+
+#(PS,(success!
+))'