Free Text Language

freetext.ft

Section License
===============

This code is in the public domain.

Section Header

  This is the name of the compilation unit.
  
  - name := "freetext";

Section About

  The line of equals below the section is optional. A section is identified by the keyword Section at the beginning of the line (no indentation). A section must be at the beginning of the file or preceeded by an empty line. The following line must be either empty or match `^=+$` followed by an empty line. The text after the "Section" keyword is free text, except for "Section Header" that is specific.

  Free text is allowed anywhere in the code. Free text starts by a letter.
  
  Code is intruduced using a slot operator (+ or -) like Lisaac followed by a slot definition. Code must not be indented below free text (in which case it is considered free text by itself).

Section Code

  Here is a function:
  
  The function is exported and will execute for initialization ("Exported and "Main").
  The function name is introduced using the dot
  
  - Exported Main .main <-
  (
    I am using the " character to introduce free text.
    This is my hello world:
    
    .println "Hello World";
    $Exit(-1 + 1) ;
    
    Here no code will be executed, ever.
    I switched to free text using the "." which denotes the end of the code.
  );
  
  
  This is my exit function:
  
  The function name is introduced by the dot as usual
  The argument code is an argument because it is separated by a whitespace
  The type of the argument isn't known yet until it is declared after.
  
  - Exported .exit .code <-
    The code is an integer denoting the return status of the program.
    0 means that it is successful
    + .code :int
  (
    Here I am executing a builtin:
    
    $Exit(.code);
    
    Now, no code will ever run past the $Exit.
  );
  
  - Private Operator: .a + .b : .c <-
    + .a, .b, .c :int;
  (
    Because this is the last line of code, and there is no ";", its result will be assigned to c (the result argument)
    
    $Add(.a, .b)
  );
  
  Here we define the unary operator '-'.
  The code isn't in a block ( '(' ... ')' ), this isn't necessary. Not putting code in a clock is equivalent to writing the code in a block without the final semicolon.
  
  - Private Operator: -.a : .b <-
    + .a, .b :int;
    $OneComplement(.a);
  
  This is equivalent to:
    
    - Private Operator: -.a : .b <-
      + .a, .b :int;
      ( .b = $OneComplement(); );
    
    (this is not interpreted because it is indented below free text)

Section Types

  We used types (int) but haven't declared them yet. Types are introduced using ":" contrary to functions that start with ".":
  
  - Type :int <- $Bits(32);
  
  We can define an interface as well:
  
  - Interface :tree <- (
    Here, we can define the functions that the type must implement:
    
    - .leaves : .result <- + result :slice(:leave);
    
    We should find a way to express that in a more compact form. For example:
    
        - .leaves : .result :slice(:leave);
  );
  
  - Implementation .boolean_tree .bool :bool : _ :tree <-
  (
    - .leaves : .result <-
    (
      This is a null pointer (empty slice):
      $Binary(0)
    );
  );
  
  - Type :slice(:item_type) <-
  $UnboundedPointer(:item_type);

Section Summary

  In a section, code is introduced by "-". Free text is anything else.
  
  "-" let you define a slot. A slot start with keywords (generally) followed by the signature of the item:
  
  * if the signature starts with ".", it is a function
  * if the signature starts with ":", it is a type
  
  The slot continues with "<-" followed by the slot definition, followed by ";"
  
  The slot definition can define types usid in functions. The variables starts with "+", followed by the variable name(s) and the type. It ends with ";".
  
  The slot definition can also contain free text
  
  The a list of a slot definition, code is introduced by :
  
  * "(" to start a list
  * "+" to declare a local variable
  * "." to use a variable in scope (global function, local variable)
  * "$" to use a builtin
  * The rest is free text
  
  It is also possible to declare function pointers:
  
    + example_procedure (.arg1, .arg2, .argn) <-
      This is a function because it has an implementation operator "<-" as opposed to assignment ":="
      + .arg1, .arg2, .argn :int;
      No implementation, use an empty list "()"
    ();

Section Control Structures

  - Local choose_yes_no : .boolean <-
    + .boolean :boolean;
  (
    .print("(Y/n) ");
    + .char :char := .readchar;
    (.char != 'n').if {
      .println "yes";
      .true
    } else {
      .println "No";
      .false
    }
  );
  
  - Type :boolean <- $Bits(1);
  - .true :boolean := $Binary(1);
  - .false :boolean := $Binary(0);

  - Local (.boolean).if .true_block else .false_block :any <-
    + true_block, false_block :block(:any);
    + .boolean :boolean = .true;
    This was pattern matching
  (
    .true_block.value
  )
  
  - Local (.boolean).if .true_block else .false_block :any <-
    + true_block, false_block :block returning :any;
    + .boolean :boolean = .false;
  (
    .false_block.value
  )

  - Type :block (...:args) returning (...:results) <- $FunctionPointer(:args, :results);
  - Local (.block).value (....args) : (....results) <-
    + .block :block (...:args) returning (...:results);
    + ....args ...:args;
    + ....results ...:results;
  $CallFunctionPointer(.block, ....args);