basicdoc: wip

assets/disk0/home/basic/sqrt.bas

@@ -1,7 +1,10 @@
 1 REM Calculates a square root using newtonian method
-20 INPUT X
+10 INPUT X
-30 Y = 0.5 * X
+11 IF TYPEOF(X)=="num" THEN GOTO 20
-40 Z = Y
+12 PRINT "Please type in a number, please";
-50 Y = Y-(((Y^2)-X)/(2*Y))
+13 GOTO 10
-60 IF Z <> Y THEN GOTO 40
+20 Y = 0.5 * X
+30 Z = Y
+40 Y = Y-(((Y^2)-X)/(2*Y))
+50 IF Z <> Y THEN GOTO 30
 100 PRINT "Square root of ";X;" is approximately ";Y

assets/disk0/tbas/doc/functions.tex

@@ -99,11 +99,11 @@ Functions are a form of expression that may taks input arguments surrounded by p
 \section{Output}
 
     \subsection{EMIT}
-        \codeline{\textbf{EMIT(}EXPR [\{\textbf{,}|\textbf{;}\} EXPR]\ldots\textbf{)}}\par
+        \codeline{\textbf{EMIT(} EXPR [\{\textbf{,}|\textbf{;}\} EXPR]\ldots\ \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]\ldots\textbf{)}}\par
+        \codeline{\textbf{PRINT(} EXPR [\{\textbf{,}|\textbf{;}\} EXPR]\ldots\ \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.
@@ -155,38 +155,38 @@ Functions are a form of expression that may taks input arguments surrounded by p
         \codeline{CHAR \textbf{= CHR(}X\textbf{)}}\par
         Returns the character with code point of \code{X}. Code point is a numeric expression in the range of $[0-255]$.
     \subsection{LEFT}
-        \codeline{SUBSTR \textbf{= LEFT(}STR \textbf{,} NUM\_CHARS\textbf{)}}\par
+        \codeline{SUBSTR \textbf{= LEFT(} STR \textbf{,} NUM\_CHARS \textbf{)}}\par
         Returns the leftmost \code{NUM\_CHARS} characters of \code{STR}.
     \subsection{MID}
-        \codeline{SUBSTR \textbf{= MID(}STR \textbf{,} POSITION \textbf{,} LENGTH\textbf{)}}\par
+        \codeline{SUBSTR \textbf{= MID(} STR \textbf{,} POSITION \textbf{,} LENGTH \textbf{)}}\par
         Returns a substring of \code{STR} starting at \code{POSITION} with specified \code{LENGTH}.\par
         When \code{OPTIONBASE 1} is specified, the position starts from 1; otherwise it will start from 0. 
     \subsection{RIGHT}
-        \codeline{SUBSTR \textbf{= RIGHT(}STR \textbf{,} NUM\_CHARS\textbf{)}}\par
+        \codeline{SUBSTR \textbf{= RIGHT(} STR \textbf{,} NUM\_CHARS \textbf{)}}\par
         Returns the rightmost \code{NUM\_CHARS} characters of \code{STR}.
     \subsection{SPC}
-        \codeline{STR \textbf{= SPC(}STR \textbf{,} NUM\_CHARS\textbf{)}}\par
+        \codeline{STR \textbf{= SPC(} STR \textbf{,} NUM\_CHARS \textbf{)}}\par
         Returns a string of \code{NUM\_CHARS} spaces.
 
 \section{Array Manipulation}
         
     \subsection{HEAD}
-        \codeline{K \textbf{= HEAD(}ARRAY\textbf{)}}\par
+        \codeline{K \textbf{= HEAD(}X\textbf{)}}\par
-        Returns the head element of the given array.
+        Returns the head element of the array \code{X}.
     \subsection{INIT}
-        \codeline{K \textbf{= INIT(}ARRAY\textbf{)}}\par
+        \codeline{K \textbf{= INIT(}X\textbf{)}}\par
-        Returns the new array that has its last element removed.
+        Constructs the new array from array \code{X} that has its last element removed.
     \subsection{LAST}
-        \codeline{K \textbf{= LAST(}ARRAY\textbf{)}}\par
+        \codeline{K \textbf{= LAST(}X\textbf{)}}\par
-        Returns the last element of the given array.
+        Returns the last element of the array \code{X}.
     \subsection{TAIL}
-        \codeline{K \textbf{= TAIL(}ARRAY\textbf{)}}\par
+        \codeline{K \textbf{= TAIL(}X\textbf{)}}\par
-        Returns the new array that has its head element removed.
+        Constructs the new array from array \code{X} that has its head element removed.
         
 \section{Graphics}
 
     \subsection{PLOT}
-        \codeline{\textbf{PLOT(}X\_POS \textbf{,} Y\_POS \textbf{,} COLOUR\textbf{)}}\par
+        \codeline{\textbf{PLOT(} X\_POS \textbf{,} Y\_POS \textbf{,} COLOUR \textbf{)}}\par
         Plots a pixel to the framebuffer of the display, at XY-position of \code{X\_POS} and \code{Y\_POS}, with colour of \code{COLOUR}.\par
         Top-left corner of the pixel will be 1 if \code{OPTIONBASE 1} is specified; otherwise it will be 0.
 
@@ -201,24 +201,50 @@ Functions are a form of expression that may taks input arguments surrounded by p
     \subsection{OPTIONTRACE}
         \codeline{\textbf{OPTIONTRACE} \{\textbf{0}|\textbf{1}\}}\par
         Specifies whether or not the line numbers should be printed out. The messages will be printed out to the \emph{serial debugging console}, or to the stdout.
+    \subsection{TYPEOF}
+        \codeline{X \textbf{= TYPEOF(} VALUE \textbf{)}}\par
+        Returns a type of given value.\par
+        \begin{longtable}{*{2}{m{\textwidth}}}\hline
+        \endfirsthead
+        \endhead
 
+        \endfoot
+        \hline
+        \endlastfoot
+        \centering
+        \begin{tabulary}{\textwidth}{rl}
+        BASIC Type & Returned Value \\
+        \hline
+        Number & \ttfamily{num} \\
+        Boolean & \ttfamily{bool} \\
+        String & \ttfamily{str} \\
+        \end{tabulary}
+        \begin{tabulary}{\textwidth}{rl}
+        BASIC Type & Returned Value \\
+        \hline
+        Array & \ttfamily{array} \\
+        Generator & \ttfamily{generator} \\
+        User Function & \ttfamily{usrdefun}
+        \end{tabulary}
+        \end{longtable}
+    
 \section{System}
 
     \subsection{PEEK}
-        \codeline{BYTE \textbf{= PEEK(}MEM\_ADDR\textbf{)}}\par
+        \codeline{BYTE \textbf{= PEEK(} MEM\_ADDR \textbf{)}}\par
         Returns whatever the value stored in the \code{MEM\_ADDR} of the Scratchpad Memory.\par
         Address mirroring, illegal access, etc. are entirely up to the virtual machine which the BASIC interpreter is running on.
     \subsection{POKE}
-        \codeline{\textbf{POKE(}MEM\_ADDR \textbf{,} BYTE\textbf{)}}\par
+        \codeline{\textbf{POKE(} MEM\_ADDR \textbf{,} BYTE \textbf{)}}\par
         Puts a \code{BYTE} into the \code{MEM\_ADDR} of the Scratchpad Memory.
 
 \section{Higher-order Function}
 
     \subsection{DO}
-        \codeline{\textbf{DO(}EXPR0 [\textbf{;} EXPR1]\ldots\textbf{)}}\par
+        \codeline{\textbf{DO(} EXPR0 [\textbf{;} EXPR1]\ldots\ \textbf{)}}\par
         Executes \code{EXPRn}s sequentially.
     \subsection{FILTER}
-        \codeline{NEWLIST \textbf{= FILTER(}FUNCTION \textbf{,} ITERABLE\textbf{)}}\par
+        \codeline{NEWLIST \textbf{= FILTER(} FUNCTION \textbf{,} ITERABLE \textbf{)}}\par
         Returns an array of values from the \code{ITERABLE} that passes the given function. i.e. values that makes \code{FUNCTION(VALUE\_FROM\_ITERABLE)} true.
         \subsubsection*{Parameters}
         \begin{itemlist}
@@ -226,14 +252,14 @@ Functions are a form of expression that may taks input arguments surrounded by p
         \item \code{ITERABLE} is either an array or a generator.
         \end{itemlist}
     \subsection{FOLD}
-        \codeline{NEWVALUE \textbf{= FOLD(}FUNCTION \textbf{,} INIT\_VALUE \textbf{,} ITERABLE\textbf{)}}\par
+        \codeline{NEWVALUE \textbf{= FOLD(} FUNCTION \textbf{,} INIT\_VALUE \textbf{,} ITERABLE \textbf{)}}\par
         Iteratively applies given function with accumulator and the value from the \code{ITERABLE}, returning the final accumulator. Accumulator will be set to \code{INIT\_VALUE} before iterating over the iterable. In the first execution, the accumulator will be set to \code{ACC=FUNCTION(ACC,ITERABLE(0))}, and the execution will continue to remaining values within the iterable until all values are consumed. The \code{ITERABLE} will not be modified after the execution.
         \subsubsection*{Parameters}
         \begin{itemlist}
         \item \code{FUNCTION} is a user-defined function with two parameters: first parameter being accumulator and second being a value.
         \end{itemlist}
     \subsection{MAP}
-        \codeline{NEWLIST \textbf{= MAP(}FUNCTION \textbf{,} ITERABLE\textbf{)}}\par
+        \codeline{NEWLIST \textbf{= MAP(} FUNCTION \textbf{,} ITERABLE \textbf{)}}\par
         Applies given function onto the every element in the iterable, and returns an array that contains such items. i.e. returns tranformation of \code{ITERABLE} of which the transformation is \code{FUNCTION}. The \code{ITERABLE} will not be modified after the execution.
         \subsubsection*{Parameters}
         \begin{itemlist}

assets/disk0/tbas/doc/langguide.tex

@@ -13,12 +13,28 @@ Ok
 Oh \emph{boy} we just did a computation! It printed out \code{4} which is a correct answer for $2+2$ and it didn't crash!
 
 \section[GOTO]{GOTO here and there}
+
+\code{GOTO} is used a lot in BASIC, and so does in \tbas. \code{GOTO} is a simplest method of diverging a program flow: execute only the some part of the program conditionally and perform a loop.
+
+Following program attempts to calculate a square root of the input value,  showing how \code{GOTO} can be used in such manner.
+
+\begin{lstlisting}
+10 X = 1337
+20 Y = 0.5 * X
+30 Z = Y
+40 Y = Y-(((Y^2)-X)/(2*Y))
+50 IF Z <> Y THEN GOTO 30
+100 PRINT "Square root of ";X;" is approximately ";Y
+\end{lstlisting}
+
+Here, \code{GOTO} in line 50 to perform a loop, which keep loops until \code{Z} and \code{Y} becomes equal. This is a newtonian method of approximating a square root. 
+
 \section[When GOTO Is Bad]{Severe Acute Spaghettification Syndrome}
 \section[Subroutine with GOSUB]{GOSUB to the rescue!}
 
 \section[FOR--NEXT Loop]{FOR ever loop NEXT}
 
-So you can make a loop using \code{GOTO}s here and there, but they \emph{totally suck}. Fortunately, there's better way to go about that: the FOR--NEXT loop!
+So you can make a loop using \code{GOTO}s here and there, but they \emph{totally suck}, too much spaphetti crashes your cerebral cortex faster than \emph{Crash Bandicoot 2}. Fortunately, there's better way to go about that: the FOR--NEXT loop!
 
 \begin{lstlisting}
 10 FOR I = 1 TO 20
@@ -29,6 +45,8 @@ So you can make a loop using \code{GOTO}s here and there, but they \emph{totally
 60 NEXT
 \end{lstlisting}
 
+When executed, this program print out triangles of stars. Still not convinced? Try to write a same program with \code{GOTO}s.
+
 \section[Get User INPUT]{Isn't It Nice To Have a Computer That Will Question You?}
 
 What fun is the program if it won't talk with you? You can make that happen with \code{INPUT} statement.
@@ -60,34 +78,51 @@ Lo and behold, the \code{DEFUN}! You can define a \emph{function} in a single li
 
 \section[Recursion]{BRB: Bad Recursion BRB: Bad Recursion BRB: Bad Recursion BRB: Bad RecursionBRB: Bad Recursion BRBRangeError: Maximum call stack size exceeded}
 
-But don't get over-excited, as it's super-trivial to create unintentional infinite loop.
+But don't get over-excited, as it's super-trivial to create unintentional infinite loop:
 
 \begin{lstlisting}
-10 DEFUN ENDLESS(SHIT)=ENDLESS(SHIT)
+10 DEFUN FAC(N)=N*FAC(N-1)
-20 ENDLESS(1)
-\end{lstlisting}
-
-\begin{lstlisting}
-10 DEFUN FAC(N)=IF N==0 THEN 1 ELSE N*FAC(N-1)
 20 FOR K=1 TO 6
 30 PRINT FAC(K)
 40 NEXT
 \end{lstlisting}
 
+(if you tried this and computer becomes unresponsive, hit Ctrl-C to terminate the execution)
+
+This failed attempt is to create a function that calculates a factorial of \code{N}. It didn't work because there is no \emph{halting condition}: didn't told computer to when to escape from the loop.
+
+$n \times 1$ is always $n$, and $0!$ is $1$, so it would be nice to break out of the loop when \code{N} reaches $0$; here is the modified program:
+
 \begin{lstlisting}
 10 DEFUN FAC(N)=IF N==0 THEN 1 ELSE N*FAC(N-1)
-20 K=MAP FAC, 1 TO 10
+20 FOR K=1 TO 10
-30 PRINT K
+30 PRINT FAC(K)
+40 NEXT
 \end{lstlisting}
 
+Since \code{IF-THEN-ELSE} can be chained to make third or more conditions --- \code{IF-THEN-ELSE IF-THEN} or something --- we can write a recursive Fibonacci function:
 
 \begin{lstlisting}
 10 DEFUN FIB(N)=IF N==0 THEN 0 ELSE IF N==1 THEN 1 ELSE FIB(N-1)+FIB(N-2)
-20 FOR K=1 TO 12
+20 FOR K=1 TO 10
 30 PRINT FIB(K);" ";
 40 NEXT
 \end{lstlisting}
 
+\section[MAPping]{Map}
+
+\code{MAP} is a \emph{higher-order}\footnote{Higher-order function is a function that takes another function as an argument.} function that takes a function (called \emph{transformation}) and an array to construct a new array that contains old array transformed with given \emph{transformation}.
+
+Or, think about the old \code{FAC} program before: it only printed out the value of $1!$, $2!$ \ldots\ $10!$. What if we wanted to build an array that contains such values?
+
+\begin{lstlisting}
+10 DEFUN FAC(N)=IF N==0 THEN 1 ELSE N*FAC(N-1)
+20 K=MAP(FAC, 1 TO 10)
+30 PRINT K
+\end{lstlisting}
+
+Here, \code{K} will contain the values of $1!$, $2!$ \ldots\ $10!$. We're just printing out the array, but you can make acutual use out of the array.
+
 \section[Currying]{Haskell Curry Wants to Know Your Location}
 \label{currying101}