\documentclass[11pt]{article}

\usepackage[margin=1in]{geometry}
%\geometry{a4paper} % Set the page size to be A4 as opposed to the default US Letter
\usepackage{textcomp}
\usepackage[usenames,dvipsnames]{color}
\usepackage{alltt}
\usepackage{courier}
\usepackage{listings}
\usepackage{amsmath}
\usepackage{float}
\restylefloat{table}
\usepackage{tikz}
\usetikzlibrary{shapes}
\usepackage{hyperref}
\hypersetup{
    colorlinks,
    citecolor=black,
    filecolor=black,
    linkcolor=blue,
    urlcolor=black
}

\linespread{1} % Line spacing
\setlength\parindent{0pt} % Uncomment to remove all indentation from paragraphs

%----------------------------------------------------------------------------------------
%   CODE INCLUSION CONFIGURATION
%----------------------------------------------------------------------------------------

\definecolor{MyDarkGreen}{rgb}{0.0,0.4,0.0} % This is the color used for comments

\lstdefinelanguage{clip} {
    alsoletter={-, +, *, /},
    morekeywords={defun,defvar,+,-,*,/,let,set,map,reduce,lambda,
    mod,pow,inverse,is-prime,next-prime,less,greater,leq,geq,eq,neq,and,or,not,
    group,merge,make-vector,transpose,
    int-of-bits,bits-of-int,string-of-bits,bits-of-string,
    zero,rand,pad,flip,flip-bit},
    morekeywords=[2]{int,string,bit},
    morekeywords=[3]{type,index-1,index-2,index-n,vector-name,
    functor,argument-1,argument-2,argument-3,argument-n,expression,functor-name,return-type,
    type-1,type-n,identifier,type,value,integer,bit-sequence,a-string,length,
    var-1,var-2,var-n,type-2,exp-1,exp-2,exp-n,exp,id-1,id-2,id-n,value-i,id-i,
    a-vector,function,integer-1,integer-2,integer-n,vector-of-bit-seq,integer-1,
    integer-2,integer-n,bit-1,bit-2,bit-n,matrix,vector-type,value-1,value-n},
    morecomment=[l]{~~},
    morecomment=[s]{~~>}{<~~},
    morestring=[b]",
    breaklines=true,
}

\lstloadlanguages{Caml, C++, clip, sh, {[gnu]make}}

\newcommand{\setocaml}{
\lstset{language=Caml,
        frame=single,
        basicstyle=\small\ttfamily,
        keywordstyle=[1]\color{Blue}\bf,
        keywordstyle=[2]\color{Purple},
        keywordstyle=[3]\underbar,
        identifierstyle=,
        commentstyle=\usefont{T1}{pcr}{m}{sl}\color{MyDarkGreen}\small,
        stringstyle=\color{Purple},
        showstringspaces=false,
        tabsize=4,
        morekeywords={},
        morekeywords=[2]{},
        morekeywords=[3]{},
        morecomment=[l][\color{Blue}]{...},
        numbers=left,
        firstnumber=1,
        numberstyle=\tiny\color{Blue},
        breaklines=true,
        stepnumber=5
}
}

\newcommand{\setsh}{
\lstset{language=sh,
        frame=single,
        basicstyle=\small\ttfamily,
        keywordstyle=[1]\color{Blue}\bf,
        keywordstyle=[2]\color{Purple},
        keywordstyle=[3]\color{Blue}\underbar,
        identifierstyle=,
        commentstyle=\usefont{T1}{pcr}{m}{sl}\color{MyDarkGreen}\small,
        stringstyle=\color{Purple},
        showstringspaces=false,
        tabsize=4,
        morekeywords={},
        morekeywords=[2]{},
        morekeywords=[3]{},
        morecomment=[l][\color{Blue}]{...},
        numbers=left,
        firstnumber=1,
        numberstyle=\tiny\color{Blue},
        breaklines=true,
        stepnumber=5
}
}

\newcommand{\setmake}{
\lstset{language={[gnu]make},
        frame=single,
        basicstyle=\small\ttfamily,
        keywordstyle=[1]\color{Blue}\bf,
        keywordstyle=[2]\color{Purple},
        keywordstyle=[3]\color{Blue}\underbar,
        identifierstyle=,
        commentstyle=\usefont{T1}{pcr}{m}{sl}\color{MyDarkGreen}\small,
        stringstyle=\color{Purple},
        showstringspaces=false,
        tabsize=4,
        morekeywords={},
        morekeywords=[2]{},
        morekeywords=[3]{},
        morecomment=[l][\color{Blue}]{...},
        numbers=left,
        firstnumber=1,
        numberstyle=\tiny\color{Blue},
        breaklines=true,
        stepnumber=5
}
}

\newcommand{\setc}{
\lstset{language=C++,
        frame=single,
        basicstyle=\small\ttfamily,
        keywordstyle=[1]\color{Blue}\bf,
        keywordstyle=[2]\color{Purple},
        keywordstyle=[3]\color{Blue}\underbar,
        identifierstyle=,
        commentstyle=\usefont{T1}{pcr}{m}{sl}\color{MyDarkGreen}\small,
        stringstyle=\color{Purple},
        showstringspaces=false,
        tabsize=4,
        morekeywords={out},
        morekeywords=[2]{},
        morekeywords=[3]{},
        morecomment=[l][\color{Blue}]{...},
        numbers=left,
        firstnumber=1,
        numberstyle=\tiny\color{Blue},
        breaklines=true,
        stepnumber=5
}
}

\newcommand{\setclip}{
\lstset{language=clip,
        frame=single,
        basicstyle=\small\ttfamily,
        keywordstyle=[1]\color{Blue}\bf,
        keywordstyle=[2]\color{Purple},
        keywordstyle=[3]\underbar,
        identifierstyle=,
        commentstyle=\usefont{T1}{pcr}{m}{sl}\color{MyDarkGreen}\small,
        stringstyle=\color{Purple},
        showstringspaces=false,
        tabsize=4,
        morekeywords={},
        morekeywords=[2]{},
        morekeywords=[3]{},
        morecomment=[l][\color{Blue}]{...},
        numbers=left,
        firstnumber=1,
        numberstyle=\tiny\color{Blue},
        breaklines=true,
        stepnumber=5
}
}

\newcommand{\codefile}[2]{
\begin{itemize}
\item[]\lstinputlisting[caption=#2,label=#1]{#1}
\end{itemize}
}

\lstnewenvironment{code}
{}
{}

\renewcommand{\c}[1]{\lstinline!#1!}

\begin{document}

\setclip

%----------------------------------------------------------------------------------------
%   TITLE PAGES
%----------------------------------------------------------------------------------------

\begin{titlepage}

\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here

\center % Center everything on the page

%\textsc{\LARGE }\\[1.5cm] % Name of your university/college
\textsc{\Large }\\[0.5cm] % Major heading such as course name
\textsc{\large }\\[0.5cm] % Minor heading such as course title

\HRule \\[0.4cm]
{ \huge \bfseries CLIP - A Crytographic Language with Irritating Parentheses}\\[0.4cm]
% Title of the document
\HRule \\[1.5cm]

\begin{minipage}{0.4\textwidth}
\begin{flushleft} \large
\emph{Author:}\\
Wei \textsc{Duan}
wd2214@columbia.edu

Yi-Hsiu \textsc{Chen}
yc2796@columbia.edu
\end{flushleft}
\end{minipage}
~
\begin{minipage}{0.4\textwidth}
\begin{flushright} \large
\emph{Instructor:} \\
Prof. Stephen A. \textsc{Edwards} % Supervisor's Name


\end{flushright}
\end{minipage}\\[4cm]

{\large \today}\\[3cm] % Date, change the \today to a set date if you want to be precise

%\includegraphics{Logo}\\[1cm] % Include a department/university logo - this will require the graphicx package

\vfill % Fill the rest of the page with whitespace

\end{titlepage}

%----------------------------------------------------------------------------------------
%	TABLE OF CONTENTS
%----------------------------------------------------------------------------------------

\tableofcontents

\newpage

%----------------------------------------------------------------------------------------
%   INTRODUCTION
%----------------------------------------------------------------------------------------

\section{Introduction}

This manual describes CLIP, which is a programming language designed specifically for cryptographers.
The purpose of CLIP is to provide users with an efficient and simple programming language to manipulate cryptographic operations, create innovative cryptographic algorithms and implement existing cryptographic protocols.
As inheriting the mathematical nature of cryptography, CLIP is designed as a functional language.
Its syntax is inspired by the classical functional language Lisp, but with more special types and operations to implement cryptographic algorithms.
Essentially, CLIP allows cryptographers to build programs with more convenience than many other popular programming languages.

There are two common and important operations in cryptography.
One is number theory related calculation, in which big numbers are especially vital due to security concerns.
Another is bits manipulation which usually occurrs in the symmetry cryptosystem. CLIP is designed to facilitate both kinds of operations. For the big number calculation, we include the GMP library of C language, which has descent performance in big number calculation and random number generation. For bits manipulation, efficiency is not the main concern in our language, instead, we emphasize on the way to effectively express algorithms. In fact, fast encryption/decryption are usually realized from hardware end.

%----------------------------------------------------------------------------------------
%   Language Tutorial
%----------------------------------------------------------------------------------------

\section{Language Tutorial}

\subsection{Installation and Usage}
For first time users of CLIP, you need to install the GMP library.
Simply executing ``gmp.sh'' in the main directory can accomplish GMP installation. The next step is to type ``make'', it will produce two executable files ``clip'' and ``clipc''.

``clip'' is used to generate the C++ files while ``clipc'' can be used to generate executable files from .clip files in directory.

Here is the Hello World program in CLIP, which is extremely simple.
\codefile{../test/algorithm/hello_world.clip}{hello\_world.clip}
The output is

\codefile{../test/algorithm/hello_world.clip}{hello\_worldi.clip}
The Hello World program consists of only one single expression.
CLIP will print out the expression in the program automatically.

\subsection{Data Declaration and Types}
To bind a value to a variable, we can use the keyword \c{defvar}.
When binding a variable, the type of the variable should be indicated explicitly.

There are three basic types in CLIP, integer, bit sequence and string.
Their keywords are \c{int}, \c{bit#} and \c{string} respectively.

Here are some examples of variable binding:
\begin{code}
defvar i:int = 314;
defvar i:int = 0xA3;
defvar i:int = 0b1011010;
defvar b:bit#7 = '0100010;
defvar b:bit#8 = 'x5B;
defvar s:string = "I am a string";
\end{code}
In CLIP, the integer has an unlimited precision, which means you can assign large numbers such as a thousand-digit integer to a variable if needed.
To represent a bit sequence, we add a single quote in front of the digit sequence to indicate it.
Notably, the above examples show that integer can also be expressed in Hexadecimal and Binary. The bit sequence can also be expressed in Hexadecimal.

\vspace{0.5cm}
There is another derived data type, vector, in CLIP. Vector is a sequence of elements of same type. \c{defvar} could also be used to bind vectors. The declaration of a vector is

 \c{type[index-1][index-2]..[index-n]}

Here are some examples of binding vector.
\begin{code}
defvar i:int[2] = {3 4};
defvar i:int[2][3] = {{1 2 3} {4 5 6}};
defvar b:bit#2[3][2] = {{'11 '10} {'11 '01} {'01 '00'}};
defvar s:string[1] = {"I am a string"};
\end{code}

Notably, the format of vector is to use curly brackets to separate elements from different dimensions. For example, \c{\{3 4\}} means that it is a vector with two integer elements. While \c{\{\{1 2 3\} \{4 5 6\}\}} is a vector, which has two vector elements \c{\{1 2 3\}} and \c{\{4 5 6\}}, and within each vector there are three integer elements.

\subsection{Functions}
The syntax of function call in CLIP is adopted from Lisp. A pair of parentheses should surround the fucntion call.
In every pair of parentheses, the first expression is an identifier bound to a function, or a function call which returns a function, such as lambda function.

Let's try some simple arithmetic function now.
\begin{code}
(+ 4 (* 2 3) (mod 11 4))
\end{code}
The result is the same with $4 + (2*3) + (11\%4)$, which is the form we are familiar with. Therefore, the output of this program is
\begin{code}
13
\end{code}

Here is an example of \c{lambda} function.
\begin{code}
((lambda <x:int> (* x x)) 5)
\end{code}
The \c{lambda} defines a function which has one integer $x$ as its parameter, and returns the square of $x$. The whole \c{lambda} expression returns a square function. The outer most parentheses apply the lambda function to integer 5, so the output should be
\begin{code}
25
\end{code}

There are plenty of built-in functions in CLIP, including arithmetic, bit sequence and vector manipulation. For the complete list and usages of them, please refer to the language reference manual in section 3.
However, three important built-in functions would be explained below.

\begin{enumerate}
\item \c{let}

Sometimes it is convenient to have a local variable, but \c{defvar} is used to bind only global variables. Hence we introduce \c{let} here.
The last argument of \c{let} function is the expression to be returned.
Remaining arguments are used for binding, so there can be as many arguments as needed in \c{let} function.

\begin{code}
(let <x:int (* 5 5)> <y:int (/ 30 5)> <z:int 3> (+ x y z))
\end{code}
The above expression will return the evaluation result of \c{(+ x y z)} where
\c{x}, \c{y}, \c{z} are defined in angle brackets.
The output of the program is
\begin{code}
34
\end{code}

\item \c{map}

The \c{map} function is of great use in terms of vectors. It takes two arguments, with the first one being a function and the second one being a vector. \c{map} applies the first argument to each individual element in the vector. The type of return value of map is always a vector, and it  depends on the type of the return value of its first argument. 

\begin{code}
(map int-of-bits {'01 '10 '11}) 
\end{code}
The above expression will apply the function \c{int-of-bits} to \c{'01}, \c{'10}, and \c{'11} respectively.
The output of the program is
\begin{code}
{1 2 3}
\end{code}
\item \c{reduce}

The \c{reduce} function also takes in two arguments, with the first one being a function and the second one being a vector. Yet, it is different from \c{map}. \c{reduce} applies the first argument to the first and second elements in the vector, get a partial result and applies the first argument to the partial result and the third element in the vector. It does so repeatedly till the last element in the vector.

\begin{code}
(reduce + {10 11 12}) 
\end{code}
The above expression will apply the function \c{+} first to \c{10} and \c{11} to get a partial result, which is \c{2}1, then apply \c{+} to the \c{21} and \c{12}.
The output of the program is
\begin{code}
33
\end{code}

\end{enumerate}

\subsection{If and Else}

\c{if} is the only control flow in CLIP. It takes in three arguments. The first argument would be evaluated, and if it is true, the second argument will be evaluated and returned, otherwise, the third argument will be evaluated and returned.

\begin{code}
(if (eq 2 3) 2 3)
\end{code}
The expression \c{(eq 2 3)} will be first evaluated. Since it is false, the third argument will be evaluated and returned, which is \c{3}.

The output of the program is
\begin{code}
3
\end{code}


\subsection{Function Definition}

To bind a function to a variable, we use the keyword \c{defun}. The returned value type of the function as well as all the input argument types should also be provided.

Here is an example of a simple function definition:

\begin{code}
defun f:int a:int =(+ a 2);
\end{code}
It means that a function named \c{f} is defined, with only one integer as the input argument. The function \c{f} takes in an integer and returns a value that is the sum of that integer and \c{2}.

\subsection{Compound Examples}
\subsubsection{GCD}
Let's start from the basic well-known algorithm greatest common divisor in number theory.

The gcd algorithm can be recursively defined.
It could be written in CLIP as follows:
\begin{code}
defun gcd:int a:int b:int=
(if (eq a b) 
    a 
    (if (greater a b) 
        (gcd (- a b) b) 
        (gcd a (- b a))));

(gcd 24 18)
(gcd 55 34)
\end{code}
The algorithm first test whether \c{a} equals \c{b}.
If it is true, returns \c{a}. Otherwise, it evaluates the third expression, which is another \c{if} statement. The sub \c{if} statement will recursively cals \c{gcd} depending on the result of evaluating \c{(greater a b)}.

The result of the program is
\begin{code}
6
1
\end{code}

\subsubsection{SHA-3}
SHA-3 is a cryptographic hash function designed by Guido Bertoni, Joan Daemen, Michaël Peeters, and Gilles Van Assche.
We use part of this algorithm to demonstrate the ability of CLIP to manipulation bit sequences.

In one round block permutation, there are five sub-routines need to be applied.
$\theta, \rho, \pi, \chi, \iota$
We will show how to implement the first four functions and explain more details of $\theta$ function

Before defining and implementing the function, we should fixiate the size of blocks.
In SHA-3, a block size is $5\times5\times2^l$.
Here, we follow the convention and set $l$ as 6, so the block size is $5\times5\times64$.

The concise formula of those functions are
\begin{enumerate}
    \item $\theta: b[i][j][k] \oplus = parity(a[0..4][j-1][k]) \oplus parity(a[0..4][j+1][k-1])$
    \item $\rho: b[i][j][k] = b[i][j][k-(t+1)(t+2)/2])$ where
    \[\begin{bmatrix}i\\j\end{bmatrix} = \begin{bmatrix}3 & 2\\1 & 0\end{bmatrix}^t
    \begin{bmatrix}0\\1\end{bmatrix}\]
    \item $\pi: b[j][2i+3j][k] = b[i][j][k]$
    \item $\chi: b[i][j][k] \oplus = \neg b[i][j+1][k] \wedge b[i][j+2][k]$
\end{enumerate}


For a input block matrix as below
\[
\begin{matrix}
&\overbrace{1010\cdots10}^\text{64 bits} & 0000\cdots11 & 0101\cdots10 & 1110\cdots11 & 0110\cdots00\\
           &0101\cdots01 &                 1001\cdots01 & 0101\cdots00 & 1111\cdots11 & 0111\cdots11\\
           &0000\cdots00 &                 1111\cdots11 & 0100\cdots01 & 0100\cdots11 & 0011\cdots11\\
           &1000\cdots11 &                 0111\cdots01 & 1001\cdots11 & 0000\cdots00 & 1101\cdots10\\
     \oplus&1111\cdots00 &                 0010\cdots10 & 0100\cdots11 & 0000\cdots00 & 1010\cdots10\\
&-----&-----&-----&-----&-----\\
           &1000\cdots00 &                 0001\cdots10 & 1001\cdots11 & 0101\cdots11 & 0011\cdots00\\
>>> 64     &0011\cdots00 &                 1000\cdots00 & 0001\cdots10 & 1001\cdots11 & 0101\cdots11\\
<<< 63     &0000\cdots00 &                 0100\cdots11 & 1010\cdots11 & 1001\cdots10 & 0100\cdots00
\end{matrix}
\]

The first row of bit sequence beneath the dash line is the xor result of first five rows.
The second row beneath the dash line is the 64 bits right-rotation result of the first row.
The last row beneath the dash line is the 63 bits left-shift result of the first row.

Finally, the return value of theta is the xor result of the last two rows to each of the five rows in input.
Below is the code of the above algorithm for theta function and other three functions.

\begin{code}
defun theta:bit#64[5][5] block:bit#64[5][5] =
    (let <col-par:bit#320 (reduce ^ (map merge block))>
        (map (lambda <row:bit#320> 
                (group (^ row (>>> col-par 64) (<<< col-par 63)) 64))
            (map merge block)));

defun rho:bit#64[5][5] block:bit#64[5][5] =
    (make-vector <bit#64[5][5]> (>>> block[@1][@2] rho-off-set[@1][@2]));

defun pi:bit#64[5][5] block:bit#64[5][5] =
    (make-vector <bit#64[5][5]> block[@2][(mod (+ (* 2 @1) (* 3 @2)) 5)] );

defun chi:bit#64[5][5] block:bit#64[5][5] =
    (make-vector <bit#64[5][5]>
        (^ block[@1][@2]
        (& block[@1][(mod (+ @2 1) 5)] block[@1][(mod (+ @2 2) 5)])));
\end{code}

The first step is to bind the variable \c{col-par} to a value, and the value corresponds to
the first row after the dash line.
In the lambda function, it rotate rightwards and leftwards of \c{col-par}, which corresponds to the last two line
in previous diagram.

The reason to use \c{(map merge block)} is we want to xor every row,
but we cannot xor them directly since it is a vector not bit sequence.
We have to merge them first.

\subsubsection{RSA}
RSA is an algorithm for public-key cryptography invented by Ron Rivest, Adi Shamir and Leonard Adleman.
Here we simply describe the algorithm without explaining what is public-key cryptosystem or the hardness of breaking it.

\begin{enumerate}
    \item Settings:

    To build the RSA cryptosystem, first we have to generate two different large prime number $p, q$.
    The larger are those prime numbers, the harder is to break the system.
    Typically, they are 1024 bits long. Then we can generate other parameter as follows.
    \begin{eqnarray*}
        n & = & p\cdot q\\
        N & = & \phi(n) = (p-1)(q-1)\\
        e & = & 65537\\
        d & = & e^{-1} \bmod{N}\\
    \end{eqnarray*}

    \item Encryption:

    Suppose the message $m$ is a number less then $n$, then the cipher text $c$ is
    \[m = c^e \bmod{n}\]

    \item Decryption:

    The decrypt algorithm is
    \[c = m^d \bmod{n}\]
\end{enumerate}
The implementation of RSA in CLIP is as follow
\codefile{../rsa.clip}{}
Since the exponential in the power calculation could be a 1024-digit number,
we cannot use the built-in pow function and module it directly.
That will cause overflow for sure even for most modern computer.
So we define the new power function, which use the divide and conquer algorithm.
Also module \c{m} after every multiplication.

For the random number generation, since there is no direct function to generate random integer or prime.
We generate random bit sequences first, convert it to an integer, then find the next prime number next to it.

Here is a possible output:
\setclip
\begin{code}
p:
107275923850495671805219157657077815844071951797036707087201253081122063110963
265836553370723793863410907146511758902260897195424790699588544829233290078582
665770266537556513900614530312921394658260422980503508424834039639556500889865
846949589582627427120263749928714157551119741594434496876891051338571452521
q:
152186273275783221706304463642636143860325089927553623249730644924286319540314
626420534952149053625141150265844108029912416151919107989849149396232955711990
089065680578016102167107967290969969125623194094950226171623871277638786832507
937681474361063057818887840021354681548439184487683206871438792047580941303
cipher text:

plain text:
42
\end{code}
Since the prime numbers are generated randomly, it's unlikely to have the repeated cipher text.
But the point is, the plain text should always be 42 after decryption.

%----------------------------------------------------------------------------------------
%   Language Manual
%----------------------------------------------------------------------------------------

\section{Language Manual}


\subsection{Lexical Convention}
CLIP has five classes of tokens: identifiers, keywords, constants, functions and other separators. Blanks, horizontal and vertical tabs, newlines and comments are ignored except as they separate tokens. Some whitespace is required to separate otherwise adjacent identifiers, keywords and constants.

\subsubsection{Comments}
As many languages, CLIP has two kinds of comment.
A single line comment begin with two consecutive tilde \c{\~\~}, and ends till the end of the line.
A multi-line comment should start with \c{\~\~\>} and end with \c{\<\~\~}.
Note that comments cannot be nested.
\subsubsection{Identifiers}
An identifier in CLIP starts with a letter and is optionally followed by letters, numbers or hyphen.
But there cannot be two consecutive hyphens in an identifier.

e.g. \c{this-is-a-valid-identifier} is a valid identifier, but \c{this-is--not} is not.

\subsubsection{Keywords}
\begin{enumerate}
\item \textbf{Binding}: The following keywords are used for binding the identifier to variables and functions respectively.

\c{defvar}, \c{defun}
\item \textbf{Flow Control}: There is only one keyword used for flow control.
Though its syntax is like function call, it works differently to normal function call.

\c{if}
\item \textbf{Types}: Each basic type, including integer, bit sequence and string, has a keyword the program uses for declarations.

\c{int}, \c{bit#}, \c{string}
\item \textbf{Built-in Functions}: The following keywords are reserved for built-in functions

\begin{itemize}
\item \c{let}, \c{set}, \c{map}, \c{reduce}, \c{lambda}
\item \c{mod}, \c{pow}, \c{inverse}, \c{is-prime}, \c{next-prime}
\item \c{zero}, \c{rand}, \c{pad}, \c{flip}, \c{flip-bit}
\item \c{less}, \c{greater}, \c{leq}, \c{geq}, \c{eq}, \c{neq}, \c{and}, \c{or}, \c{not}
\item \c{group}, \c{merge}, \c{make-vector}, \c{transpose}
\item \c{int-of-bits}, \c{bits-of-int}, \c{string-of-bits}, \c{bits-of-string}
\end{itemize}
\end{enumerate}


\subsubsection{Constant}

Inside the expression of CLIP, there can be integer, bit and string constant.
Also, the compound type -- vector, also can be expressed as constant.

\begin{enumerate}
\item \textbf{Integer}

CLIP provides three ways to express an integer constant.
\begin{enumerate}
\item Decimal: The expression of it is simply a sequence of digits.
The leading zero will be ignored automatically.
\item Binary: The expression is a sequence of \c{0} and \c{1} leading with \c{0b}.
\item Hexadecimal: The expression is a sequence of \c{0}-\c{9} and \c{A}-\c{F} leading with \c{0x}.
\end{enumerate}
\item \textbf{Bit sequence}

A bit sequence is a sequence of \c{0} and \c{1} lead by a single quote character.

e.g. \c{'01000101}

\item \textbf{String}

A string constant is as in C, surrounded by the double quotes.

\item \textbf{Vector}

The only compound type in CLIP is called vector.
To express a vector constant, use the curly bracket to enclose a sequence of objects.
Each object is separated by at least one space.
The vector can be nested to form a higher dimension vector.

\c{\{\{1 2 3\} \{5 7 9\}\}}

\item \textbf{Other punctuations}

There are 4 other punctuations used in CLIP and serve as different purpose
\begin{enumerate}
\item \c{;}: The semicolon is used to end the binding.
After binding variables or function, there should be a semicolon.
For an outer most expression, if there is a semicolon after it, then the expression will only be executed but not printed out its evaluation.
\item \c{[]}: The square bracket is used for expressing a vector type or accessing a vector element.
For example, \c{int[5][8][4]} means the type of 5 by 8 by 4 integer vector, and \c{a[3]} means fetching the third element from vector \c{a}
\item \c{()}: As in lisp, the parentheses are used in function call. The first expression appear in it is a functor.
\item \c{<>}: The angle bracket are reserved for special purpose.
The only place it appears is in the functions \c{let}, \c{lambda} and \c{make-vector}.
\end{enumerate}

\end{enumerate}

\subsection{Type}
\subsubsection{Basic Data Types}
In CLIP, there are three non-function basic data types
\begin{itemize}
    \item \c{int}: An integer with unlimited precision.
    \item \c{bit\#n}: A bit sequence consist of n bits.
    \item \c{string}: A series of characters. 
\end{itemize}
To access those type, simply use the identifiers which is binded to the values.

Also note that, specially, the type \c{bit#1} is also used as boolean value, which is the return type of logic functions such as \c{and}, \c{or}. \c{'0} means false and \c{'1} means true.
\subsubsection{Derived Data Type}
The only derived data type is vector.
To declare a vector type, we use a sequence of bracket as

\c{type[index-1][index-2]..[index-n]}

This suggests a vector, with \c{type} being the type of elements consist of vector, and \c{index-1}
\c{[index-2]..[index-n]} being a series of positive whole numbers enclosed in square brackets, indicates the dimensionality of the vector.
The element in the vector should be in the same type.
The number of  square brackets suggests the dimension of vector.
For examples, \c{bit#2}\c{[2][3]} is a vector with two dimensions, and the elements in the vector are all 2-bit sequences. It can contain a constant like
\c{\{\{'01 '00 '10\} \{'00 '11 '10\}\}}

The following structure:

\c{vector-name[index-1][index-2]..[index-n]}

is used to access a particular element in a vector. While \c{index-1} indicates that the element is at position \c{index-1} in the first dimension, \c{index-2} indicates that the element is at position \c{index-2} in the second dimension, etc.
All index start from 0, so suppose the above vector example is bind to \c{v},
then \c{v[1][1]} returns \c{'11}
The vector access allows not only the atom element, but also a sub vector.
Namely, \c{v[1]} returns \c{\{'00 '11 '10\}}.

\subsection{Syntax}
\subsubsection{Program Structure}
A program is consist of a sequence of function binding, variable binding and expressions.
They can appear in the program in any sequence.

When execute, the variable is declared orderly, which means in the former declaration of either functions of variables, they cannot use the variables that declared after them.
But the recursion of function is valid.

Be cautious about that the same identifier cannot be binded twice.
\subsubsection{Expression}
An expression can be a constant, variable or a function evaluation.
The syntax of function call is lisp-like as follows.
\c{(functor argument-1 argument-2 .. argument-n)}
The arguments, even the functor can also be an expression.

The function is evaluated in the applicative order.
And arguments are evaluated orderly. Namely, first evaluates \c{argument-1}, then \c{argument-2}, etc.

\subsubsection{Binding Variables}
In general, when we define a non-function data type, we use the keyword \c{defvar} as following

\c{defvar identifier:type = value;}

The scope of the identifier defined by defvar begins directly after declaration and exists throughout the whole program.
Here are some examples of binding global variables to different types of values
\begin{code}
defvar n:int = 17
defvar b:bit#3 = '001
defvar s:string = "ThisIsAString"
defvar v:bit#5[2][3] = {{'00000 '01110 '11010} {'10101 '11000 '11011}}
\end{code}

\subsubsection{Binding Functions}
The form of function declaration is

\c{defun functor-name:return-type argument-1:type-1 .. argument-n:type-n =
    expression;}

The type of the expression must match with the return type.

Here is an example of calculating Fibonacci number
\begin{code}
defun Fib:int n:int =
(if (< n 1)
    1
    (+ (Fib (- n 1)) (Fib (- n 2)));
\end{code}

\subsubsection{Output}
There is no explicit output function in CLIP.
After evaluating the outer most expression, the result will be printed out in its own line automatically.
If you don't want the result be printed, then you can add semicolon after the expression.

For example, after running below code
\begin{code}
(+ 1 1)
(+ 1 2);
(+ 1 3)
\end{code}
We will get
\begin{code}
2
4
\end{code}

\subsubsection{Control Flow}
In clip, the only flow control instruction \c{if}. The syntax is

\c{(if argument-1 argument-2 argument-3)}

\c{argument-1} should be an expression which return true or false (\c{'1} or \c{'0}).
The second and the third argument should return the same types.

The syntax looks like function call.
However, the crucial difference is, after evaluating the first argument, the program will execute \c{argument-2} or \c{argument-3} depends on the result. But not executes them both, then decide to output which result.
That is an important concept, lets take the look on the recursive factorial example
\begin{code}
defun Fib:int n:int =
(if (< n 2)
    1
    (* n (Fib (- n 1))));
\end{code}
If the if statement always evaluate both \c{argument-2} and \c{argument-3}.
Then the program will never stop.
Because even \c{Fib(1)} should simply return 1, the program still tries to evaluate the last argument, which makes it stuck in the infinite loop.

\subsection{Type Conversion}
The built-in functions provide methods to convert the data between bit sequences and integers, as well as bit sequences and strings.
They are
\begin{itemize}
    \item \c{(bits-of-int integer length)}
    \item \c{(int-of-bits bit-sequence)}
    \item \c{(bits-of-string a-string length)}
    \item \c{(string-of-bits bit-sequence)}
\end{itemize}
The length parameter indicates how many bits the output should have.
If it is too long, then the function will pad zeros.
If it is too short, then the function will truncate automatically.


%% Built-in Function
\subsection{Built-in Function}
We categorize built-in functions into five categories
\begin{enumerate}
    \item Arithmetic functions: Used to handle the arithmetic of integer with unlimited precision.
    \item Logical functions: Logical related functions.
    \item Bit sequence functions: Used in manipulation of bit sequences.
    \item Vector functions: Functions operated on the vectors.
    \item Conversion functions: Convert data between types
    \item Miscellaneous clip functions: Includes \c{let}, \c{lambda}, \c{map}, \c{set}
    First three are common elements in functional language.
\end{enumerate}

\setclip
\subsubsection{Arithmetic Functions}
\begin{enumerate}
    \item\c{+} 

        \c{(+ integer-1 integer-2 .. integer-n)}

        The function \c{+} can take in integers as arguments, and returned the sum of all the arguments. \c{+} can have many arguments. 

        Example program:
        \codefile{../test/simple-function/test-add.clip}{}

        Output:
        \codefile{../test/simple-function/test-add.ref}{}
    \item\c{*}

        \c{(* integer-1 integer-2 .. integer-n)}

        The function \c{*} can take in integers as arguments, and returned the sum of all the arguments. \c{*} can have many arguments. 

        Example program:
        \codefile{../test/simple-function/test-multiply.clip}{}

        Output:
        \codefile{../test/simple-function/test-multiply.ref}{}

    \item\c{-}

        \c{(- integer-1 integer-2)}

        The function \c{-} can only take in two integers as arguments. The result of the first argument being subtracted from the second will be returned.

        Example program:
        \codefile{../test/simple-function/test-sub.clip}{}

        Output:
        \codefile{../test/simple-function/test-sub.ref}{}

    \item\c{/}

        \c{(/ integer-1 integer-2)}

        The function \c{/} can only take in two integers as arguments. The result of the first argument being divided by the second will be returned.

        Example program:
        \codefile{../test/simple-function/test-divide.clip}{}

        Output:
        \codefile{../test/simple-function/test-divide.ref}{}
    \item\c{mod}

        \c{(mod integer-1 integer-2)}

        The function \c{mod} can only take in two integers as arguments. The return value is the remainder of division of the first argument by the second one.

        Example program:
        \codefile{../test/simple-function/test-mod.clip}{}

        Output:
        \codefile{../test/simple-function/test-mod.ref}{}
    \item\c{pow}

        \c{(pow integer-1 integer-2)}

        The function \c{pow} takes in two integer arguments. The return value is the exponential of the first argument  to the second argument.

        Example program:
        \codefile{../test/simple-function/test-pow.clip}{}

        Output:
        \codefile{../test/simple-function/test-pow.ref}{}
    \item\c{inverse}
        \c{(inverse integer-1 integer-2)}

        The function \c{inverse} takes in two integer arguments. It returns a value \c{x} such that \c{integer-1 * x = 1 (mod integer-2)} 

        Example program:
        \codefile{../test/simple-function/test-inverse.clip}{}

        Output:
        \codefile{../test/simple-function/test-inverse.ref}{}

    \item\c{is-prime}

        \c{(is-prime integer)}

        The function \c{is-prime} takes in an integer as input, and return \c{'1 } if the input is a prime, or \c{'0 } otherwise.

        Example program:
        \codefile{../test/simple-function/test-is-prime.clip}{}

        Output:
        \codefile{../test/simple-function/test-is-prime.ref}{}
    \item\c{next-prime}

        \c{(next-prime integer)}

        The function \c{next-prime} takes in an integer as input, and return the nearest prime that is greater than it.

        Example program:
        \codefile{../test/simple-function/test-next-prime.clip}{}

        Output:
        \codefile{../test/simple-function/test-next-prime.ref}{}
\end{enumerate}


%% Bit Sequence Functions
\subsubsection{Bit Sequence Functions}
\begin{enumerate}
    \item \c{zero}

        \c{(zero integer)}

        The function \c{zero} takes in an integer and returns a \c{bit-sequence}, whose length is indicated by the input.

        Example program:
        \codefile{../test/simple-function/test-zero.clip}{}

        Output:
        \codefile{../test/simple-function/test-zero.ref}{}

    \item \c{rand}

        \c{(rand integer)}

        The function \c{rand} takes in an integer and returns a random \c{bit-sequence}. The length of the \c{bit-sequence} is indicated by the input.

        Example program:
        \codefile{../test/simple-function/test-rand.clip}{}

        Output:
        \codefile{../test/simple-function/test-rand.ref}{}

    \item \c{pad}

        \c{(pad bit-sequence integer)}

        The function \c{pad} takes in two arguments. The first one is a \c{bit-sequence} and the second one is an \c{integer}. \c{pad} extends the length of the first argument to be as indicated by the second argument by adding a number of \c{'0}.

        Example program:
        \codefile{../test/simple-function/test-pad.clip}{}

        Output:
        \codefile{../test/simple-function/test-pad.ref}{}

    \item \c{flip}

        \c{(flip bit-sequence)}

        The function \c{flip} converts the input \c{bit-sequence} into another \c{bit-sequence} whose leftmost bit is the same as the rightmost bit in the input, second leftmost bit is the same as the second rightmost bit in the input, etc.

        Example program:
        \codefile{../test/simple-function/test-flip.clip}{}

        Output:
        \codefile{../test/simple-function/test-flip.ref}{}


    \item \c{flip-bit}

        \c{(flip-bit bit-sequence integer)}

        The function \c{flip-bit} takes in two arguments. The first one is a \c{bit-sequence} and the second one is an \c{integer}. \c{flip-bit} converts the nth bit into its reverse, where n is indicated by the second argument.

        Example program:
        \codefile{../test/simple-function/test-flip-bit.clip}{}

        Output:
        \codefile{../test/simple-function/test-flip-bit.ref}{}

\end{enumerate}


%% Logical Functions
\subsubsection{Logical Functions}

\begin{enumerate}
    \item \c{less}

        \c{(less integer-1 integer-2)}

        It takes two integers as input argument and compares them. If the first argument is less than the second one, the return value is \c{'1}, otherwise \c{'0}.

        Example program:
        \codefile{../test/simple-function/test-less.clip}{}

        Output:
        \codefile{../test/simple-function/test-less.ref}{}

    \item \c{greater}

        \c{(greater integer-1 integer-2)}

        It takes two integers as input argument and compares them. If the first argument is greater than the second one, the return value is \c{'1}, otherwise \c{'0}.


        Example program:
        \codefile{../test/simple-function/test-greater.clip}{}

        Output:
        \codefile{../test/simple-function/test-greater.ref}{}

    \item \c{leq}

        \c{(leq integer-1 integer-2)}

        It takes two integers as input argument and compares them. If the first argument is no greater than the second one, the return value is \c{'1}, otherwise \c{'0}.

        Example program:
        \codefile{../test/simple-function/test-leq.clip}{}

        Output:
        \codefile{../test/simple-function/test-leq.ref}{}

    \item \c{geq}

        \c{(geq integer-1 integer-2)}

        It takes two integers as input argument and compares them. If the first argument is no less than the second one, the return value is \c{'1}, otherwise \c{'0}.

        Example program:
        \codefile{../test/simple-function/test-geq.clip}{}

        Output:
        \codefile{../test/simple-function/test-geq.ref}{}

    \item \c{eq}

        \c{(eq expression-1 expression-2)}

        It takes two expressions with same types as input argument and compares them.
        If the first argument is equal with the second one, the return value is \c{'1}, otherwise \c{'0}.


        Example program:
        \codefile{../test/simple-function/test-eq.clip}{}

        Output:
        \codefile{../test/simple-function/test-eq.ref}{}

    \item \c{neq}

        \c{(neq integer-1 integer-2)}

        It takes two expressions with same types as input argument and compares them.
        If the first argument is equal with the second one, the return value is \c{'0}, otherwise \c{'1}.

        Example program:
        \codefile{../test/simple-function/test-neq.clip}{}

        Output:
        \codefile{../test/simple-function/test-neq.ref}{}

    \item \c{and}

        \c{(and bit-1 bit-2 .. bit-n)}

        It do the ``and'' operation on the arbitrary number of bits.

        Example program:
        \codefile{../test/simple-function/test-and.clip}{}

        Output:
        \codefile{../test/simple-function/test-and.ref}{}

    \item \c{or}

        \c{(or bit-1 bit-2 .. bit-n)}

        It do the ``or'' operation on the arbitrary number of bits.

        Example program:
        \codefile{../test/simple-function/test-or.clip}{}

        Output:
        \codefile{../test/simple-function/test-or.ref}{}

    \item \c{not}

        \c{(not bit)}

        This function simply flips \c{bit}.

        Example program:
        \codefile{../test/simple-function/test-not.clip}{}

        Output:
        \codefile{../test/simple-function/test-not.ref}{}
    \end{enumerate}

%% Vector Functions
\subsubsection{Vector Functions}
\begin{enumerate}
    \item \c{group}

        \c{(group bit-sequence integer)}

        It slices a \c{bit-sequence} into several bit sequences and groups them into a vector,
        where the length of output bit sequence is indicated by integer. The integer should be a divider of the length of \c{bit-sequence}.

        Example program:
        \codefile{../test/simple-function/test-group.clip}{}

        Output:
        \codefile{../test/simple-function/test-group.ref}{}

    \item \c{merge}

        \c{(merge vector-of-bit-seq)}

        It is an inverse function of group, it concatenate all the bit sequences in \c{vector-of-bit-seq}
        and returns it.

        Example program:
        \codefile{../test/simple-function/test-merge.clip}{}

        Output:
        \codefile{../test/simple-function/test-merge.ref}{}

    \item \c{make-vector}

        \c{(make-vector <vector-type> expression)}

        The \c{make-vector} function creates an arbitrary dimension vector and returns it.
        The first argument \c{vector-type} indicates the return type.
        The second argument \c{expression} generally would be a function indicates the specific elements in the vector. \c{@i} suggests the i-th index of the vector.
        The return type of \c{expression} should be a basic type of \c{vector-type}.
        In sum up, suppose the \c{vector-type} is \c{int[3][5]}, then \c{@1} and \c{@2} can appear in the \c{expression} as identifier.
        For the return vector, the position \c{[i][j]} will be the value of expression insert \c{@1} as \c{i} and \c{@2} as \c{j}

        Example program:
        \codefile{../test/simple-function/test-make-vector.clip}{}

        Output:
        \codefile{../test/simple-function/test-make-vector.ref}{}

    \item \c{transpose}

        \c{(transpose matrix)}

        As suggested by the name of the function, it will transpose a matrix, which is a two dimension vector.

        Example program:
        \codefile{../test/simple-function/test-transpose.clip}{}

        Output:
        \codefile{../test/simple-function/test-transpose.ref}{}
\end{enumerate}


%% Conversion Function

\subsubsection{Conversion Functions}
\begin{enumerate}
\item \c{int-of-bits}

\c{(int-of-bits bit-sequence)}

It converts a \c{bit-sequence} into an integer in the big endian sense.
The length of \c{bit-sequence} can be arbitrary.

Example program:
\begin{code}
(int-of-bits '010011)
\end{code}

Output:
\begin{code}
19
\end{code}

\item \c{bits-of-int}

\c{(bits-of-int integer-1 integer-2)}

It converts the integer \c{integer-2} into the bit sequence, the first integer \c{integer-1}
indicates how long the return bit length is.

Example program:
\begin{code}
(bits-of-int 12 341)
(bits-of-int 13 341)
\end{code}

Output:
\begin{code}
'xAA8
'0000101010101
\end{code}

\item \c{string-of-bits}

\c{(string-of-bits bit-sequence)}

It converts \c{bit-sequence} into a string
by transforming every eight bits into a character in big endian sense.
If the bits is not a multiple of eight, then it pads 0 after it.

The length of \c{bit-sequence} can be arbitrary.

Example program:
\begin{code}
(string-of-bits '01001001)
\end{code}

Output:
\begin{code}
I
\end{code}

\item \c{bits-of-string}

\c{(bit-of-string integer a-string)}

It converts \c{string} into a bit sequence in the big endian sense.
Every character in the string will be converted into 8 bit sequence.

Example program:
\begin{code}
(bits-of-string "HI")
\end{code}

Output:
\begin{code}
'x9212
\end{code}

\end{enumerate}

%% Miscellaneous Clip Functions

\subsubsection{Miscellaneous Clip Functions}
    \begin{itemize}
        \item \c{let}

        \c{(let <id-1:type-1 value-1> .. <id-n:type-n value-n> expression)}

        \c{let} evaluates expression and binds the \c{value-i} to the \c{id-i} specified in the angle brackets.
        The return value is the evaluation of the last expression.
        It can contain the global variables and the identifiers binded in the \c{let} function.
        If the identifier is already defined as a global variable or outer \c{let} function, then it will use the one in nearest layer.
         
        Example program:
        \codefile{../test/simple-function/test-let.clip}{}

        Output:
        \codefile{../test/simple-function/test-let.ref}{}
    \item \c{lambda}

        \c{(lambda <id-1:type-1 id-2:type-2 .. id-n:type-n> expression)}

        The \c{lambda} function returns a function which can be used as an argument of another function. Same as in \c{let} function, we can use variables \c{id-1} to \c{id-n} in \c{expression}.
        If the name is conflicted with outer variable, it will mask the outer one.

        Example program:
        \codefile{../test/simple-function/test-lambda.clip}{}

        Output:
        \codefile{../test/simple-function/test-lambda.ref}{}

    \item \c{map}

        \c{(map function a-vector)}

        The \c{map} function allows you to apply a function on each element of a vector. If the vector has multiple dimensions, the \c{map} will treat the second outer most layer vector as an element and apply the \c{function} on that vector. 

        Example program:
        \codefile{../test/simple-function/test-map.clip}{}

        Output:
        \codefile{../test/simple-function/test-map.ref}{}

    \item \c{reduce}

        \c{(reduce function a-vector)}

        The \c{reduce} function also takes in a function and a vector as arguments.
        Here the function must take two argument in the same types and return the same type data. Similar to \c{map} function, the vector can be more than one dimension.
        On such cases, it only handles the outer most layer vector.
        \c{reduce} takes the first two elements from the second input argument and applies \c{function} to it.Then a partial result will be generated. The \c{function} will again apples to the partial result and the third element in the second input argument. It does so repeatedly till the end of the vector is reached. The final output of \c{function} is the output of \c{reduce} function.

        Example program:
        \codefile{../test/simple-function/test-reduce.clip}{}

        Output:
        \codefile{../test/simple-function/test-reduce.ref}{}


\end{itemize}

\subsection{Scope}
\subsubsection{Global variables}
In general, CLIP does not allow declare the variable or function in an expression,
so the scope of a variable is simple to define, usually.
Except in several special functions, \c{lambda} \c{let} \c{make-vector}.

In the function declaration, if the local variable has the same name to some global variable,
then it will mask the global variable.
Therefore the output of following example will be
\begin{code}
defvar a:int = 3;

defun f:int b:int =
    (+ a b);

(f 4)

defun g:int a:int =
    (+ a a);

(g 4)
\end{code}
\begin{code}
7
8
\end{code}

Other than function definition, there are three functions, which can has its own local variables.
\begin{enumerate}
    \item \c{(lambda <var-1:type-1 var-2:type-2 .. var-n:type-n> expression)}

    The scope of \c{var-1}, \c{var-2} ... \c{var-n} are in the \c{expression}
    \item \c{(let <var-1:type-1 exp-1> <var-2:type-2 exp-2> .. <var-n:type-n exp-n>
    exp})

    The scope of variable \c{var-1}, \c{var-2} ... \c{var-n} are also in the \c{exp}
    \item \c{(make-vector <type> expression)}

    In the \c{expression} of \c{make-vecotr}, the variable \c{@1}, \c{@2}, .. , \c{@d} has the scopes in \c{expression} where \c{d} is the dimension of \c{type}.
\end{enumerate}

\subsection{Grammar}

In the below grammar, the string with capital letters, like \c{ID}, \c{INT}, are the token given by the scanner, also the terminal symbol.
Some notation also adopts the regular expression representations.
We use square bracket to group expressions in regular expression, so \c{\\[ \\]} means the square bracket symbol itself.

\setsh
\begin{code}
program:
    [defvar | defun | expression SEMICOLON?]*

defvar:
    DEFVAR ID:type = expression SEMICOLON

defun:
    DEFUN (ID:type)+ = expression SEMICOLON 

expression:
    constant
    ID
    ID dimensions
    AT_NUM 
    (LET [<ID:type> expression]* expression)
    (LAMBDA <[ID:type]*>)
    (MAKE-VECTOR <type> expression)
    (expression+)

type: 
    sig_type
    sig_type
    const_dimensions 

sig_type:
    INT
    BITS
    STR

const_dimension_list:
    [\[constant\]]*

dimension_list:
    [\[expression\]]*

constant:
    constant_int
    onstant_bits
    STRING_LIT
    vector

vector:
    {[expression ]+}

constant_int:
    INTEGER
    0b BINARY
    0x HEX

constant_bits:
    ' BIT_BINARY
    'x BIT_HEX
\end{code}

%----------------------------------------------------------------------------------------
%   Project Plan
%----------------------------------------------------------------------------------------

\section{Project Plan}

With the relatively small number of members in our team, we employed a collaborative strategy to accomplish the project. The strategy basically involves the following components:

\begin{itemize}
\item {The use of a version control infrastructure.}

We created a git repository on Dropbox and branched it on our own directory, because in comparison with the open source environment of github, dropbox can maintain files with higher security. Hence, all source code in this project was produced on the local git repository and being pushed to dropbox and only shared with the other team member.
\item {Communicate with each other on a regular basis.}

Group meeting was held about two times a week. General problems such as module design, implementation rules and specification details would be discussed. In addition, scheduled meeting with TA was also organized every week, during which progress updates would be reported.

\item {Keep up a stable working pace}

Time is especially limited in summer terms. Therefore, we pushed ourselves to start thinking about the project from the first week. Then, progress of each week may differ, we tried to focuses all efforts on the project, and managed to accomplish a module per week.

\end{itemize} 

\subsection{Planning process}
Starting from the very beginning, we decided to design a language that could assist programming in cryptography. We spent the first week to design the features and functionality of this language, and then set up main goals for each phase. Throughout the whole project, we referred to our planned schedule and kept up proceed along with it. Meanwhile, we also retained certain flexibility so that the short-term goal may experience shifting due under some unexpected circumstances. 

\subsection{Specification process}

Initially, in the language reference manual, we specified the propoerty of CLIP being a functional language, and the features include the ability of manipulating big numbers and bits sequences. Targeting at cryptographers, we also planned to create built-in functions which support those most common cryptographic operations. We decided to borrow the syntax of LISP which can provide programmers a rather clear distinction of the scope of each function. Yet for big number calculation, we did not determine its implementation until Professor Edwards recommended us to utilize GMP, which is a very powerful c library for big number operations. Along development, some of the features claimed in the LRM may be adjusted, for example, the format of comments. Moreover, some features may be added, such as to define CLIP as a strongly-typed language and require provision of type for each function(its return value), variable(both local and global) and arguments.   
\subsection{Development process}

We planned to implement CLIP by translating it to C++, then, compiled using g++. Follow the stage of architecture, we immediately turned to the real practice and started working on scanner, then moved on to parser, then semantic check, and finally the translator. The first two stages were finished within the first half of the summer semester, since they are the fundamental basis for all other stages. We then continued to semantic check and accomplished it in the second week, but it was amended frequently later, particularly when we wrote code for translator.

\subsection{Testing process}

Testing was performed throughout the whole development process. At the beginning, when scanner and parser were completed, test cases consist of  positive and negative instances were created and examined. According to the feedback given by testing, modifications and improvements were made to give lexical part more robustness. Then, semantic check module was established. Again, we test its ability of detecting grammar errors by design a series of complex negative test cases. The result of semantic check was printed out in the format of AST parsing tree, which in the meantime tested previous scanner and parser modules as well. When tranlator modul was built up, we started to feed it with authentic CLIP code, and testing results were print out in the format of C++ language, which is our target language. In addition, regression testing strategy was adopted so that old test cases would always run whenever new features were added to ensure the reliability of our compiler as a whole.

\subsection{Programming style}
\begin{itemize}
\item
Ocaml programming:

Being new to Ocaml, we used the following reference guide below to learn the most basic grammar:
http://courses.cms.caltech.edu/cs134/cs134b/book.pdf

\item
Formatting:

We mostly follow one of the style described in Caml Programming Guideline http://caml.inria.fr/resources/doc/guides/guidelines.en.html

More specifically, we use 4 spaces as indentation and put the \c{in} of \c{let .. in} function at the end of the last line.

\item 
Documentation:

Comments was written at beginning of functions to specify its functionality.
\end{itemize}


\subsection{Project timeline}

\begin{table}[H]
\caption{Scheduled timeline}
\begin{center}
\begin{tabular}{|l|l|}
    \hline
     Date & Task to accomplish\\ \hline
     July 15th & Language proposal complete\\ \hline
     July 22nd & Language reference manual complete\\ \hline
     July 29th & Scanner and parser complete\\ \hline
     Aug 5th & Semantic check complete\\ \hline
     Aug 10th & Translator complete\\ \hline
     Aug 14th & Testing, debugging\\ \hline
     Aug 16th & Final report and presentation\\ \hline
\end{tabular}
\end{center}
\end{table}

\subsection{Responsibilities}

There is no strict division of responsibilities as we are a small team, where each member should participate in multiple parts depending on the progress of the project.
\begin{table}[H]
\caption{Work distribution}
\begin{center}
\begin{tabular}{|l|l|}
    \hline
    
    Yi-Hsiu Chen & Scanner, Parser, AST, Semantic check, C++ library, Translator\\ \hline
    Wei Duan & Scanner, AST, C++ library, Translator, Test suites\\ \hline
\end{tabular}
\end{center}
\end{table}

\subsection{Software development environment}
We had the following programming and development environment:
\begin{itemize}
\item
Programming language for building compiler : Ocaml version 4.00.1 . Ocamlyacc and Ocamllex extensions were used for compiling the scanner and parser.
\item
Development environment: We used Sublime Text 2 together with its plugins.
\end{itemize}

\subsection{Project log}
\begin{table}[H]
\caption{Project log}
\begin{center}
\begin{tabular}{|l|l|}
    \hline
     Date & Milestone\\ \hline
     July 10th & Language defined\\ \hline
     July 15th & Language proposal complete\\ \hline
     July 19th & Language features defined\\ \hline
     July 22th & Language reference manual complete\\ \hline
     July 28th & Scanner and parser complete\\ \hline
     July 31th & Test parser complete\\ \hline
     Aug 2rd & Testcases designed\\ \hline
     Aug 9th & Semantic check complete\\ \hline
     Aug 11th & Translator and built-in function library complete\\ \hline
     Aug 12th & Debugging and adjusting\\ \hline
     Aug 14th & All modules complete\\ \hline
     Aug 16th & Final report and Presentation\\ \hline
\end{tabular}
\end{center}
\end{table}




%----------------------------------------------------------------------------------------
%   Architectural Design
%----------------------------------------------------------------------------------------

\section{Architectural Design}

\subsection{The Compiler}

The architecture of CLIP compiler mainly consists of four parts: scanner, parser, semantic checker, translator (The last step merely invokes the g++ compiler).
All four parts are implemented using OCaml.
We also use ocamllex and ocamlyacc to help implementing scanner and parser respectively.

The main compiler program is clip.ml, which invoke scanner, parser, semantic checker, translator sequentially.
The first step is passing the clip source code to scanner and parser.
They will generate the AST, which defines in ast.ml and
contains the information about the structure of clip program.
In next step, we pass the AST to semantic.ml, which will check the semantic correctness. It mainly check the type consistency.
During checking the semantic, it also constructing the SAST, which contains more information than AST.
The information help the translator to generate C code easily.
The last step of the compiler is to generate compilable C code from SAST.
The above tasks are packed into a single executable file ``clip''
In order to make it more convenient to transform into executable file,
we also provide ``clipc'', which takes .clip file as input and generate executable file as output.

\begin{center}
\begin{tikzpicture}[>=stealth]

  % Position the nodes using a matrix layout
    \node [rectangle,draw,minimum width=3cm,minimum height=1cm,rounded corners=3pt,text width=2cm,align=center] (input) at (0, 3)  {input\\ .clip file};
    \node [rectangle,draw,minimum width=3cm,minimum height=1cm,rounded corners=3pt,text width=2cm,align=center] (token) at (6, 3)  {Lexical\\ token};
    \node [rectangle,draw,minimum width=3cm,minimum height=1cm,rounded corners=3pt,text width=2cm,align=center] (ast) at (12, 3)  {AST};
    \node [rectangle,draw,minimum width=3cm,minimum height=1cm,rounded corners=3pt,text width=2cm,align=center] (sast) at (12, 0)  {SAST};
    \node [rectangle,draw,minimum width=3cm,minimum height=1cm,rounded corners=3pt,text width=2cm,align=center] (cc) at (6, 0)  {.cc file};
    \node [rectangle,draw,minimum width=3cm,minimum height=1cm,rounded corners=3pt,text width=2cm,align=center] (exe) at (0, 0)  {executable file};
    \node [circle,draw,minimum width=0.5cm,minimum height=0.5cm,text width=2cm,align=center] (gmp) at (3, -3)  {GMP Library};

    \path [->] (input) edge node[above]{ocamllex}  (token)
             (token) edge node[above]{ocamlyacc}  (ast)
             (ast) edge node[left]{semantic.ml}  (sast)
             (sast) edge node[above]{translator.ml}  (cc)
             (cc) edge node[above]{g++ or clang}  (exe);
    \draw [->] (gmp) .. controls (3,0) .. (exe);
\end{tikzpicture}
\end{center}
%----------------------------------------------------------------------------------------
%   Test Plan
%----------------------------------------------------------------------------------------

\section{Test Plan}
\subsection{Testing phases}
\subsubsection{Unit testing(scanner, parser, translator)}
In this project, we built up a regression test suite to examine the correctness as well as integrity of CLIP. Each module of CLIP was tested individually by designing both basic and complex test cases and printing out their results respectively. For scanner and parser, we manually input different CLIP programs and printing the AST(.tree) out in the form of a parsing tree. For translator, we tested it by writing various CLIP code and printing them out as C++ code(.cc). Finally, the automation was triggered and to test the final output of each CLIP program by comparing them with reference results(.ref). With the progress of each module being developed and new features being added, the regression test suite was run on a regular basis to ensure that the language was analyzed and operated correctly, and that new adjustments would not damaged previous program behaviors.
\subsubsection{Integration testing}
In the process starting from scanner to C++ code generation, syntax, lexical conventions and semantics were check by taking advantage of various sets of input: constants, types, variable and functions. The correctly generated code would then be translated to C++ and compile with g++ to verify with their expected output.
\begin{itemize}
\item Constants(Literals)

Integer, bit numbers and strings were tested and verified. Escape sequences could be correctly handled:

(\c{\\n}, \c{\\t}, \c{\\r}, \c{"\\ "})

\item Types

In CLIP, four types are supported: \c{int}, \c{bit#}, \c{string} and vector. Each was checked with several test cases. For vectors, we also tested their declaration and binding. Testing of those types include negative cases such as assigning an int to a string.


\item Variables

Declaration and bindings of each variable was checked by printing out the result.

\item Functions 

We implement nested functions as test cases and refer to the AST tree generated to check if each function could be called in the right order, and if the scope of arguments of each function were corrected handled.


\end{itemize}
%enumerate  
\subsubsection{System testing}
Several CLIP programs were created and tested. Test cases varies from the most simple Hello World file to the more sophisticated cryptographic algorithms such as RSA. Scope rules and function closure were tested.The test cases could be found in the Test cases section below. In the CLIP to C++ section, we also demonstrate some example programs. 

\subsection{Testing automation}
In order to efficiently run test cases, we created a script called ``testall.sh''. It takes in all the test cases from a certain directory and compiles them to C++ code.
\subsection{Test cases}
In the test directory, there is a wrong-cases folder in which negative test cases were stored. All of them are failed in the semantic check stage. Another folder is named right-cases, in which right test cases were stored. For debugging purpose, we gave output files different extension. 


\begin{table}[H]
\caption{Meaning of different file extension}
\begin{center}
\begin{tabular}{|l|l|}
    \hline
    File extension  &  Content\\ \hline 
    .clip & store source program\\ \hline
    .out & store the final result\\ \hline 
    .ref & store the expected result\\ \hline
    .DIFF & store the difference between final result and expected result\\ \hline
    .tree & store the AST tree given by parser\\ \hline
    .error &  store the standar error message\\ \hline
\end{tabular}
\end{center}
\end{table}


\begin{table}
\caption{Testing suite test cases}
\begin{center}
\begin{tabular}{|l|l|}
    \hline
    File  &  Testing target\\ \hline   
    test-arith & Test a number of different arithmatic functions\\ \hline
    test-binding & Test variable binding and assignment\\ \hline
    test-bit & Test built-in functions for bit number manipulation\\ \hline
    test-comp & Test built-in functions for integer comparison\\ \hline
    test-defun & Test function binding\\ \hline
    test-gcd & Test recursion\\ \hline
    test-if & Test the execution of built-in function if\\ \hline
    test-lambda & Test the execution of built-in function lambda\\ \hline
    test-logic & Test built-in function for logic operation\\ \hline
    test-map & Test built-in function map\\ \hline
    test-misce & Test built-in function zero and int-of-bits\\ \hline
    test-mod & Test built-in function mod\\ \hline
    test-parser1 & Test vector binding\\ \hline
    test-parser2 & Test built-in function make-vector\\ \hline
    test-rsa & Test a cryptographic algorithm RSA\\ \hline
    test-shiftrotate & Test built-in function for shift and rotate\\ \hline
    test-type & Test different types of variable binding\\ \hline
    test-vector & Test vector manipulation\\ \hline 

\end{tabular}
\end{center}
\end{table}

\subsection{CLIP to C++}
The source language CLIP would be translated into C++ language. Following are a few representative examples of CLIP program along with their target C++ program.
\setclip
\codefile{fortest.clip}{A simple addition example in CLIP}
\setc
\codefile{fortest.cc}{The addition example compiled to C++}
\setclip
\codefile{test-gcd.clip}{A recurrsive function gcd in CLIP}
\setc
\codefile{test-gcd.cc}{The gcd example compiled to C++}

\subsection{Testing roles}
The shell script and the test cases were created by Wei Duan, while Yi-Hsiu Chen helped to implement the cryptographic algorithms.

%----------------------------------------------------------------------------------------
%   Lessons Learned
%----------------------------------------------------------------------------------------

\section{Lessons Learned}
\begin{itemize}
\item Wei Duan

In this class, I learned lessons on both technique knowledge and teamwork. From the lectures, I got to understand the achetecture of building up a compiler, the important features for a good programming language as well as how to program in Ocaml. At first, typical PLT concepts such AST seemed a little abstract to me. But when we started to implement our own compiler, I knew the concepts better, and realized that following the knowledged being taught in class truly helped me in practice. In addition, to implement a good programming language, it worth taking more time in design beforehand. A clear big picture about how to implement the compiler would contribute to better development in the end. In our project, the sematic check was initially built in such a way that it did store the information regarding type of variables, arguments and functions. Yet, when we moved into the translator stage, it was hard to intepret CLIP program into C++ programs without those information. Hence, we went back to the semantic check module and made some adjustment. Another crucial thing I learned in this project is that effective communication between team members could be a big plus. We are a small team, with only two people. At the beginning, I was worried that we may produce less than other teams which have three to four people. However, it turned out that sometimes fewer people is not a bad thing. The communication between me and my teammate is very convenient, because we have more time flexibility. What really matters is the meaningful communications among team members.

\item Yi-Hsiu Chen

Doing this project, provide a good opportunity to scrutinize what we have learned in class.
Sometimes, I just thought I already understood what Professor was talking about.
However, until doing project and really implementing some concepts, then realized that I did not understand throughly, at least not well enough.
For instance, about the concept of static scope and dynamic scope, several issues and methods of implementation just popped up when I translated it. 
Even for the very first step: scanner and parser, I thought I designed the context free grammar of our language perfectly.
But it pops out lots of shift/reduce error after ocamlyacc it, which stuck me for an hour.
After several correcting, I finally diminished all warnings and knows the mechanism of such algorithm better.

In the technical part, although OCaml might the useful tool in future tasks, using a functional language forces me to think different about implementing and designing algorithms.
Also the pattern matching function is so useful that I just cannot imagine if I have to use another language to implementing a compiler.
I also learned two important things or techniques during doing project, version control and shell.
Although, at first, using them is painful and makes me frustrated when spending an hour just for fixing a stupid error, every time when git perfectly merge our modification or testing tens of files in one command.
I really appreciate the recommend from Professor.

Another thing I learned from this project is about teammate, even we only have two people, which makes deciding meeting time and communication much easier.
There is still lots of method to communicate and collaborate we can improve.
For two people, the most challenge part is how to divide the works properly, since we cannot waste any human resource.
Honestly, we did not do well at the beginning, we waste lots of time doing the same things or generating a garbage.
But afterward, we found out how to split to task, that is building the skeleton of the task at the beginning.
Otherwise, the codes created by different people just not mergeable, then you have to abandon one of them.

To sum up, I think the project is absolutely worth doing, even in the summer session.
Before doing the project, I though why on earth we have to such complicated thing in such short time.
Why can't we just learn more concepts form textbook.
Now I realized doing project makes you learn not only lot more practical things, also deeper in some important concepts.

\end{itemize}

%----------------------------------------------------------------------------------------
%   Appendix
%----------------------------------------------------------------------------------------

\section{Appendix}
\setocaml
\codefile{../ast.ml}{ast.ml}
\codefile{../builtin.ml}{builtin.ml}
\codefile{../parser.mly}{parser.mly}
\codefile{../printast.ml}{printast.ml}
\codefile{../printsast.ml}{printsast.ml}
\codefile{../sast.ml}{sast.ml}
\codefile{../semantic.ml}{semantic.ml}
\codefile{../semantic.mli}{semantic.mli}
\codefile{../translate.ml}{translate.ml}
\codefile{../translate.mli}{translate.mli}
\codefile{../clip.ml}{clip.ml}
\codefile{../scanner.mll}{scanner.mll}

\setc
\codefile{../library/builtin.cc}{builtin.cc}

\setsh
\codefile{../clipccore}{clipccore}
\codefile{../gmp.sh}{gmp.sh}
\codefile{../testall.sh}{testall.sh}


\setmake
\codefile{../Makefile}{Makefile}

\end{document}