\documentclass{Karma}
\usepackage{pgf}
\usepackage{listings}
\newcommand{\karma}{\textcolor{red}{$\overline{\textcolor{green!80!black}{\underline{\textcolor{blue!80!white}{\mbox{Karma}}}}}$}}

\usepackage{fontspec}
\setromanfont[Script=Devanagari]{Sanskrit 2003}

\setlength{\oddsidemargin}{0pt}
\setlength\textwidth{470pt}

\newcommand{\code}[1]{\texttt{\textcolor{blue!50!black}{\textbf #1}}}

\lstnewenvironment{codelisting}[1][]
{\lstset
  {
    keywordstyle=\color{blue!50!red}\bfseries,
    basicstyle=\small\ttfamily,
    language=C++,
    backgroundcolor=\color{gray!15!white},
    frame=single,
    frameround=ttt,
    caption=#1
  }
}
{}
{}

\begin{document}

\title{\karma (कर्म) File Format: ASDFS}
\author{Iyer Arvind Sundaram}
\maketitle
\tableofcontents

\pagebreak
\section{The Name}
The Vedas mention Chitragupta (चित्रगुप्ता) as the maintainer of the records of all Karma. He records it in a book by the name of Agrasandhanam (अग्रसंधानम्). It was hence found suitable to call the name of the format (which ultimately turned out as a file system) in which the Karma details are written as ASDFS or Agrasandhanam-File System. 



\section{\code{FileBase}}
\code{FileBase} is a abstract class. This class provides the interface for \code{SerialData} to work on. Thus it is an interface class. The following declares the \code{FileBase} class
\begin{codelisting}[\code{FileBase}]
class FileBase
{
        public: 
		virtual FilePosType write(const ByteType*,const FilePosType&)=0;
		virtual FilePosType read (ByteType*,const FilePosType&) const=0;
                
		virtual bool weof()const=0;
		virtual bool reof()const=0;
                
                virtual FilePosType wtell()const=0;
                virtual FilePosType rtell()const=0;

                virtual void wseek(const FilePosType& pos)=0;
                virtual void rseek(const FilePosType& pos)const=0;

                virtual FilePosType size()const=0;
                virtual void writeZeros(const FilePosType&)=0;

                virtual ~FileBase(){}
};
\end{codelisting}

\code{FileBase} demands the presence of two distinct and independent file pointers, one for reading and the othr for writing. Thus when a data is read, it will read from the current location of the read pointer in the stream, and likewise, when data is written it will be written at the current location of the write pointer. The read or written will be arrays of type \code{ByteType}. \code{ByteType} is one byte wide, and in most system it is a typedef of \code{unsigned char}. When a data is to be written (or read), it is to be converted into( or from) a serialized form. This is most usually done by using the utility functions provided by \code{SerialData}. The concrete subclasses of \code{FileBase} provide the \textsl{substrate} for \code{SerialData} to write on.
\paragraph{Function Documentation}

The following functions are pure virtual in \code{FileBase} and to be implemented in the concrete class.
\begin{description}
\item[\code{write}] Write at the most the specified (arg 2) bytes from the buffer (arg 1) to the stream at the current write position. Return the number of bytes actually written.
\item[\code{read}] Read at the most the specified (arg 2) bytes from the stream and write it into the provided buffer(arg 1), at the current read position. Return the number of bytes actually read

\item[\code{weof}] Return true if the current write pointer is at the end of the file, otherwise return false.
\item[\code{reof}] Return true if the current read pointer is at the end of the file, otherwise return false.

\item[\code{wtell}] Return the current position, as the bytes from the begining of the file, of the write pointer.
\item[\code{rtell}] Return the current position, as the bytes from the begining of the file, of the read pointer.

\item[\code{wseek}] Position the write pointer at the specified position from the begining of the stream.
\item[\code{rseek}] Position the read pointer at the specified position from the begining of the stream.

\item[\code{size}] Return the current size of the stream.
\item[\code{writeZeros}] Fill the specified size with zeros at the current write position.
\end{description}

\subsection{\code{Memfile}}
\code{Memfile} is the concrete child class of FileBase which provides for the writing of data purely in memory. \code{Memfile} uses a linked list of \code{ByteVectors} for storing the data. The vectors are concatenated based on certain criteria (yet to be implemented). 

\subsection{\code{SingleFile}}
\code{SingleFile} uses the native file system for storing the data. The constructor takes the argument of the name of the file. The file is always opened in binary mode.

\subsection{\code{Network} (proposed)}
It is proposed to have a protocol for the implementation of a seekable stream over TCP/IP.

\subsection{\code{Compressed}(proposed)}
It is proposed to have a compressed file substrate.

\section{\code{SerialData}}
The fundamental unit of the ASDFS is the \code{SerialData}. This is the placeholder for the serialized representation of an object. \code{SerialData} provides functions and operators useful for Serialization of data. \code{SerialData}, may be \textsl{mounted} over a concrete child class of the abstract class \code{FileBase}. A \code{SerialData} thus provides for a unified, and consistent technique for writing data over a range of media, that is, by using \code{SerialData} with Memfile on can store and pass around serialized data in the memory. And by using \code{SerialData} with network file, one can pass the same information over TCP/IP. 
\subsection{What \code{SerialData} cannot do}
Serialized data is available as a stream of bytes. A \code{SerialData} may hold several objects in a contiguious manner. \code{SerialData} does not separate the objects in any way. That means that four characters of one byte each may be read in as an integer of four bytes, though such interpretations are usually not correct. The serialized data is not self describing, and other means must be adopded for describing the data.
\subsection{What it can do}
In cases where the order of the data stored is known, one can use \code{SerialData} for serialization. One of the prime requirements that arises because of the contiguious nature of the data is that, one needs to know apriori how many bytes to be read. This is simple in the cases of POD type data. For example, an \code{integer} of four bytes data, is obviously read by reading four bytes from the stream, and likewise, a \code{double} can be read by reading eight bytes. However in cases like that of reading arrays of character strings, one must adopt means to inform how much of the stream to be read. This is easily acomplished by first writing an integer, indicating the number of characters, and then writing the data itself, so that while reading, the function will first read the number of elements to be read, and then read those many elements. 

Serialization of the atomic types is available. The idea is that, one uses this code to serialize increasingly complicated data types. Reading and writing from/to SerialData is accomplished by using the right shift, and the left shift operators, usually. Thus 

\begin{codelisting}[{Writing a double to \code{SerialData}}]
SerialData ser;
ser<<3.14159265;
double d;
ser>>d;
ASSERT(d==3.14159265,"serialization of double is not correct")
\end{codelisting}
Serialization is provided in-built for all the atomic types and std::string (this is a case where an integer is written before the actual characters of the string).
Thus
\begin{codelisting}[{Writing a string to \code{SerialData}}]
SerialData ser;
ser<<std::string("This is a test string");
std::string str;
ser>>str;
ASSERT(str=="This is a test string","serialization of string is not correct")
\end{codelisting}

Since \code{SerialData} can sore multiple objects, one can store both the above examples as 
\begin{codelisting}[{Multiple objects}]
SerialData ser;
ser<<std::string("This is a test string")<<3.14159265;
std::string str;
double d;
ser>>str>>d;//note ser>>d>>str; is not correct!
ASSERT(d==3.14159265,"serialization of double is not correct")
ASSERT(str=="This is a test string","serialization of string is not correct")
\end{codelisting}

Combining as above, one can write a simple serial writer and reader for a complex number as
\begin{codelisting}[{\code{SerialData} reader and writer example}]
class Complex
{
private:
  double _re,_im;
public:
  double& re(){return _re;}
  const double& re()const{return _re;}
  double& im(){return _im;}
  const double& im()const{return _im;}

};
SerialData& operator<<(SerialData& ser,const Complex& cplx)
{
  return ser<<cplx.re()<<cplx.im();
}
const SerialData& operator<<(const SerialData& ser,Complex& cplx)
{
  return ser>>cplx.re()>>cplx.im();
}
\end{codelisting}
\end{document}
