%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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: float = 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{Inheritance}
    Inheritance is one of the keys of Object Oriented Progamming.  It allows you
  to have related classes be derived from a base class.  The classic example is
  having a dog and a cat class inherit from an animal class.  The animal class
  is the base class, while the dog and cat are derived classes.  \\ 
    Derived classes have the same members and functions as the base class, but can 
  also overload them with implementations specific to the derived class.  For 
  instance, the animal class may have a run function, that returns some standard 
  speed for an animal.  The derived classes would overload that run function, 
  and return their specific speed. Dog and cat can be passed to functions that 
  take in the animal class, and this is something called polymorphism.  
  Kraken's inheritance is taken in part from the Java style of inheritance.
  All base class objects inherit from the Object class.  The derived classes
  only need to inherit from the base class.
  \begin{lstlisting}[language=C++]
    //brief class for clarity 
    obj Animal(Object){
      var speed: int;

      //returns the standard speed
      fun run(): int;
    }

    obj Dog(Animal){
      //returns the speed specific to dog
      fun run(): int;
    }

    obj Cat(Animal){
      //returns the speed specific to cat
      fun run(): int;
    }

    fun OutrunBear(me: Animal, you:Animal): bool{
      var BearSpeed = 10;
      if(me.run() > you.run())
      {
        //I don't have to outrun the bear
        //I just have to outrun you
        return true;
      } else if(me.run() > BearSpeed){
        //Months at the gym paid off 
        return true;
      }else{
        //New Year's Resolution.
        //Going to hit the gym.
        return false;
      }
    }
  \end{lstlisting}
%----------------------------------------------------------------------------------------
%	SECTION Templates
%----------------------------------------------------------------------------------------

\section{Templates}
  Section T
%----------------------------------------------------------------------------------------
%	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}