trac_lang 0.1.0

data/examples/term.trl

@@ -0,0 +1,129 @@
+
+ANSI Escape Codes
+-----------------
+
+#(PS,Loading examples/term.trl...)'
+
+Here are some basic ANSI escape codes for controlling text appearance.  
+
+First we define the codes for effects:
+
+#(DS,define-effect,(
+  #(EQ,<number>,-END-,,(
+    #(DS,clr-#(CS,effect-list),<number>)
+    #(define-effect,#(CS,effect-list,-END-))
+  ))
+))
+#(scrub,define-effect)
+#(SS,define-effect,<number>)'
+
+#(DS,effect-list,(
+0 reset
+1 bright
+2 dim
+4 underscore
+5 blink
+7 reverse
+8 hidden))'
+
+#(SS,effect-list,( ),##(CL,return))'
+
+Notice how I segment the effect-list by spaces and newlines.  That makes it
+easy to write readable lists in your code.
+
+Discard first empty segment: #(CS,effect-list)'
+
+#(define-effect,#(CS,effect-list))'
+
+Next we define the codes for colors, foreground and background:
+
+#(DS,define-color,(
+  #(EQ,<number>,-END-,,(
+    #(define-colors,#(CS,color-list),<number>)
+    #(define-color,#(CS,color-list,-END-))
+  ))
+))
+#(scrub,define-color)
+#(SS,define-color,<number>)'
+
+#(DS,define-colors,(
+  #(DS,clr-<name>-fg,3<number>)
+  #(DS,clr-<name>-bg,4<number>)
+))
+#(scrub,define-colors)
+#(SS,define-colors,<name>,<number>)'
+
+#(DS,color-list,(
+0 black
+1 red
+2 green
+3 yellow
+4 blue
+5 magenta
+6 cyan
+7 white))
+
+#(SS,color-list,( ),##(CL,return))'
+
+Discard first empty segment:  #(CS,color-list)'
+
+#(define-color,#(CS,color-list))'
+
+#(DD,define-effect,define-color)'
+
+
+Now we define our script that will translate the names above into actual escape
+codes.  
+
+#(DS,color,(
+  #(DS,list,<list>)
+  #(SS,list,##(CL,space))
+  #(DS,read,(
+    #(clr-<s>)
+    #(next,#(CS,list,END))
+  ))
+  #(SS,read,<s>)
+  #(DS,next,(
+    #(EQ,<s>,END,,(;#(read,<s>)))
+  ))
+  #(SS,next,<s>)
+  #(escape)[#(read,#(CS,list,reset))m
+  #(DD,list,read,next)
+))
+#(sss,color,<list>)'
+
+Usage:
+(
+  #(color,bright red-fg blue-bg)
+  
+  Defaults to reset:  #(color)
+  
+  The escape codes need to be embedded in print commands to take effect, like
+  so:
+  
+  #(PS,#(color,green-fg)I am green!#(color) I am not!)
+
+  Using these you can make templates for creating forms:
+  
+  #(DS,template,(
+  *label*Name:**	*field*<name>**
+  *label*Occupation:**	*field*<job>**
+  *label*Age:**		*field*<age>**
+  ))
+  
+  #(SS,template,**,*label*,*field*)
+  
+  #(DS,form,##(CL,template,#(color),#(color,bright),#(color,reverse)))
+  
+  #(SS,form,<name>,<job>,<age>)
+  
+  Now you can fill out the form multiple times, and it will print with the
+  format you decided on.  Notice that I used a neutral call on the template
+  when defining the form to protect the newlines in it.
+
+)
+
+
+#(PS,(success!
+))'
+      

data/examples/util.trl

@@ -0,0 +1,366 @@
+
+Basic Utilities
+
+#(PS,Loading examples/util.trl...)'
+
+Scrub Whitespace
+----------------
+A problem with TRAC definitions is they're strings, and so if you add
+whitespace to make them readable, your definition ends up with a lot of 
+extraneous whitespace.  Carriage return and line feed are normally ignored if
+they aren't protected, so they don't need to be removed, but spaces and tabs
+aren't.  So here are some scripts to help out:
+
+scrub-char
+	scrubs a single character out of your script
+
+	#(DS,scrub-char,(#(SS,<f>,(<c>))#(DS,<f>,##(CL,<f>))))
+	#(SS,scrub-char,<f>,<c>)'
+
+scrub
+	scrubs spaces and tabs out of your script
+	
+	#(DS,scrub,(#(scrub-char,<f>,(	))#(scrub-char,<f>,( ))))
+	#(SS,scrub,<f>)'
+
+Call these scripts on your definitions before you call SS, otherwise your 
+arguments will get messed up.  To make that easier to do:
+
+sss	scrubs your script and then segments according to the args you pass
+
+	#(DS,sss,(#(scrub,<f>)#(SS,<f>,<args>)))
+	#(SS,sss,<f>,<args>)'
+
+If you use this for a script that has multiple arguments, protect the argument
+list with parentheses, otherwise TRAC will think your arguments are extra 
+arguments for sss, instead of for SS.  Remember TRAC is only passing around 
+strings, not data structures.
+
+
+Special Characters
+------------------
+Another problem with TRAC is that some characters are special, and so can't be
+used normally.  This is especially true of the two editing characters - the "\"
+and the "@".  They can't be typed in, but since editing is not done when 
+reading a file, they can be entered in a file.  So here are definitions for 
+each.
+
+#(DS,backslash,\)'
+#(DS,at,@)'
+
+The meta character can be changed, so that a definition of the default meta 
+character single quote can be made.  
+
+#(CM,*)'
+#(DS,quote,')*
+#(CM,')*
+
+Both the hash or number sign and the comma can easily be protected by
+parentheses, so neither need a separate defintion.  Here's how parentheses can
+be defined:
+
+#(DS,parens,(()))
+#(DS,open-paren,##(CC,parens))
+#(DS,close-paren,##(CC,parens))
+#(DD,parens)'
+
+However, even if you use a neutral call, unmatched parens can only be passed to
+a TRAC primitive.  You can't pass them to a form you define, because once the 
+form is expanded, the parens will no longer match.
+
+Some important characters:
+
+#(DS,return,(
+))'
+#(DS,tab,	)'
+#(DS,space, )'
+#(DS,bell,)'
+#(DS,escape,)'
+#(DS,backspace,)'
+
+The following is the first control character, known as SOH.  We will use it as
+a delimiter sometimes, instead of using a printable character.
+
+#(DS,.,
)'
+
+
+Character Classes
+-----------------
+
+Here are some useful character classes.
+
+#(DS,lower,abcdefghijklmnopqrstuvwxyz)'
+#(DS,upper,ABCDEFGHIJKLMNOPQRSTUVWXYZ)'
+#(DS,digit,0123456789)'
+#(DS,whitespace,##(return)##(tab)##(space))'
+
+Here are some scripts for using the character classes.  These were inspired by
+TTM primitives that have the same names.  See page 20 and 21 of TTM: An 
+Experimental and Interpretive Language.
+
+https://github.com/Unidata/ttm/raw/master/ttm_interpretive_language_pr_07.pdf
+
+#(DS,[TCL],(
+  #(EQ,(<c>),--,(Z),(
+    #(CR,class)
+    #(EQ,##(IN,class,(<c>),--),--,(F),(T))
+  ))
+))
+#(sss,[TCL],(class,<c>,T,F,Z))
+#(DS,TCL,(#([TCL],class,##(CC,form,--),(T),(F),(Z))))
+#(SS,TCL,class,form,T,F,Z)'
+
+TCL (Test Class) tests if the character pointed to by the form pointer is in
+the class given.  If returns T if so, F if not, and Z if the form pointer is at
+the end of the form.
+
+#(DS,[CCL],(
+  #([TCL],class,(<c>),(
+    (<c>)#([CCL],class,##(CC,form,--),form)
+  ),(
+    #(,##(CN,form,-1))
+  ))
+))
+#(sss,[CCL],(class,<c>,form))
+#(DS,CCL,(#([CCL],class,##(CC,form,--),form)))
+#(SS,CCL,class,form)'
+
+CCL (Call Class) returns all consecutive characters from the given form,
+starting at the form pointer and going up to but not including the first
+character that is not in the given class.  In other words, it will return a
+string of characters that are in the class given.  If there are no characters
+in the given class at the form pointer, or if the form pointer is at the end of
+the form, nothing is returned.
+
+#(DS,SCL,(#(,#(CCL,class,form))))
+#(SS,SCL,class,form)'
+
+SCL (Scan Class) will move the form pointer past all characters in the form
+that are in the given character class.
+
+
+Times
+-----
+Execute something a number of times.  The action can be a simple string or 
+something more complicated.
+
+#(DS,times,(
+  #(EQ,<n>,0,,(
+    <action>#(times,#(SU,<n>,1),(<action>)))
+  ))
+)
+#(sss,times,(<n>,<action>))'
+
+
+Character Count
+---------------
+Count the number of characters in a form.  This is probably the most involved
+thing that I wish was a primitive in TRAC.  There isn't a code golf challenge 
+that doesn't require this, and if it was a primitive TRAC might actually have a
+chance.
+
+This really counts from the form pointer to the end, and sets the form pointer
+at the end of the string as a side effect.  So if you want the real length, you
+have to call CR beforehand.
+
+#(DS,count,(
+  #(EQ,##(CC,<f>,--),--,<tot>,(
+    #(count,<f>,#(AD,1,<tot>))
+  ))
+))
+#(sss,count,(<f>,<tot>))'
+
+
+Concatenate
+-----------
+
+Add given characters to the end of a given form.  A very simple definition, but
+useful when you only have one reference to the form you want to concatenate on.
+
+#(DS,concat,(
+  #(DS,form,##(CL,form,args)(str))
+  #(SS,form,args)
+))
+#(sss,concat,(form,args,str))'
+
+
+Increment
+---------
+
+Another very simple definition of something that's easy to do.  But it's also
+easy to forget that the form "num" needs to executed for the AD to work, in 
+which case you end up with one as your value, instead of what you want.
+
+#(DS,inc,(#(DS,num,#(AD,#(num),1))))
+#(SS,inc,num)'
+
+
+Move To End
+-----------
+Move to the end of a form.  This is relatively simple, but it sure would be
+nice to have a primitive that could do this, the way CR can move to the start
+of a form.
+
+#(DS,end,(
+  #(EQ,##(CC,<form>,--),--,,(
+    #(end,<form>)
+  ))
+))
+#(sss,end,<form>)'
+
+
+At End Or Beginning?
+--------------------
+Test if you are at the end of a form.  This uses a special trick of TRAC, when
+the form pointer is at the end of a form, CN returns the end-of-form argument
+even when you ask for zero characters.  The same trick works at the beginning
+of a form when you use negative zero.  This trick is the whole reason that 
+negative zero exists in TRAC.
+
+#(DS,end?,(#(EQ,#(CN,form,0,#(.)),#(.),(T),(F))))
+#(SS,end?,form,T,F)'
+
+#(DS,start?,(#(EQ,#(CN,form,-0,#(.)),#(.),(T),(F))))
+#(SS,start?,form,T,F)'
+
+
+Form Exists
+-----------
+
+This relies on a odd property of IN.  If you search for the empty string in a
+form using IN, if the form doesn't exist, the empty string is returned.  If the
+form does exist, searching for the empty string will fail, and so the 
+"not found" parameter will be returned.  We can use this to create a test for
+the existence of a form.
+
+#(DS,exists?,(#(EQ,#(IN,form,,notfound),notfound,(T),(F))))
+#(SS,exists?,form,T,F)'
+
+
+Starts With
+-----------
+
+Tests if a given string starts with a given value.  Notice that I have to
+define a form with the string to search in and then delete it when I'm done
+with it.  I use the special character as the temporary name, so that I don't
+overwrite an existing form.
+
+#(DS,starts-with,(
+  #(DS,#(.),(string1))
+  #(EQ,#(IN,#(.),(string2),-),,#(DD,#(.))(T),(F))
+))
+#(sss,starts-with,(string1,string2,T,F))
+
+
+List Forms With Prefix
+----------------------
+
+One way to organize the list of defined forms is to prefix the name of related
+forms with a certain value.  For instance, all the color code definitions in
+the term.trl file are prefixed with "clr-".  This script allows you to list the
+only those forms.  Notice I use the dot special character as a delimiter, so
+you can use any printable character in your form names.
+
+#(DS,list-prefix,(
+  #(DS,[names],#(LN,#(.)))
+  #(SS,[names],#(.))
+  #(DS,[delimiter])
+  #(DS,[next],(
+    #(EQ,<name>,#(.),,(
+      #(DS,[name],<name>)
+      #(EQ,#(IN,[name],prefix,#(.)),,(
+        #(CR,[name])
+        ##([delimiter])#([name])
+        #(DS,[delimiter],(<delimiter>))
+      ))
+      #([next],#(CS,[names],#(.)))
+    ))
+  ))
+  #(SS,[next],<name>)
+  #([next],#(CS,[names],#(.)))
+  #(DD,[next],[names],[name],[delimiter])
+))
+#(sss,list-prefix,(prefix,<delimiter>))'
+
+
+Get Segment By Index
+--------------------
+
+Returns a segment of a form by the one-based index of it.  If the index is out
+of range (below one or above the number of segments in the form), the default
+is returned.
+
+#(DS,segment,(
+  #(DS,[seg],(
+    #(EQ,(value),#(.),(default),(
+      #(GR,2,count,#(CR,form)(value),(
+        #([seg],#(SU,count,1),##(CS,form,#(.)))
+      ))
+    ))
+  ))
+  #(SS,[seg],count,value)
+  #(GR,1,index,(default),(
+    #([seg],index,#(CS,form,#(.)))#(CR,form)
+  ))
+))
+#(sss,segment,(index,form,default))'
+
+
+Logic - And, Or and Not
+-----------------------
+
+These work by passing partial function calls.  For example, to test if a number
+is between -1 and 1 you would do:
+(
+  #(and,(GR,a,-1),(GR,1,a),between,not-between)
+)
+Any test that returns either a true or false value can be used, both built-in
+tests and any user-defined tests as well.  These can be nested if necessary,
+although that can become unreadable very quickly.  For example, test if "b" is
+in the interval ]-1,1[ or the interval ]2,3[:
+(
+  #(or,(and,(GR,b,-1),(GR,1,b)),(and,(GR,b,2),(GR,3,b)),true,false)
+)
+Both "and" and "or" are short-circuited, in other words, if the first test
+determines what the result is, the second test is not executed.
+
+#(DS,and,(
+  #(EQ,#(test1,T,F),T,(
+    #(EQ,#(test2,T,F),T,(true),(false))
+  ),(false))
+))
+#(sss,and,(test1,test2,true,false))'
+
+#(DS,or,(
+  #(EQ,#(test1,T,F),T,(true),(
+    #(EQ,#(test2,T,F),T,(true),(false))
+  ))
+))
+#(sss,or,(test1,test2,true,false))'
+
+And here's the implementation of not.  Just pass it a partial test, same as you
+do for "and" and "or".
+
+#(DS,not,(#(test,(F),(T))))
+#(SS,not,test,T,F)'
+
+
+#(PS,(success!
+))'
+
+
+Load Other Files
+----------------
+
+#(DS,term,term.trl)
+#(FB,term)'
+#(DS,math,math.trl)
+#(FB,math)'
+#(DS,meta,meta.trl)
+#(FB,meta)'
+#(DS,ratio,ratio.trl)
+#(FB,ratio)'
+#(DS,struct,struct.trl)
+#(FB,struct)'
+#(DS,list,list.trl)
+#(FB,list)'