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} % 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}
  \subsection{References}
  \subsection{Dynamic Memory Allocation} 

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

\section{Classes}
  \subsection{Constructors}
  \subsection{Operator Overloading}
  \subsection{Inheritance}
%----------------------------------------------------------------------------------------
%	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}