%%%%%%%%%%%
%  SETUP  %
%%%%%%%%%%%

\documentclass[a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[usenames,x11names,table]{xcolor}

\usepackage{listings}
\usepackage{enumitem}
\usepackage{graphicx}
\usepackage{framed}
\usepackage{calc}
\usepackage{ifthenx}
\usepackage{tabularx}
\usepackage{soul}

%%% -------------------------------------------------------
%%% universal formatting
%%% -------------------------------------------------------

\parindent 0pt
\frenchspacing
\pagestyle{empty}

\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}
\setlength{\marginparsep}{0in}
\setlength{\marginparwidth}{0in}
\setlength{\textwidth}{6.5in}

\setlength{\topmargin}{0in}
\setlength{\headsep}{0in}
\setlength{\headheight}{0in}
\setlength{\textheight}{9in}

%%% -------------------------------------------------------
%%% custom commands
%%% -------------------------------------------------------

% a horizontal box with coloured background
\newcommand{\myheading}[1]{
	{
		\definecolor{shadecolor}{named}{Azure4}
		\begin{snugshade*}
			\centering\large
			\textcolor{white}{\textbf{-- #1 --}\vphantom{p\^{E}}}
		\end{snugshade*}
	}
}

\newcommand{\myhl}[1]{
	{
		\color{Snow1}
		\sethlcolor{Red1}
		\hl{#1}
	}
}

\newcommand{\mymacrow}[2]{
	\footnotesize\textcolor{DarkOrchid3}{\textbf{#1}}: & \small #2 \\[8pt]
}

\newcommand{\mytermrow}[2]{
	\tt\bf\small #1 & \tt\small #2 \\
}



\begin{document}
	
	% setup
	\frenchspacing
	
	% C styling
	\lstdefinestyle{customc}{
		language=C,
		basicstyle=\small\ttfamily,
		breaklines=true,
		keepspaces=true,
		xleftmargin=\parindent,
		% colours
		commentstyle=\color{DodgerBlue2},
		identifierstyle=\color{Red1},
		keywordstyle=\color{Purple3},
		stringstyle=\color{SpringGreen4},
		numbers=left,
		showstringspaces=false,
	}


	\myheading{usage}

	Your tests should be written as a single .c file separate from
	the body of text containing your functionality to be tested.
	A simple example might look something like this: \\ 

	\hrule
	\lstset{style=customc}
	\lstinputlisting{a_simple_example.c}
	\hrule
	\pagebreak

	If both tests above succeed, the output will look like this:\\

	\hrule
	\vspace{8pt}

	% successful output
	\begin{tabular*}{\textwidth}{r@{\ \tt\bf :: }l}
		\mytermrow{1}{\color{Yellow4}description of the first test}
		\mytermrow{2}{\color{Yellow4}this is the second test}
		\mytermrow{ }{\color{DodgerBlue2}grabbing heap string...}
		\mytermrow{ }{\color{SpringGreen4}success!}
	\end{tabular*}

	\vspace{8pt}
	\hrule
	\vspace{20pt}

	If the first test fails, it will look something like this:\\
	\hrule
	\vspace{8pt}

	% failed output
	\begin{tabular*}{\textwidth}{r@{\ \tt\bf :: }l}
		\mytermrow{1}{\color{Yellow4}description of the first test}
		\mytermrow{ }{\color{Red1}FAIL: error message shown on failing}
		\mytermrow{ }{\textcolor{SpringGreen4}{\textbf{\ \ expected:}}6}
		\mytermrow{ }{\textcolor{Red1}{\textbf{\ \ \ \ actual:}}0}
	\end{tabular*}
	
	\vspace{8pt}
	\hrule

	\pagebreak

	\myheading{defined macros}
	\begin{tabularx}{\textwidth}{r@{\ }X}
		\mymacrow{BEGIN\_TEST}{
			must appear before all tests and 
			after all global variable declarations
		}
		\mymacrow{END\_TEST}{
			must appear at the end of your test
			program
		}
		\mymacrow{CLEANUP(statements)}{
			this defines a list of statements to run
			when the test exits, either successfully or
			on a failure. it isn't necessary for a test
			to run, but, if it does appear, it must be
			after the declaration of all variables to
			which it makes reference.
		}
		\mymacrow{RETURN()}{
			place at the end of a test which uses
			CLEANUP to ensure it is called before the
			test exits. i couldn't find any way around
			this without using more than just one
			header file, so i hope it isn't too annoying.
		}
		\mymacrow{STATE(description)}{
			show a prettily-formatted description of the
			program's state during a test. takes printf-style
			arguments.
		}
		\mymacrow{EXPECT\_ZERO(summary, arg)}{
			fail if \texttt{arg} does not resolve to 0
		}
		\mymacrow{EXPECT\_ONE(summary, arg)}{
			fail if \texttt{arg} does not resolve to 1
		}
		\mymacrow{EXPECT\_GREATER\_THAN\_ZERO(summary, arg)}{
			fail if \texttt{arg} does not resolve to a value
			greater than 0. this will be replaced with more
			generic integer comparisons soon.
		}
		\mymacrow{EXPECT\_INT(summary, arg1, arg2)}{
			fail if \texttt{arg2} does not match the
			expected integer value \texttt{arg1}
		}
		\mymacrow{EXPECT\_EQUAL\_INT(summary, arg1, arg2)}{
			fail if \texttt{arg1} and \texttt{arg2} are
			not equal
		}
		\mymacrow{EXPECT\_UNEQUAL\_INT(summary, arg1, arg2)}{
			fail if \texttt{arg1} and \texttt{arg2} are
			equal
		}
		\mymacrow{EXPECT\_STR(summary, arg1, arg2)}{
			fail if string \texttt{arg2} does not match the
			expected string value \texttt{arg1}
		}
		\mymacrow{EXPECT\_EQUAL\_STR(summary, arg1, arg2)}{
			fail if \texttt{arg1} and \texttt{arg2} are
			not equivalent strings
		}
		\mymacrow{EXPECT\_UNEQUAL\_STR(summary, arg1, arg2)}{
			fail if \texttt{arg1} and \texttt{arg2} are
			equivalent strings
		}
	\end{tabularx}

\end{document}