restructure file layout

3 files changed, 259 insertions, 0 deletions

diff --git a/doc/a_simple_example.c b/doc/a_simple_example.c
new file mode 100644
index 0000000..fb7d774
--- /dev/null
+++ b/doc/a_simple_example.c
@@ -0,0 +1,52 @@
+#include "simple-test.h"
+#include "header_with_stuff_to_be_tested.h"
+
+BEGIN_TEST
+
+/* a simple test using only stack mem */
+TEST("description of the first test")
+{
+  int var1=2;
+  int var2=4;
+  
+  /* add is a function included from our hypothetical
+   * header_with_stuff_to_be_tested */
+  EXPECT_INT("error message shown on failing",
+		  var1+var2, add(var1, var2));
+}
+
+/* this test uses heap memory, so things get a bit
+ * more complicated */
+TEST("this is the second test")
+{
+  /* first, ensure all your pointers which will
+   * point to heap mem are declared */
+  char *heap_string=NULL;
+  
+  /* next, declare a list of statements to be
+   * called to clean up memory once the test
+   * is completed */
+  CLEANUP(
+      if(heap_string != NULL)
+        free(heap_string);
+        );
+        
+  /* then, define the body of the test */
+  
+  /* STATE can be used to report (with pretty
+   * formatting) the current state within the
+   * test, which may be useful in the case of
+   * a segfault */
+  STATE("grabbing heap string");
+  
+  heap_string=get_heap_string_value();
+  
+  EXPECT_STR("i suck at grabbing pointers!",
+		  "expected value", heap_string);
+  
+  /* finally, call RETURN(); to run the
+   * cleanup code and continue */
+  RETURN();
+}
+
+END_TEST
diff --git a/doc/usage.pdf b/doc/usage.pdf
new file mode 100644
index 0000000..fb6f9c7
--- /dev/null
+++ b/doc/usage.pdf
diff --git a/doc/usage.tex b/doc/usage.tex
new file mode 100644
index 0000000..6494ee5
--- /dev/null
+++ b/doc/usage.tex
@@ -0,0 +1,207 @@
+%%%%%%%%%%%
+%  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}
+