kraken/doc/Manual.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Kraken Documentation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%----------------------------------------------------------------------------------------
%	PACKAGES AND DOCUMENT CONFIGURATIONS
%----------------------------------------------------------------------------------------

\documentclass{article}

\usepackage{graphicx} % Required for the inclusion of images
\usepackage{amsmath} % Required for some math elements 
\renewcommand{\labelenumi}{\alph{enumi}.} % Make numbering in the enumerate environment by letter rather than number (e.g. section 6)

\usepackage{times} 
\usepackage{listings}
\usepackage{color}
%----------------------------------------------------------------------------------------
%	DOCUMENT INFORMATION
%----------------------------------------------------------------------------------------

\title{Kraken Programming Guide v0.0} % Title

\author{Jack \textsc{Sparrow}} % Author name

\date{\today} % Date for the report

\begin{document}

\maketitle % Insert the title, author and date

%----------------------------------------------------------------------------------------
%       SECTION Compiling
%----------------------------------------------------------------------------------------
\section{Compiling}
  Kraken compilation currently only supports building the compiler from source.
You can clone the repository from a terminal using:
  \begin{lstlisting}
    git clone https://github.com/Limvot/kraken.git
  \end{lstlisting}
Once you have the repository, run the following commands:
  \begin{lstlisting}
    mkdir build %Create a build directory
    cd build
    cmake ..    %Requires cmake to build the compiler
    make        %Create the compiler executable
  \end{lstlisting}
This will create a kraken executable, which is how we will call the compiler.
Kraken supports several ways of invoking the compiler.  These include:
  \begin{lstlisting}
    kraken source.krak
    kraken source.krak outputExe
    kraken grammarFile.kgm source.krak outputExe
  \end{lstlisting}
The grammar file is a file specific to the compiler, and should be included
in the github repository.  When you run the compile command, a new directory
with the name of the outputExe you specified will be created.  In this directory
is a shell script, which will compile the created C file into a binary executable.
This binary exectuable can then be run as a normal C executable.

%----------------------------------------------------------------------------------------
%	SECTION Variables
%----------------------------------------------------------------------------------------

\section{Variables}
\label{sec:var}
  Kraken has automatic type deduction.  This is sort of like the duck typing of
Python.  The difference is that variables cannot change types.  In this way, it
is much more like an implicit "auto" keyword in C++.  Unlike C++, semicolons are
optional after declarations.

\subsection{Variable Declaration}
  \begin{lstlisting}[language=C++]
    var A: int;         //A is unitialized int
    var B = 1;          //B is integer
    var C = 2.0;        //C is double
    var D: double = 3.14 //D is double

  \end{lstlisting}
\subsection{Primitive Types}
  The primitive types found in kraken are:
    \begin{enumerate}
      \item int
      \item float
      \item double
      \item char
      \item bool
      \item void
    \end{enumerate}

%----------------------------------------------------------------------------------------
%	SECTION 2: Functions
%----------------------------------------------------------------------------------------
\section{Functions}
   \begin{lstlisting}[language=C++]
    fun FunctionName(arg1 : arg1_type, arg2 : arg2_type) : returnType {
      var result = arg1 + arg2;
      return result;
    }
  \end{lstlisting}

    Functions are declared using the {\bf{fun}} keyword.  If you pass in 
  variables as shown, there will be passed by value, not by reference.  
  Therefore if you pass a variable in, it will not be modified outside the
  function.
%----------------------------------------------------------------------------------------
%       SECTION I/O
%----------------------------------------------------------------------------------------
\section{Input and Output}
    In order to print to a terminal or file, the {\bf{io}} library must be
  imported.  There are a few different functions you can use to print to the
  terminal. 
    The print() function will print out to the terminal without a newline
  character.  Like java, there is a println() function that will print whatever
  you pass in, as well as a newline.  There are also functions that can print
  colors in a unix terminal.  The color will continue when you print until
  you call the function Reset().
  \begin{enumerate}
    \item {\color{red}{BoldRed()}}
    \item {\color{green}{BoldGreen()}}
    \item {\color{yellow}{BoldYellow()}}
    \item {\color{blue}{BoldBlue()}}
    \item {\color{magenta}{BoldMagneta()}}
    \item {\color{cyan}{BoldCyan()}}
  \end{enumerate}

  \begin{lstlisting}[language=C++]
    io::print(3.2); //print without a newline character
    io::println(varA); //print variable A with a newline character
    io::BoldRed();
    io::println("This line is printed Red");
    io::Reset();
    io::println("This line is printed black");
  \end{lstlisting}
  
    You can also use kraken to read and write to files.  The functions are as
  follows:
  \begin{lstlisting}[language=C++]
    //returns true if file exists
    var ifExists = io::file_exists("/usr/bin/clang"); 

    //read file into string
    var fileString =  io::read_file("~/Documents/file.txt");     
    
    //write a string to the file
    io::write_file("/",SteamString);     
    
    //read file into vector of chars
    var charVec = io::read_file_binary("~/Documents/file2.txt");     
    
    //write a vector of chars to a file
    io::write_file_binary("/",md5checkSum);   
  \end{lstlisting}

%----------------------------------------------------------------------------------------
%       SECTION Memory Management
%----------------------------------------------------------------------------------------
\section{Memory Management}
  \subsection{Pointers}
    Pointers in kraken work like they do in C.  The notation is the 
    {\bf{*}} symbol.  This is a dereference operator.  This means that it
    operates on a pointer, and gives the variable pointed to.  For 
    instance:
    \begin{lstlisting}[language=C++]
      var B: *int = 4;  //B is a pointer to an integer 4
      *B = 3;         //B is now equal to 3
      print(B);       //would print an address, like "0xFFA3"
    \end{lstlisting}
  \subsection{References}
    References are a way to create "automatic" pointers.  If a function
  takes in a reference, the variable is passed by reference, instead of by
  value.  This means that no copy of the variable is made, and any changes
  made to the variable in the function will remain after the end of the
  function.  References also allow left-handed assignment.  This means that
  an array indexed on the left hand of an equal sign can have its value
  changed.
    \begin{lstlisting}[language=C++]
      fun RefFunction(arg1: ref int): ref int{
        return arg1 + 1;
      }
      
      var a = 6;
      var b = RefFunction(a);
      println(a); //a is now equal to 6
      println(b); //b is now equal to 6
      RefFunction(b) = 15; 
      println(b); //b is now equal to 15
    \end{lstlisting}
  
  \subsection{Dynamic Memory Allocation} 
    In order to allocate memory on the heap instead of the stack, dynamic
  memory allocation must be used.  The data must be explicitly allocated with
  the {\bf{new}} keyword, and deleted with the {\bf{delete}} keyword.  The
  size in both instances must be provided.
    \begin{lstlisting}[language=C++]
      var data = new<int>(8); //Allocate 8 integers on the heap
      delete(data,8);         //Free the memory when its no longer used.
    \end{lstlisting}

%----------------------------------------------------------------------------------------
%	SECTION Classes
%----------------------------------------------------------------------------------------

\section{Classes}
  \subsection{Constructors}
    As with most of kraken, classes are based on their C++ counterparts, with
  a few key differences.  Constructors in kraken are not called by default.  
  You must actually call the constructor function.  The constructor must return
  a pointer to the object, which is denoted by the {\bf{this}} keyword.  
  The destructor is automatically called when the object goes out of scope, 
  and is just called destruct().  An example class is shown below:
  \begin{lstlisting}[language=C++]
    obj MyObject (Object) {
      var variable1: int;
      var variable2: vector::vector<double>;

      fun construct(): *MyObject {
        variable1 = 42;
        variable2.construct();
        return this;
      }
      
      //Could also pass by reference???
      fun copy_construct(old: *MyObject): void {
        variable1 = &old->variable1;
        variable2.copy_construct(&old->variable2); 
      }
      
      fun destruct() {
        variable2.destruct();
      }
    }
  \end{lstlisting}
  \subsection{Operator Overloading}
    Operator overloading allows you to use operators for syntactic sugar, and
  make your code look nicer.  This again borrow mostly from C++, and you can
  overload most of the operators that you can in C++.  An example is shown
  below:
  \begin{lstlisting}
    //Inside a class
    
    //overload the assignment operator 
    fun operator=(other: SampleObject): void{
      destruct();
      copy_construct(&other);
    }
    
    //overload the equality operator
    fun operator==(other: SampleObject): bool{
      return EqualTest == other.EqualTest;
    }
  \end{lstlisting}
  \subsection{Traits}
    Currently, Kraken has no notion of inheritance.  Instead, objects can be
  intialized with traits.  These give special properties to the object.  For
  instance, if the object is defined with the {\bf{Object}} trait, then its
  destructor will be called when the object goes out of scope.  The second trait
  that kraken has is the {\bf{Serializable}} trait.  This allows it to be used
  with the {\bf{serialize}} class, which serializes it into a vector of bytes.
  This stream of bytes could then be used to send messages over TCP, etc.
  \begin{lstlisting} 
    //Object has both Object and Serializable traits
    obj Hermes (Object, Serializable) {
      var RedBull: vector::vector<string>; 
      
      fun construct(): *Hermes {
        RedBull = "gives you wings";
      }
      
      fun serialize(): vector::vector<char> {
        //String already has a serialize member function 
        var toReturn = RedBull.serialize(); 
        return toReturn;
      }

      fun unserialize(it: ref vector::vector<char>, pos: int): int {
        pos = RedBull.unserialize(it,pos);
        return pos;
      }
      
      fun destruct(): void {
        io::println("I must return to my people");
      }

  \end{lstlisting}
%----------------------------------------------------------------------------------------
%	SECTION Templates
%----------------------------------------------------------------------------------------

\section{Templates}
  Templates are a very important part of C++, but are also one of the reasons
people do not like the language.  They are extremely useful, but also fairly
hard to use properly.  If you make an error while using templates, the bug is
often extremely difficult to find.  Kraken templates aim to prevent that problem.
\\
Templates are a way of writing something once for any type.  At compile time,
the compiler will see what types you are using with the template, and substitute
those types in.  This is not duck typing, since the types cannot change once they
are assigned.  It is more like how you can initialize variables in kraken, with
the use of {\bf{var}}.  This is extremely useful for something like a container.
The vector class in kraken uses templates, so you can put any type, including
custom objects, into a vector. \\
The convention is to use {\bf{T}} for a template, and if there are two,
{\bf{U}}.  The following example, taken from the vector implementation,
demonstrates templates.
\begin{lstlisting}[language=C++]
  //Can have a vector of any type, with <T> 
  obj vector<T> (Object, Serializable) {
    //data can be an array of any type
    var data: *T;
    //size and available are just primitive ints
    var size: int;
    var available: int;
    ...
  }
\end{lstlisting}


%----------------------------------------------------------------------------------------
%	SECTION Standard Library
%----------------------------------------------------------------------------------------

\section{Standard Library}
  \subsection{Import Statements}
  \subsection{Vector}
  \subsection{String}
  \subsection{Regex}
  \subsection{Util}
  \subsection{Data Structures}
    \subsubsection{Stack}
    \subsubsection{Queue}
    \subsubsection{Set}
    \subsubsection{Map}
%----------------------------------------------------------------------------------------
%       SECTION Understanding Kraken Errors
%----------------------------------------------------------------------------------------
\section{Understanding Kraken Errors}
  Section error
%----------------------------------------------------------------------------------------
%	SECTION C Passthrough
%----------------------------------------------------------------------------------------
\section{C Passthrough}

\end{document}