Differences

This shows you the differences between two versions of the page.

--- documentation [2010/02/23 04:51]
redbrain
+++ documentation [2010/05/21 04:05] (current)
redbrain
@@ Line 1: / Line 1: @@
-====== Documentation ======
+====== Language Documentation/Tutorial ======
 Crules has been specificity designed to be simple and intuitive for programmers, by making computing procedures easier while remaining dynamic and reusable. Designed with clean, clear syntax and keywords; along with a fully dynamic typing system; fast and dynamic data structures which makes it a great platform as a scripting engine which can be embedded into existing programs for a more high level logic computation or even as a fast and reliable application development platform, with a definite focus on being integrated with existing technologies.
-For now in the early life of this language we will focus on explaining the language until more advanced features (which will set it apart) are more stable and use-able, and since the nature of an early project the syntax for certain language constructs may change!
+For now in the early life of this language we will focus on explaining the language core until more advanced features (which will set it apart) are more stable and use-able, and since the nature of an early project the syntax for certain language constructs and semantics may change often!
-===== Interaction with the Interpreter =====
+===== Basic Interpreter Usage =====
 So how do you start to work with this language, as in how do you write code? Well you have 2 choices, but first follow the guide [[crules|Getting Crules]] to install the interpreter and get your computer all setup once this is complete you should have a working install of the language. Lets get rocking.. firstly put on some iron maiden and get your shell up!
-==== Interactive Session ====
 To run crules as an interactive session simply:
@@ Line 16: / Line 14: @@
 % crules --help
 % crules --version
 # interactive session just do:
 % crules
+# or run on the main source file:
+% crules source-code.crl
 </code>
-==== Source Code Files ====
+Done the interpreter usage is simple, its your code you run in it is the usage.
-Simply open up your favourite text-editor mine is emacs since i am an old man. In crules/tools/crules.el, contains a very basic generic emacs mode for crules. Simply compile and load it then M-X 'crules-mode' will give you a decent syntax highlighted mode to write crules code. Example:
+===== Language Tutorial =====
-<code python>
+So lets begin with a straight in approach to the language, if your using this i will assume you at least have some good programming experience be it Python or C or Perl. Since the core features and semantics will work very similar to a mix of these languages!
-# example_a.crl
-print "HelloWorld!\n";
-list = [ 1,2,3,4,5 ];
-print list;
-defun mult( x, y, z ) {
-  z = x * y;
-}
-retval = 0;
-mult( 7, 3, retval );
-print "retval = ",retval,"!\n";
-</code>
-This is just some random procedure i just made up, to run this do (dont worry about the './src' its just where the binary is created when in the dev dir):
-<code>
-./src/crules example_a.crl
-</code>
-Ok lets get into the language and give it a test drive!
-===== The Language =====
 ==== Hello World ====
@@ Line 57: / Line 31: @@
 <code python>
->>> print "Hello World!\n";
+% crules
+>>> print( "Hello World!\n" );
 Hello World!
 </code>
-Whao, that was complicated and mostly not very helpful to learn the language. So that let us print messages to the screen. Note '\n' for new line '\t' for tab programmers familiar with other languages should know this. Another note print is a keyword but it is a __builtin__ ergo you can __builtin__.print("Hello World!\n");
+Whao, that was complicated and mostly not very helpful to learn the language. So that let us print messages to the screen. Note '\n' for new line '\t' for tab, programmers familiar with other languages should know this. Note print is a function not a keyword like many other dynamic languages but more importantly its actually an internal alias call to the static object:
+<code python>
+Stdio.print( "Hello World!\n" );
+</code>
+But take note this is strictly due to the implementation, and isn't part of the language specification, I believe it is important with respect to common sense there must be a clear separation between language extension/implementation and language specification to limit undefined or unexpected side-effects.
 ==== Expressions ====
-Lets make sure our heads are screwed on and lets check out some math to learn this language properly:
+The centre point in programming from the beginning of modern programming languages, has been Mathematics! Simply as a way for dynamic valued calculations on dynamically processed information. So lets make sure crules works right and do some simple math:
 <code>
 >>> 1 + 1;
->>> 2 * 3;
+>>> 2 * 3 + 1 - ( 3 / 2 );
+.500000
 </code>
-If you are already familiar with programming languages you'll know how to write long expressions and you can do the same in crules example:
+So if your familiar with other imperative procedural languages you get the idea, but this isn't helpful since this is hard coded data and I though the point was for languages to be dynamic so we need to introduce variables and the dynamic typing system!
-<code>
+==== Variables and Dynamic Typing ====
->>> ( 2 + 4 ) / 4;
-...
-</code>
-So we can do a little bit of computing some numbers like a calculator, don't worry I am just trying to be formal to show the language properly, before i get into more interesting features.
-==== Variables ====
+If you have worked with languages such as Perl or Python you have worked with a dynamic typing system, this is when variables are not typed statically typed similar to languages like C where you have to specifically set the type of a variable before assigning it and in all contexts where this variable is valid manipulation must result of the same type with the exception of some type casting.
-Now lets do some assignments and work with variables to show what i mean by a dynamic typing system:
+Dynamic typing gives the ability to simply use an identifier to address any valid primitive in the language, and every context which is valid for this symbol can be assigned to any other symbol or user defined object. Primitives will be listed and described after a quick example:
 <code python>
->>> integer = 5;
+>>> x = 3;
->>> integer;
+>>> x = 3 / 2 ;
->>> list = [ 1,2,3,4,5 ];
->>> list = [ list , 9 ];
->>> list;
-[ [  1,  2,  3,  4,  5 ] ,  9 ]
->>> list = integer;
->>> list;
->>> expr = ( 2 + 4 ) / 4;
->>> expr;
 .500000
+>>> x = true;
+True
+>>> x = false;
+False
+>>> x = 'c';
+'c'
+>>> x = "some string";
+"some string"
+>>> x = [ 1,2,3,4 ];
+[ 1, 2, 3, 4 ]
+>>> x = [ x, 2+3, ];
+[ [ 1, 2, 3, 4 ], 5 ]
+>>> x = y = z = true;
+True
 </code>
-So you can see if we apply the '=' operator we can keep the data for future reference when in context
+This was just a quick overview of some of the primitives within the language and this little table shows them and their respective valid lexical descriptions support for such things as Hex Digits will be added soon...
-The ''<something>'' can be anything from 'c' (char), "string" (string), 559284 (integer), 2.346542 (float), true/false (boolean), variable_b (variable), expression (expression eval return), etc so you get the idea if you are familiar with python.
+^ Primitive Type ^ Lexical Token                  ^
+| Integer        | (0-9)+                         |
-It is also important to understand the 'nil' symbol which can initialize a variable within its context so you know the scope example:
+| Decimal        | {Integer}"."{Integer}          |
+| Character      | '(a-zA_Z0-9_)'                 |
-<code python>
+| String         | &quot;(a-zA-Z_)(a-zA_Z0-9_)*"       |
-x = nil;
+| Boolean        | (true-false)                   |
+| Nil            | (nil)                          |
-if( x ) {
-  ...
-}
-else {
-  x= 5;
-}
-print x;
-</code>
-That isn't really a good example to show what i mean but i trust most of you have dealt with NULL/null/None types! You can also initilize a variable to a nil list which is helpful so you can have a list and already start accessing member functions with it!
-&lt;code python>
-list = [ ];
-if( list ) {
- ..
-}
-else {
-  list.append( 2 );
-}
-print list,"!\n";
-</code>
-==== Lists - Strings ====
-Lists and Strings are implemented in two very different ways, my original idea was to work like Haskell and simply have strings as lists which is a nice idea theoretically but potentially tan awful thing to do. Due to the fact you will end up having to use a lot of memory for the code to manage the list!
-But never the less the api on the 2 objects is very similar and you can use them in very different ways lets look at lists first.
-<code python>
-list = [ 1,2,3,4 ];
-print list,"\n";
-list = [ list , "some string!" ];
-print list,"\n";
-x = list[ 0 ];
-print x,"\n";
-</code>
-So notice we can have lists inside lists and access lists just like it was an array in C! This is simply a call to the member function ' list.index( Int ) '
 ==== Functions ====
-Functions is where a programmer should spend most of his time even if it is a fully functional language, but its the core on how stuff works even if your using a fully object orientated language you need to write your constructor functions and member functions.
+Functions is where a programmer should spend most of his time even if it isn't a fully functional language, but its the core on how stuff works even if your using a fully object orientated language you need to write your constructor functions and member functions.
-For this we have created many different ways of defining functions each with very different side effects or none lets take a look at a basic function and its respective call:
+For this I have created many different ways of defining functions each with very different side effects or none lets take a look at a basic function and its respective call:
 <code python>
 defun print_something( x ) {
-    print x;
+    print( x );
 }
@@ Line 174: / Line 112: @@
 <code python>
-defun multiply( x,y,z ) {
+defun multiply( x,y ) {
-  z= x*y;
+  return ( x*y );
-  return z;
 }
-z = -1;
+print( "x= <", (x=multiply( 3,4 )) ,">!\n" );
-x= multiply( 3,4,z );
-print "x= <",x,"> z= <",z,">!\n";
 </code>
-Something i want people to notice is that since we assigned parameter 'z' the toplevel context variable 'z' we have actually changed the symbol, many modern dynamic languages don't allow this due to the fact they use environment contexts for each function call. I prefer having total control and hope programmers don't do silly things with the interpreter!
+So ok now i think you see more correctly how parameters can be passed here you pass expressions which are evaluated on argument dispatch. Ok next I address a big problem with dynamic typing is allowing some static typing. It occurs in every big dynamically typed language API's want arguments to functions to be of certain types like Integers or Strings or some other user defined object.
-Things are no where near finished with functions lets take the example:
+So for example things like this can happen quite often:
 <code python>
-defun functor( ... ) {
+defun random_function( x,y ) {
-  args= $$;
+    x.some_member_function( y );
-  print args, "!\n";
+    return ( x+1 );
 }
 </code>
-People familiar with perl will understand this and this:
+So ok do you know what will happen here because I sure don't because a dynamic type system allows anything to be anything we have no assurances that when entering a function were dealing with a symbol of a specific type which is why you see people getting frustrated quite often when they passed a slightly wrong type as the wrong parameter.
-<code python>
+In Crules you can do something like this:
-defun functor {
-  args= $$;
-  print args, "!\n";
-}
-</code>
-Note these are exactly the same function simply the parameters are varadic, you access arguments (if any) via the '$$' key-value, which is a list you can manipulate. You can mix this example:
 <code python>
-defun functor( x,y, ... ) {
+defun do_something( Int x, Int y, List z ) {
-  __args= $$;
+  z.append( x+y );
-  for i in args {
+  return True;
-    print i;
-  }
-  ......
 }
 </code>
-Lets take a closer look at handling parameters its nice we can have a dynamic type system so we can literally pass anything as an argument, but sometimes we want to be more forceful and explicitly say what the arguments should be as a pre-condition!
+So from this you know exactly what is going on you know x and y will be integers which can be added and z will be a mutable list which your appending do if we didnt have that typing the function would just have to hope the correct types would have been passed, this is not enforced in crules you can do as before and go as untyped example:
 <code python>
-defun functor( Int x, Float y, String z ) {
+defun foo( x,y,z ) ....
-  zz= x+y;
-  print z,zz,"!\n";
-}
 </code>
-So we know that z could be some kind of message etc its a random functions just to show the idea, it gets more interesting when passing data-structures, we can have them work more like static arrays example:
+The interesting thing about this is it has the effect or becoming this function signature:
 <code python>
-defun max( Int [x] ) {
+defun foo( Object x, Object y, Object z ) ...
-  m= x[0];
-  for i in x {
-    if( i >= m ) {
-      m = i;
-    }
-  }
-  return m;
-}
 </code>
-So you get the idea these are nice features but really they are the same idea: I will show some of the function work i am currently working towards but be warned these semantics are by no-means stable nor are they implemented because of this!
+Since everything in crules is an object because it is an object orientated language you can pass in anything this is what goes on behind the scenes.
-<code python>
+Builtin primitive types are:
-# simple linear velocity :-)
-f := u + (a * t);
-x = f( u=2, a=2.5, t=3 );
-</code>
-These are runtime function definitions similar to Python lambda forms, and resemble simple algebraic substitutions which will be a nice way of defining functions, any parameter/variable you don't assign with in the given expression shall be left alone and will be a valid procedure if and only if the symbols un-touched are visible in the running context! Due to the nature of the semantics this is limited to one expression.
+^ Primitive Type ^ Typing    ^
+| Integer        | Int       |
-==== Loops ====
+| Decimal        | Float     |
+| Character      | Char      |
-Where would an imperative language be without loops! In crules i only implement 2 looping methods 'for' and 'while', since every loop can be implemented as a while loop for loops work like python using iterators.
+| String         | String    |
+| Boolean        | Bool      |
-<code python>
+| List           | List      |
-list = { 1,2,3,4,5 };
-for i in list {
-  print i,"\n";
-}
-</code>
-Now for a while example:
-<code python>
-quit= false; i= 0;
-while( quit != true ) {
-  if( i == 5 ) {
-    quit = true;
-  }
-  else { i++; }
-}
-</code>
-Thats enough on loops i assume most of you are programmers looking at this, i will need more help building nicer documentation in the future!
-==== Conditional Blocks (if-statements) ====
-I have to admit i really love lolcats! :D So here is a little conditional!
-<code python>
-icanhascheezburger = true;
-if( icanhascheezburger ) {
-  print "Yes can haz cheeze burger! :-)";
-}
-else {
-  print "No can haz cheeze burger! :'(";
-}
-</code>
-Lets do a more exciting example some random string matcher:
-<code python>
-from sys.crl import sys.readline;
-PASSWORD="icanhascheezburger";
-prompt = ">>> ";
-input = sys.readline( prompt );
-while ( input != PASSWORD ) {
-  print "Password Incorrect! Try again...";
-  input = readline( prompt );
-}
-</code>
-Yeah i know thats a terrible password handler but i just want to show how you can compare strings.
-==== Object Orientation ====
-Object Orientation is very important, and really has become the most prefered paradigm to program in, simply due to the fact building very clear/clean API's is very easy and easy to do well! Java has very good features in this area, and in crules i want to try and take some influence from this but remembering that this is a dynamic language some ideas many change lets take a look at basic Objects:
-<code python>
-class myclass {
-  defun myclass( ) {
-  }
-}
-</code>
-.. this area needs more work other featues are more important to me at the moment...
-==== Lazy Evaluation and The Where Clause ====
-This still needs a lot of work but i will give you some idea of what i mean here:
-<code python>
-defex max( Int [x] ) := j where { j=0; each i in x -> (j>=i) };
-# or:
-defex even( Int [x] ) := j where { each i in x -> even( i ) };
-</code>
-Beware this syntax needs alot of work still, and it also resembles haskell list comprehension.
+You can of course create your own objects and those object types can become parameter types if wanted also.
-==== Rules and Dependencies ====
+=== Coming Soon more documentation ===
-The funny thing in this section Rules was meant to be the focus of crules but I've found so many other parts of language design intrigue'd me much much more so this hasn't been worked on for some time! And unlikely to be worked on until Object Orientation is finalized for 1.0 when we have method overrides implemented to better understand how this can work.
+More documentation coming asap its being re-written