basic yet more docs

assets/basic.js

@@ -27,6 +27,7 @@ let TRACEON = true;
 let DBGON = true;
 let DATA_CURSOR = 0;
 let DATA_CONSTS = [];
+let DEFUNS_BUILD_DEFUNS = false;
 
 if (system.maxmem() < 8192) {
     println("Out of memory. BASIC requires 8K or more User RAM");
@@ -615,7 +616,7 @@ if no arg text were given (e.g. "10 NEXT"), args will have zero length
     return twoArgNum(lnum, stmtnum, args, (lh,rh) => lh << rh);
 },
 ">>" : function(lnum, stmtnum, args) {
-    return twoArgNum(lnum, stmtnum, args, (lh,rh) => lh >> rh);
+    return twoArgNum(lnum, stmtnum, args, (lh,rh) => lh >>> rh);
 },
 "UNARYMINUS" : function(lnum, stmtnum, args) {
     return oneArgNum(lnum, stmtnum, args, (lh) => -lh);
@@ -1972,7 +1973,8 @@ bF._parseStmt = function(lnum, tokens, states, recDepth) {
         treeHead.astLeaves[0].astLeaves = defunArgDeclSeps.map(i=>bF._parseIdent(lnum, [tokens[i]], [states[i]], recDepth + 1));
 
         // parse function body
-        treeHead.astLeaves[1] = bF._parseExpr(lnum,
+        let parseFunction = (DEFUNS_BUILD_DEFUNS) ? bF._parseStmt : bF._parseExpr;
+        treeHead.astLeaves[1] = parseFunction(lnum,
             tokens.slice(parenEnd + 2, tokens.length),
             states.slice(parenEnd + 2, states.length),
             recDepth + 1

assets/tbas/doc/functions.tex

@@ -1 +1,135 @@
-Builtin functions
+\label{functions}
+
+Functions are a form of expression that may taks input arguments surrounded by parentheses. Most of the traditional BASIC \emph{statements} that does not return a value are \emph{functions} in \tbas , and like those, while \tbas{} functions can be called without parentheses, it is highly \emph{discouraged} because of the ambiguities in syntax. \textbf{Always use parentheses on function call!}
+
+\section{Mathematical}
+
+    \subsection{ABS}
+        \codeline{Y \textbf{= ABS(}X\textbf{)}}\par
+        Returns absolute value of \code{X}.
+    \subsection{ACO}
+        \codeline{Y \textbf{= ACO(}X\textbf{)}}\par
+        Returns inverse cosine of \code{X}.
+    \subsection{ASN}
+        \codeline{Y \textbf{= ASN(}X\textbf{)}}\par
+        Returns inverss sine of \code{X}.
+    \subsection{ATN}
+        \codeline{Y \textbf{= ATN(}X\textbf{)}}\par
+        Returns inverse tangent of \code{X}.
+    \subsection{CBR}
+        \codeline{Y \textbf{= CBR(}X\textbf{)}}\par
+        Returns cubic root of \code{X}.
+    \subsection{CEIL}
+        \codeline{Y \textbf{= CEIL(}X\textbf{)}}\par
+        Returns integer value of \code{X}, truncated towards positive infinity.
+    \subsection{COS}
+        \codeline{Y \textbf{= COS(}X\textbf{)}}\par
+        Returns cosine of \code{X}.
+    \subsection{COSH}
+        \codeline{Y \textbf{= COSH(}X\textbf{)}}\par
+        Returns hyperbolic cosine of \code{X}.
+    \subsection{EXP}
+        \codeline{Y \textbf{= EXP(}X\textbf{)}}\par
+        Returns exponential of \code{X}, i.e. $e^X$.
+    \subsection{FIX}
+        \codeline{Y \textbf{= FIX(}X\textbf{)}}\par
+        Returns integer value of \code{X}, truncated towards zero.
+    \subsection{FLOOR, INT}
+        \codeline{Y \textbf{=} \{\textbf{FLOOR}|\textbf{INT}\}\textbf{(}X\textbf{)}}\par
+        Returns integer value of \code{X}, truncated towards negative infinity.
+    \subsection{LOG}
+        \codeline{Y \textbf{= LOG(}X\textbf{)}}\par
+        Returns natural logarithm of \code{X}.
+    \subsection{ROUND}
+        \codeline{Y \textbf{= ROUND(}X\textbf{)}}\par
+        Returns closest integer value of \code{X}, rounding towards positive infinity.
+    \subsection{RND}
+        \codeline{Y \textbf{= RND(}X\textbf{)}}\par
+        Returns a random number within the range of $[0..1)$. If \code{X} is zero, previous random number will be returned; otherwise new random number will be returned.
+    \subsection{SIN}
+        \codeline{Y \textbf{= SIN(}X\textbf{)}}\par
+        Returns sine of \code{X}.
+    \subsection{SINH}
+        \codeline{Y \textbf{= SINH(}X\textbf{)}}\par
+        Returns hyperbolic sine of \code{X}.
+    \subsection{SGN}
+        \codeline{Y \textbf{= SGN(}X\textbf{)}}\par
+        Returns sign of \code{X}: 1 for positive, -1 for negative, 0 otherwise.
+    \subsection{SQR}
+        \codeline{Y \textbf{= SQR(}X\textbf{)}}\par
+        Returns square root of \code{X}.
+    \subsection{TAN}
+        \codeline{Y \textbf{= TAN(}X\textbf{)}}\par
+        Returns tangent of \code{X}.
+    \subsection{TANH}
+        \codeline{Y \textbf{= TANH(}X\textbf{)}}\par
+        Returns hyperbolic tangent of \code{X}.
+
+\section{Input}
+
+    \subsection{DIM}
+        \codeline{Y \textbf{= DIM(}X\textbf{)}}\par
+        Returns array with size of \code{X}, all filled with zero.
+    \subsection{GETKEYSDOWN}
+        \codeline{Y \textbf{= GETKEYSDOWN(}X\textbf{)}}\par
+        Returns array that contains keycode of keys held down in \code{X}.\par
+        Actual keycode and the array length depends on the machine: in \thismachine , array length will be fixed to 8. For the list of available keycodes, see \ref{technical}.
+    \subsection{INPUT}
+        \codeline{\textbf{INPUT} VARIABLE}\par
+        Prints out \code{? } to the console and waits for user input. Input can be any length and terminated with return key. The input will be stored to given variable.
+
+\section{Output}
+
+    \subsection{EMIT}
+        \codeline{\textbf{EMIT(}EXPR [\{\textbf{,}|\textbf{;}\} EXPR]...\textbf{)}}\par
+        Prints out characters corresponding to given number on the code page being used.\par
+        \code{EXPR} is numeric expression.
+    \subsection{PRINT}
+        \codeline{\textbf{PRINT(}EXPR [\{\textbf{,}|\textbf{;}\} EXPR]...\textbf{)}}\par
+        Prints out given string expressions.\par
+        \code{EXPR} is a string, numeric expression, or array.\par
+        \code{PRINT} is one of the few function that differentiates two style of argument separator: \codebf{;} will simply concatenate two expressions (unlike traditional BASIC, numbers will not have surrounding spaces), \codebf{,} tabulates the expressions.
+
+\section{Program Manipulation}
+
+    \subsection{CLEAR}
+    \subsection{DATA}
+    \subsection{END}
+    \subsection{FOR}
+    \subsection{FOREACH}
+    \subsection{GOSUB}
+    \subsection{GOTO}
+    \subsection{LABEL}
+    \subsection{NEXT}
+    \subsection{READ}
+    \subsection{RESTORE}
+    \subsection{RETURN}
+
+\section{String Manipulation}
+
+    \subsection{CHR}
+    \subsection{LEFT}
+    \subsection{MID}
+    \subsection{RIGHT}
+    \subsection{SPC}
+
+\section{Graphics}
+
+    \subsection{PLOT}
+
+\section{Meta}
+
+    \subsection{OPTIONBASE}
+    \subsection{OPTIONDEBUG}
+    \subsection{OPTIONTRACE}
+
+\section{System}
+
+    \subsection{PEEK}
+    \subsection{POKE}
+
+\section{Higher-order Function}
+
+    \subsection{DO}
+    \subsection{FOLD}
+    \subsection{MAP}

assets/tbas/doc/implementation.tex

@@ -1 +1,2 @@
+\label{technical}
 Keycodes follow LWJGL2 lol

assets/tbas/doc/langref.tex

@@ -6,14 +6,14 @@ This chapter describes the \tbas{} language.
 
 In the descriptions of BASIC syntax, these conventions apply.
 
-\begin{itemize}
+\begin{itemlist}
 \item \codebf{VERBATIM} --- Type exactly as shown
 \item \code{IDENTIFIER} --- Replace \emph{identifier} with appropriate metavariable
 \item \code{[a]} --- Words within square brackets are optional
 \item \code{\{a|b\}} --- Choose either \code{a} or \code{b}
 \item \code{[a|b]} --- Optional version of above
 \item \code{a...} --- The preceding entity can be repeated
-\end{itemize}
+\end{itemlist}
 
 \section{Definitions}
 
@@ -21,11 +21,11 @@ A \emph{Program Line} consists of a line number followed by a \emph{Statements}.
 
 A \emph{Line Number} is an integer within the range of \intrange{}.
 
-A \emph{Statements} consists of 1 statement or more, separated by colons:
+A \emph{Statement} is special form of code which has special meaning. A program line can be composed of 1 or more statements, separated by colons. For the details of statements available in \tbas , see \ref{statements}.
 
 \codeline{STATEMENT [: STATEMENT]...}
 
-An \emph{Expression} takes one of the following forms:
+An \emph{Expression} is rather normal program lines, e.g. mathematical equations and function calles. The expression takes one of the following forms. For the details of functions available in \tbas , see \ref{functions}.
 
 \codeline{VARIABLE\_OR\_FUNCTION}\\
 \codeline{( EXPRESSION )}\\
@@ -103,10 +103,10 @@ Precedence & Operators & Associativity & Precedence & Operators & Associativity
 \end{tabulary}
 
 \subsubsection*{Examples}
-\begin{itemize}
+\begin{itemlist}
 \item Exponentiation is more tightly bound than negation: \code{-1\basicexp 2 == -(1\basicexp 2) == -1} but \code{(-1)\basicexp 2 == 1}
 \item Exponentiation is right-associative: \code{4\basicexp 3\basicexp 2 == 4\basicexp (3\basicexp 2) == 262144}. This behaviour is \emph{different} from GW-BASIC in which its exponentiation is left-associative.
-\end{itemize}
+\end{itemlist}
 
 \subsection{Mathematical Operators}
 
@@ -115,6 +115,7 @@ Mathematical operators operate on expressions that returns numeric value only, e
 \begin{tabulary}{\textwidth}{CLL}
 Code & Operation & Result \\
 \hline
+\emph{x} $=$ \emph{y} & Assignment & Assigns \emph{y} into \emph{x} \\
 \emph{x} $\basicexp$ \emph{y} & Exponentiation & \emph{x} raised to the \emph{y}th power \\
 \emph{x} $\ast$ \emph{y} & Multiplication & Product of \emph{x} and \emph{y} \\
 \emph{x} $/$ \emph{y} & Division & Quotient of \emph{x} and \emph{y} \\
@@ -124,19 +125,22 @@ Code & Operation & Result \\
 \emph{x} $-$ \emph{y} & Subtraction & Difference of \emph{x} and \emph{y} \\
 $+$ \emph{x} & Unary Plus & Value of \emph{x} \\
 $-$ \emph{x} & Unary Minus & Negative value of \emph{x} \\
+\emph{x} \condensedfont{MIN} \emph{y} & Minimum & Lesser value of two \\
+\emph{x} \condensedfont{MAX} \emph{y} & Maximum & Greater value of two \\
+
 \end{tabulary}
 
 \subsubsection*{Notes}
-\begin{itemize}
+\begin{itemlist}
 \item Type conversion rule follows underlying Javascript implementation. In other words, \emph{only the god knows.}
 \item The expression \code{0\basicexp 0} will return \code{1}, even though the expression is indeterminant.
-\end{itemize}
+\end{itemlist}
 
 \subsubsection*{Errors}
-\begin{itemize}
+\begin{itemlist}
 \item Any expression that results \code{NaN} or \code{Infinity} in Javascript will return some kind of errors, mainly \code{Division by zero}.
 \item If \code{\emph{x}<0} and \code{\emph{y}} is not integer, \code{\emph{x}\basicexp\emph{y}} will raise \code{Illegal function call}.
-\end{itemize}
+\end{itemlist}
 
 \subsection{Comparison Operators}
 
@@ -155,19 +159,21 @@ Code & Operation & Result \\
 
 When comparing strings, the ordering is as follows:
 
-\begin{itemize}
+\begin{itemlist}
 \item Two strings are equal only when they are of the same length and every codepoint of the first string is identical to that of the second. This includes any whitespace or unprintable characters. 
 \item Each character position of the string is compared starting from the leftmost character. When a pair of different characters is encountered, the string with the character of lesser codepoint is less than the string with the character of greater codepoint. 
 \item If the strings are of different length, but equal up to the length of the shorter string, then the shorter string is less than the longer string.
-\end{itemize}
+\end{itemlist}
 
 \subsection{Bitwise Operators}
 
-Bitwise operators operate on integers only. Floating points are truncated\footnote{truncated towards zero} to integers.
+Bitwise operators operate on unsigned integers only. Floating points are truncated\footnote{truncated towards zero} to integers.
 
 \begin{tabulary}{\textwidth}{CLL}
 Code & Operation & Result \\
 \hline
+\emph{x}  <\!< \emph{y} & Bitwise Shift Left & Shifts entire bits of \emph{x} by \emph{y} \\
+\emph{x}  >\!> \emph{y} & Bitwise Shift Right & Shift entire bits \emph{x} by \emph{y}, including sign bit \\
 \condensedfont{BNOT} \emph{x} & Ones' complement & $-\emph{x}-1$ \\
 \emph{x}  \condensedfont{BAND} \emph{y} & Bitwise conjunction & Bitwise AND of \emph{x} and \emph{y} \\
 \emph{x}  \condensedfont{BOR} \emph{y} & Bitwise disjunction & Bitwise OR of \emph{x} and \emph{y} \\
@@ -176,7 +182,7 @@ Code & Operation & Result \\
 
 \subsection{Boolean Operators}
 
-Boolean operators operate on boolean values. If one of the operand is not boolean, it will be cast to appropriate boolean value. See \ref{valuesandtypes}
+Boolean operators operate on boolean values. If one of the operand is not boolean, it will be cast to appropriate boolean value. See \ref{valuesandtypes} for casting rules.
 
 \begin{tabulary}{\textwidth}{CLL}
 Code & Operation & Result \\
@@ -186,6 +192,17 @@ Code & Operation & Result \\
 \emph{x} \condensedfont{OR} \emph{y} & Bitwise disjunction & True if \emph{x} or \emph{y} is true, or  both are true \\
 \end{tabulary}
 
+\subsection{Generator Operators}
+
+Generator operators operate on numeric values and generators to create and modify a generator.
+
+\begin{tabulary}{\textwidth}{CLL}
+Code & Result \\
+\hline
+\emph{x} \condensedfont{TO} \emph{y} & Creates an generator that counts from \emph{x} to \emph{y} \\
+\emph{x} \condensedfont{STEP} \emph{y} & Modifies an counting stride of the generator \emph{x} into \emph{y} \\
+\end{tabulary}
+
 \subsection{Array Operators}
 
 Array operators operate on arrays and numeric values.

assets/tbas/doc/statements.tex

@@ -1 +1,47 @@
-IF DEFUN ON
+\label{statements}
+
+A Program line is composed of a line number and one or more statements. Multiple statements are separated by colons \code{:}.
+
+\section{IF}
+
+\codeline{\textbf{IF} TRUTH\_VALUE \textbf{THEN} TRUE\_EXPRESSION [\textbf{ELSE} FALSE\_EXPERSSION]}
+
+If \code{TRUTH\_VALUE} is truthy, executes \code{TRUE\_EXPRESSION}; if \code{TRUTH\_VALUE} is falsy and \code{FALSE\_EXPERSSION} is used, executes that expression, otherwise next line or next statement will be executed.
+
+\subsubsection*{Notes}
+
+\begin{itemlist}
+\item \codebf{IF} is both statement and expression. You can use IF-clause after \codebf{ELSE}, or within functions as well, for example.
+\item \codebf{THEN} is \emph{not} optional, this behaviour is different from most of the BASIC dialects.
+\item Also unlike the most dialects, \codebf{GOTO} cannot be omitted; doing so will make the number be returned to its parent expression.
+\end{itemlist}
+
+\section{ON}
+
+\codeline{\textbf{ON} INDEX\_EXPRESSION \{\textbf{GOTO}|\textbf{GOSUB}\} LINE0 [\textbf{,} LINE1]...}
+
+Jumps to \code{INDEX\_EXPRESSION}-th line number in the argements. If \code{INDEX\_EXPRESSION} is outside of range of the arguments, no jump will be performed.
+
+\subsubsection*{Parametres}
+
+\begin{itemlist}
+\item \code{LINEn} can be a number, numeric expression (aka equations) or a line label.
+\item When \code{OPTIONBASE 1} is used within the program, \code{LINEn} starts from 1 instead of 0.
+\end{itemlist}
+
+\section{DEFUN}
+
+\emph{There it is, the} DEFUN. \emph{All those new-fangled parser\footnote{a computer program that translates program code entered by you into some data bits that only it can understand} and paradigms\footnote{a guidance to in which way you must think to assimilate your brain into the computer-overlord} are tied to this very statement on \tbas{}, and only Wally knows its secrets\ldots}
+
+\codeline{\textbf{DEFUN} NAME \textbf{(} [ARGS0 [\textbf{,} ARGS1]...] \textbf{)} \textbf{=} EXPRESSION }
+
+With the aid of other statements\footnote{Actually, only the IF is useful, unless you want to \emph{transcend} from the \emph{dung} of mortality by using DEFUN within DEFUN (a little modification of the source code is required)} and functions, DEFUN will allow you to ascend from traditional BASIC and do godly things such as \emph{recursion}\footnote{see recursion} and \emph{functional programming}.
+
+Oh, and you can define your own function, in traditional \code{DEF FN} sense.
+
+\subsubsection*{Parametres}
+
+\begin{itemlist}
+\item \code{NAME} must be a valid variable name
+\item \code{ARGSn} must be valid variable names, but can be a name of variables already used within the BASIC program; their value will not be affected nor be used
+\end{itemlist}

assets/tbas/doc/tbasman.tex

@@ -47,6 +47,8 @@
 \setlength{\parskip}{\mytextsize}
 \setsecnumdepth{subsection}
 
+%% More compact itemize %%
+\newenvironment{itemlist}{\vspace{0pt}\itemize}{\enditemize}
 
 %% Idioms %%
 \hyphenation{Java-scr-ipt}
@@ -65,6 +67,10 @@
 %\let\oldsection\chapter
 %\renewcommand\chapter{\clearpage\oldsection}
 
+% shorten spaces before section header
+\setbeforesubsecskip{\mytextsize}
+\setbeforesubsubsecskip{\mytextsize}
+
 % chapter title -- no now page after
 \renewcommand\chapterheadstart{} % kill the drop
 \renewcommand\afterchapternum{\vskip 0.5em} % space between number and title
@@ -122,6 +128,7 @@
 
 % The title
 \newcommand{\tbas}{Terran BASIC}
+\newcommand{\thismachine}{TSVM}
 \newcommand{\tbasver}{1.0}
 \newcommand{\theedition}{First Edition}
 \newcommand{\oreallypress}{\large\textbf{O'REALLY\raisebox{1ex}{\scriptsize ?}} \normalsize Press}

assets/tbas/parser_wip.js

@@ -4,6 +4,7 @@ class ParserError extends Error {
         Error.captureStackTrace(this, ParserError);
     }
 }
+var DEFUNS_BUILD_DEFUNS = false;
 let bF = {};
 bF.parserPrintdbg = any => serial.println(any);
 bF.parserPrintdbg2 = function(icon, lnum, tokens, states, recDepth) {
@@ -173,7 +174,7 @@ bF._parseStmt = function(lnum, tokens, states, recDepth) {
 
         treeHead.astValue = "DEFUN";
         treeHead.astType = "function";
-        
+
         // parse function name
         if (tokens[1] == "(") {
             // anonymous function
@@ -185,21 +186,22 @@ bF._parseStmt = function(lnum, tokens, states, recDepth) {
             bF.parserPrintdbgline('$', 'DEFUN Stmt Function Name:', lnum, recDepth);
             treeHead.astLeaves[0] = bF._parseIdent(lnum, [tokens[1]], [states[1]], recDepth + 1);
         }
-        
+
         // parse function arguments
         bF.parserPrintdbgline('$', 'DEFUN Stmt Function Arguments -- ', lnum, recDepth);
         let defunArgDeclSeps = sepsOne.filter((i) => i < parenEnd + 1).map(i => i-1).concat([parenEnd - 1]);
         bF.parserPrintdbgline('$', 'DEFUN Stmt Function Arguments comma position: '+defunArgDeclSeps, lnum, recDepth);
 
         treeHead.astLeaves[0].astLeaves = defunArgDeclSeps.map(i=>bF._parseIdent(lnum, [tokens[i]], [states[i]], recDepth + 1));
-        
+
         // parse function body
-        treeHead.astLeaves[1] = bF._parseExpr(lnum,
+        let parseFunction = (DEFUNS_BUILD_DEFUNS) ? bF._parseStmt : bF._parseExpr;
+        treeHead.astLeaves[1] = parseFunction(lnum,
             tokens.slice(parenEnd + 2, tokens.length),
             states.slice(parenEnd + 2, states.length),
             recDepth + 1
         );
-        
+
         return treeHead;
     }