curioustorvald/tsvm
1
0
Fork 0
mirror of https://github.com/curioustorvald/tsvm.git synced 2026-03-07 11:51:49 +09:00
Code Issues Packages Projects Releases Wiki Activity

doc: more macros for uniform doc style

Browse Source
This commit is contained in:
minjaesong
2022-08-27 13:46:18 +09:00
parent e91fac4fb5
commit b41ff1c834
3 changed files with 95 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
doc/implementation.tex
View File

@@ -21,12 +21,12 @@ Your Javascript program is stored into the Program Memory, and since its capacit
\index{js extensions}\thismachine\ provides the extra functions for your convenience.
\begin{outline}
\1Array.\textbf{head}() --- returns the first element of the array.
\1Array.\textbf{last}() --- returns the last element of the array.
\1Array.\textbf{tail}() --- returns the subarray that omits the \emph{head} element.
\1Array.\textbf{init}() --- returns the subarray that omits the \emph{last} element.
\1Array.\textbf{sum}(selector) --- returns the sum of the elements of the array. Selector can be optionally defined to indicate how the value must be transformed to obtain the sum.
\1Array.\textbf{max}(selector) --- returns the maximum among the elements of the array. Selector can be optionally defined to indicate how the value must be transformed to obtain the max.
\1\inlinesynopsis[Array]{head}{}{returns the first element of the array.}
\1\inlinesynopsis[Array]{last}{}{returns the last element of the array.}
\1\inlinesynopsis[Array]{tail}{}{returns the subarray that omits the \emph{head} element.}
\1\inlinesynopsis[Array]{init}{}{returns the subarray that omits the \emph{last} element.}
\1\inlinesynopsis[Array]{sum}{selector}{returns the sum of the elements of the array. Selector is optionally defined to indicate how the value must be transformed to obtain the sum.}
\1\inlinesynopsis[Array]{max}{selector}{returns the maximum among the elements of the array. Selector is optionally defined to indicate how the value must be transformed to obtain the max.}
\end{outline}
\subsection{Standard Input and Output}
@@ -34,11 +34,11 @@ Your Javascript program is stored into the Program Memory, and since its capacit
\index{stdio (library)}These are standard input/output functions:
\begin{outline}
\1\textbf{print}(string) --- prints a string without a new line.
\1\textbf{println}(string) --- prints a string with a new line.
\1\textbf{printerr}(string) --- prints a string to error output without a new line.
\1\textbf{printerrln}(string) --- prints a string to error output with a new line.
\1\textbf{read}() --- reads a string from the keyboard. Hit the Return to finish reading.
\1\inlinesynopsis{print}{string}{prints a string without a new line.}
\1\inlinesynopsis{println}{string}{prints a string with a new line.}
\1\inlinesynopsis{printerr}{string}{prints a string to error output without a new line.}
\1\inlinesynopsis{printerrln}{string}{prints a string to error output with a new line.}
\1\inlinesynopsis{read}{}{reads a string from the keyboard. Hit the Return to finish reading.}
\end{outline}
@@ -61,7 +61,7 @@ Your Javascript program is stored into the Program Memory, and since its capacit
\namespaceis{System}{system}
\begin{outline}
\1\textbf{maxmem}() --- returns the size of the Scratchpad Memory in bytes.
\1\inlinesynopsis{maxmem}{}{returns the size of the Scratchpad Memory in bytes.}
\end{outline}
@@ -121,23 +121,14 @@ When the read/write operation is being processed, each side emits ``busy'' flag
\namespaceis{Com}{com}
\begin{outline}
\1\textbf{sendMessage}(portNo: Int, message: String)
\\Sends message to the port and returns status code the other machine emits.
\1\textbf{fetchResponse}(portNo: Int): String
\\Fetches the message composed by other device to this machine.
\1\textbf{sendMessageGetBytes}(portNo: Int, message: String): String
\\Sends message, waits for responce, then returns the received message.
\1\textbf{waitUntilReady}(portNo: Int)
\\Blocks the program until the other device is ready.
\1\textbf{pullMessage}(portNo: Int): String
\\Make other device to initiate sending and returns the message receive from the other device.
\\NOTE: this is not a function you're looking for it you're just getting the response after the sendMessage; use fetchResponse for that.
\1\textbf{getStatusCode}(portNo: Int): Int
\\Returns the status code of the other device.
\1\textbf{getDeviceStatus}(portNo: Int): \{code: Int, message: String\}
\\Returns the status message of the other device. Different types of devices may have different messages.
\1\textbf{areYouThere}(portNo: Int): Boolean
\\Returns true if there is other device connected and is working.
\1\formalsynopsis{sendMessage}{portNo: Int, message: String}{Sends message to the port and returns status code the other machine emits.}
\1\formalsynopsis{fetchResponse}{portNo: Int}[String]{Fetches the message composed by other device to this machine.}
\1\formalsynopsis{sendMessageGetBytes}{portNo: Int, message: String}[String]{Sends message, waits for responce, then returns the received message.}
\1\formalsynopsis{waitUntilReady}{portNo: Int}{Blocks the program until the other device is ready.}
\1\formalsynopsis{pullMessage}{portNo: Int}[String]{Make other device to initiate sending and returns the message receive from the other device.\\NOTE: this is not a function you're looking for it you're just getting the response after the sendMessage; use fetchResponse for that.}
\1\formalsynopsis{getStatusCode}{portNo: Int}[Int]{Returns the status code of the other device.}
\1\formalsynopsis{getDeviceStatus}{portNo: Int}[\{code: Int, message: String\}]{Returns the status message of the other device. Different types of devices may have different messages.}
\1\formalsynopsis{areYouThere}{portNo: Int}[Boolean]{Returns true if there is other device connected and is working.}
\end{outline}
@@ -246,18 +237,17 @@ The com-port will behave differently if you're writing to or reading from the ad
\end{figure}
\begin{outline}
\1\textbf{size-LSB/MSB} --- size of the data within the block
\2\textbf{read}: from the other device
\\\textbf{write}: what the device is about to send
\\size of zero must be interpreted as 4096
\1\textbf{read} --- bit is set if the other device \emph{hasNext}, unset otherwise or the device is not present
\1\textbf{M/S} --- Master/Slave setup of the other device. Typically a disk drive is slave-only (01), a computer is both (11)
\1\textbf{T/R} --- Send-Receive mode for the port. Set the bit to send from the port, unset to read
\1\textbf{busy} --- device busy/transfer trigger
\2\textbf{read}: the port is receiving something if the bit is set
\\\textbf{write}: setting this bit initiates transfer. If T/R bit is set, the device will send out, otherwise the other device will start the transfer
\1\textbf{ready} --- write to indicate this device is ready to receive; read to know if the other device is ready
\1\textbf{hello} --- bit is set if other device is connected
\1\inlinesynopsis{size-LSB/MSB}{size of the data within the block}
\2\argsynopsis{read}{from the other device}
\2\argsynopsis{write}{what the device is about to send. size of zero must be interpreted as 4096}
\1\inlinesynopsis{read}{bit is set if the other device \emph{hasNext}, unset otherwise or the device is not present}
\1\inlinesynopsis{M/S}{Master/Slave setup of the other device. Typically a disk drive is slave-only (01), a computer is both (11)}
\1\inlinesynopsis{T/R}{Send-Receive mode for the port. Set the bit to send from the port, unset to read}
\1\inlinesynopsis{busy}{device busy/transfer trigger}
\2\argsynopsis{read}{the port is receiving something if the bit is set}
\2\argsynopsis{write}{setting this bit initiates transfer. If T/R bit is set, the device will send out, otherwise the other device will start the transfer}
\1\inlinesynopsis{ready}{write to indicate this device is ready to receive; read to know if the other device is ready}
\1\inlinesynopsis{hello}{bit is set if other device is connected}
\end{outline}

20
doc/tsvmman.tex
View File

@@ -42,6 +42,7 @@
\usepackage{anyfontsize}
\usepackage{cancel}
\usepackage{outlines}
\usepackage{xparse}
\usepackage{lineno} % debug
@@ -72,6 +73,23 @@
\newcommand{\namespaceis}[2]{\index{#2 (library)}The functions in the #1 library can be found under the \textbf{#2} namespace.}
\newcommand{\dosnamespaceis}[2]{\index{#2 (DOS)}The functions in the \thedos\ #1 library can be found under the \textbf{#2} namespace.}
% usage: \inlinesynopsis{any name}{description}
% usage: \inlinesynopsis{function name}{arguments info}{description}
% usage: \inlinesynopsis[namespace]{any name}{description}
% usage: \inlinesynopsis[namespace]{function name}{arguments info}{description}
\NewDocumentCommand\inlinesynopsis{ommg}{%
\IfNoValueF{#1}{#1.}\textbf{#2}\IfNoValueTF{#4}{ --- #3}{(#3) --- #4}%
}
% usage: \formalsynopsis{function name}{arguments info}[return type]{description}
% usage: \formalsynopsis{function name}{arguments info}{description}
\NewDocumentCommand\formalsynopsis{mmom}{%
\textbf{#1}(#2)\IfNoValueF{#3}{: #3}\\#4%
}
\newcommand\propertysynopsis[3]{\textbf{#1}: #2\\#3}
\newcommand\argsynopsis[2]{\textbf{#1}: #2}
\newcommand\forceindent{\hskip1.5em}
%% BASIC operators %%
@@ -80,6 +98,8 @@
\newcommand{\instbitrange}[2]{~\instbit{#1} \hfill \instbit{#2}~}
% Title styling
% \pretitle{\begin{flushright}}
% \posttitle{\par\end{flushright}}

109
doc/tvdos.tex
View File

@@ -48,59 +48,38 @@ A file has folliwing properties and can be manipulated using following functions
Properties:
\begin{outline}
\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.
\1\propertysynopsis{size}{Int}{Returns a size of the file in bytes.}
\1\propertysynopsis{path}{String}{Returns a path (NOT including the drive letter) of the file. Paths are separated using reverse solidus.}
\1\propertysynopsis{fullpath}{String}{Returns a fully qualified path (including the drive letter) of the file. Paths are separated using reverse solidus.}
\1\propertysynopsis{driverID}{String}{Returns a filesystem driver ID associated with the file.}
\1\propertysynopsis{driver}{[Object object]}{Returns a filesystem driver (a Javascript object) for the file.}
\1\propertysynopsis{isDirectory}{Boolean}{Returns true if the path is a directory.}
\1\propertysynopsis{name}{String}{Returns the name part of the file's path.}
\1\propertysynopsis{parentPath}{String}{Returns a parent path of the file.}
\1\propertysynopsis{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.
\1\formalsynopsis{pread}{pointer: Int, count: Int, offset: Int}{Reads the file bytewise and puts it to the memory starting from the pointer.}
\2\argsynopsis{count}{how many bytes to read}
\2\argsynopsis{offset}{when reading a file, how many bytes to skip initially}
\1\formalsynopsis{bread}{}[Array]{Reads the file bytewise and returns the content in Javascript array.}
\1\formalsynopsis{sread}{}[String]{Reads the file textwise and returns the content in Javascript string.}
\1\formalsynopsis{pwrite}{pointer: Int, count: Int, offset: Int}
{Writes the bytes stored in the memory starting from the pointer to file.}
\2\argsynopsis{count}{how many bytes to write}
\2\argsynopsis{offset}{when writing to the file, how many bytes on the file to skip before writing a first byte.}
\1\formalsynopsis{bwrite}{bytes: UintArray}{Writes the bytes to the file.}
\1\formalsynopsis{swrite}{string: String}{Writes the string to the file.}
\1\formalsynopsis{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\formalsynopsis{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\formalsynopsis{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\formalsynopsis{touch}{}[Boolean]{Updates the file's access time if the file exists; a new file will be created otherwise. Returns true if successful.}
\1\formalsynopsis{mkDir}{}[Boolean]{Creates a directory to the path. Returns true if successful.}
\1\formalsynopsis{mkFile}{}[Boolean]{Creates a new file to the path. Returns true if successful.}
\1\formalsynopsis{remove}{}[Boolean]{Removes a file. Returns true if successful.}
\end{outline}
@@ -109,23 +88,23 @@ Functions:
\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.
\1\inlinesynopsis{RND}{returns random bytes upon reading}
\2\argsynopsis{pread}{returns the specified number of random bytes}
\1\inlinesynopsis{NUL}{returns EOF upon reading}
\2\argsynopsis{pread}{returns the specified number of EOFs}
\2\argsynopsis{bread}{returns an empty array}
\2\argsynopsis{sread}{returns an empty string}
\1\inlinesynopsis{ZERO}{returns zero upon reading}
\2\argsynopsis{pread}{returns the specified number of zeros}
\1\inlinesynopsis{CON}{manipulates the screen text buffer, disregarding the colours}
\2\argsynopsis{pread}{reads the texts as bytes.}
\2\argsynopsis{bread}{reads the texts as bytes.}
\2\argsynopsis{sread}{reads the texts as a string.}
\2\argsynopsis{pwrite}{writes the bytes from the given pointer.}
\2\argsynopsis{bwrite}{identical to \code{print()} except the given byte array will be casted to string.}
\2\argsynopsis{swrite}{identical to \code{print()}.}
\1\inlinesynopsis{FBIPF}{decodes IPF-formatted image to the framebuffer. Use the \emph{Graphics} library for the encoding.}
\2\argsynopsis{pwrite, bwrite}{decodes the given IPF binary data. Offsets and counts for \code{pwrite} are ignored.}
\end{outline}