doc update

doc/tvdos.tex

@@ -33,42 +33,104 @@ Variables can be set or changed using \textbf{SET} commands.
 \chapter{DOS Commands}
 
 
-\chapter{DOS Libraries}
+\chapter{File I/O}
+\index{filesystem (DOS)}In \thedos, drives are assigned with a drive letter, and the drive currently booted on is always drive \textbf{A}.
 
-\section{Filesystem}
 
-\index{filesystem (DOS)}Each port is assigned to different drive letters, and the device currently booted on is always drive \textbf{A}.
+\section{The File Descriptor}
+\index{file descriptor (DOS)}A file is virtualised through the \emph{file descriptor} which provides the functions to manipulate the file. Do note that when a file descriptor is created, the file is not yet opened by the drive.
 
-\section{The Filesystem Library}
+To create a file descriptor, use the provided function \code{files.open(fullpath)}. \code{fullpath} is a fully qualified path of the file that includes the drive letter.
 
-\dosnamespaceis{Filesystem}{filesystem}
+\section{Manipulating a File}
+A file has folliwing properties and can be manipulated using following functions:
+
+Properties:
 
 \begin{outline}
-\1\textbf{open}(driveLetter: String, path: String, operationMode: String)
-\\Opens a file on the specified drive.
- \2Operation Mode: \textbf{R} for read, \textbf{W} for overwrite, \textbf{A} for append
-\1\textbf{readAll}(driveLetter: String)
-\\Reads entire content of the file and return it as a string.
-\1\textbf{readAllBytes}(driveLetter: String)
-\\Reads entire content of the file and return it as a array of bytes.
-\1\textbf{getFileLen}(driveLetter: String)
-\\Returns a size of the file currently opened.
-\1\textbf{write}(driveLetter: String, bytes: String)
-\\Writes bytes onto the file opened for specified drive.
-\1\textbf{writeBytes}(driveLetter: String, bytes: ByteArray)
-\\Writes bytes onto the file opened for specified drive.
-\1\textbf{isDirectory}(driveLetter: String)
-\\Returns true if the file opened for the drive is a directory.
-\1\textbf{mkDir}(driveLetter: String)
-\\Creates a directory of opened path for the drive. Usage:
-\\\code{filesystem.open("A", "path/to/nonexisting/directory", "W"); filesystem.mkDir("A")}
-\1\textbf{touch}(driveLetter: String)
-\\Updates a last-modified date of the opened file. If file does not exist, creates one.
-\1\textbf{mkFile}(driveLetter: String)
-\\Creates a file of opened path for the drive. Usage:
-\\\code{filesystem.open("A", "path/to/nonexisting/file", "W"); filesystem.mkFile("A")}
+\1\textbf{size}: Int
+\\Returns a size of the file in bytes.
+\1\textbf{path}: String
+\\Returns a path (NOT including the drive letter) of the file. Paths are separated using reverse solidus.
+\1\textbf{fullpath}: String
+\\Returns a fully qualified path (including the drive letter) of the file. Paths are separated using reverse solidus.
+\1\textbf{driverID}: String
+\\Returns a filesystem driver ID associated with the file.
+\1\textbf{driver}: [Object object]
+\\Returns a filesystem driver (a Javascript object) for the file.
+\1\textbf{isDirectory}: Boolean
+\\Returns true if the path is a directory.
+\1\textbf{name}: String
+\\Returns the name part of the file's path.
+\1\textbf{parentPath}: String
+\\Returns a parent path of the file.
+\1\textbf{exists}: Boolean
+\\Returns true if the file exists on the device.
 \end{outline}
 
+Functions:
+
+\begin{outline}
+\1\textbf{pread}(pointer: Int, count: Int, offset: Int)
+\\Reads the file bytewise and puts it to the memory starting from the \code{pointer}.
+ \2\code{count}: how many bytes to read
+ \2\code{offset}: when reading a file, how many bytes to skip initially
+\1\textbf{bread}(): Array
+\\Reads the file bytewise and returns the content in Javascript array.
+\1\textbf{sread}(): String
+\\Reads the file textwise and returns the content in Javascript string.
+\1\textbf{pwrite}(pointer: Int, count: Int, offset: Int)
+\\Writes the bytes stored in the memory starting from the \code{pointer} to file.
+ \2\code{count}: how many bytes to write
+ \2\code{offset}: when writing to the file, how many bytes on the file to skip before writing a first byte.
+\1\textbf{bwrite}(bytes: UintArray)
+\\Writes the bytes to the file.
+\1\textbf{swrite}(string: String)
+\\Writes the string to the file.
+\1\textbf{flush}()
+\\Flush the contents on the write buffer to the file immediately. Will do nothing if there is no write buffer implemented --- a write operation will always be performed imemdiately in such cases.
+\1\textbf{close}()
+\\Tells the underlying device (usually a disk drive) to close a file. When dealing with multiple files on a single disk drive (of which can only have a single active---or opened---file), the underlying filesystem driver will automatically swap the files around, so this function is normally unused.
+\1\textbf{list}(): Array or undefined
+\\Lists files inside of the directory. If the path is indeed a directory, an array of file descriptors will be returned; \code{undefined} otherwise.
+\1\textbf{touch}(): Boolean
+\\Updates the file's access time if the file exists; a new file will be created otherwise. Returns true if successful.
+\1\textbf{mkDir}(): Boolean
+\\Creates a directory to the path. Returns true if successful.
+\1\textbf{mkFile}(): Boolean
+\\Creates a new file to the path. Returns true if successful.
+\1\textbf{remove}(): Boolean
+\\Removes a file. Returns true if successful.
+\end{outline}
+
+
+\section{The Device Files}
+
+\index{device file}Some devices are also virtualised through the file descriptor, and they are given a special path. (their fullpath does not contain a drive letter)
+
+\begin{outline}
+\1\textbf{RND} --- returns random bytes upon reading
+ \2\textbf{pread}: returns the specified number of random bytes
+\1\textbf{NUL} --- returns EOF upon reading
+ \2\textbf{pread}: returns the specified number of EOFs
+ \2\textbf{bread}: returns an empty array
+ \2\textbf{sread}: returns an empty string
+\1\textbf{ZERO} --- returns zero upon reading
+ \2\textbf{pread}: returns the specified number of zeros
+\1\textbf{CON} --- manipulates the screen text buffer, disregarding the colours
+ \2\textbf{pread}: reads the texts as bytes.
+ \2\textbf{bread}: reads the texts as bytes.
+ \2\textbf{sread}: reads the texts as a string.
+ \2\textbf{pwrite}: writes the bytes from the given pointer.
+ \2\textbf{bwrite}: identical to \code{print()} except the given byte array will be casted to string.
+ \2\textbf{swrite}: identical to \code{print()}.
+\1\textbf{FBIPF} --- decodes IPF-formatted image to the framebuffer. Use the \emph{Graphics} library for the encoding.
+ \2\textbf{pwrite, bwrite} --- decodes the given IPF binary data. \code{pwrite} offsets and counts are ignored.
+
+\end{outline}
+
+
+\chapter{DOS Libraries}
 
 
 \section{The Input Library}