Taylor Venable avatar Taylor Venable committed 6042c39

Add s4cola documentation in TeX format.

Comments (0)

Files changed (2)

+\documentclass[10pt]{article}
+\usepackage{tcvmisc,tcvprgm}
+
+\usepackage[rm=charis,sf=heros,tt=consolas]{tcvfaces}
+\usepackage{polyglossia}
+\setdefaultlanguage{english}
+
+\usepackage{mdwlist}
+\usepackage{expdlist}
+
+%% INDEXING
+
+\usepackage{makeidx}
+\makeindex
+
+\SetPageStyle{Taylor Venable}{\texttt{s4cola}}
+
+\usepackage{hyperref}
+\hypersetup{colorlinks,linkcolor=black,urlcolor=niceblue}
+
+\begin{document}
+
+\title{\texttt{s4cola}\\\large A Safe, Simple, Sizable, Stretchy Command Language}
+\author{Taylor Venable\\\normalsize\href{mailto:taylor@metasyntax.net}{taylor@metasyntax.net}}
+\maketitle
+
+\begingroup
+\sffamily
+\begin{abstract}\footnotesize
+\end{abstract}
+\endgroup
+
+\thispagestyle{empty}
+\tableofcontents
+\newpage
+
+\section{Design Goals}
+
+The purpose of the \texttt{s4cola} language is to provide a stable, easy-to-use platform for
+scripting functions, particularly in the domain of system maintenance tasks.  The idea is to fill a
+role similar to that of shell scripts, Tcl, awk, and to a slightly different end, Perl.  The
+specific objectives are enumerated in the name, so let's examine them in detail.
+
+\subsection{Safety}
+
+\texttt{s4cola} provides an variety of safety features to help prevent common programming errors.
+It has automatic memory management, including buffer and initialization checks.  It has a very
+limited but extensible type system.
+
+\subsection{Simple}
+
+The core tenets of \texttt{s4cola} are very easy to understand.  There are a small set of
+fundamental data structures.  There are commands.  The first word of every line is the command to
+execute.
+
+\subsection{Sizable}
+
+Just because \texttt{s4cola} is simple does not mean it is incomplete.  Since it's meant to be a
+general purpose system language, \texttt{s4cola} includes libraries to manipulate strings (like
+regexps), files (like filesystem operations), and data structures (like maps, trees, and more).
+
+\subsection{Stretchy}
+
+The language itself is extensible.  It's very easy to define new commands, and since they're invoked
+like every other command, they instantly become a part of the your command library.  Hierarchical
+modules provide a way to organize new commands.
+
+\section{Syntax}
+
+The syntax of a language is the first and most common thing a user sees.  It's also part of the
+strength of the language.
+
+\subsection{Symbols}
+
+A symbol consists of any ``bare word'' standing alone.  As consumed by the reader, a symbol must not
+start with a number, minus, or plus symbol (as this conflicts with the syntax for a number).
+However, it is possible to construct symbols starting with these characters using the [sym] command,
+which creates a symbol from a string.  Symbols are names, for variables and commands.  There are
+some conventions you should consider following when using symbols:
+
+\begin{description}[\setleftmargin{6pc}]
+\item[variables] Start with an upper-case letter, and use ``CamelCase.''  The use of upper-case for
+  variables is inspired primarily by Erlang.
+  \begin{itemize*}
+  \item \texttt{Index}
+  \item \texttt{FirstName}
+  \end{itemize*}
+\item[constants] Are written in all upper case using underscores as word separators.  These are
+  meant to be visually distinct from the surrounding text.
+  \begin{itemize*}
+  \item \texttt{PI}
+  \item \texttt{MAX\_ENTRIES}
+  \end{itemize*}
+\item[commands] Use all lower-case with an underscore for a separator.
+  \begin{itemize*}
+  \item \texttt{delete}
+  \item \texttt{find\_string}
+  \end{itemize*}
+\end{description}
+
+\subsection{Integers}
+
+An integer is any number without a fractional component, positive or negative.
+
+\begin{itemize*}
+\item \verb|3|
+\item \verb|1024|
+\item \verb|-42|
+\item \verb|+76|
+\end{itemize*}
+
+\subsection{Real Numbers}
+
+Real numbers contain a fractional part, and must include a decimal.  Numbers before or after the
+decimal point are optional, but for clarity you must have at least one on at least one side.
+
+\begin{itemize*}
+\item \verb|7.2|
+\item \verb|-13.95|
+\item \verb|2.|
+\item \verb|.8|
+\end{itemize*}
+
+\subsection{Interpolated Strings}
+
+Strings subject to interpolation (see below) are enclosed as usual in double quotes.
+
+\begin{itemize*}
+\item \verb|"guten Tag"|
+\item \verb|"Hello, $(name)"|
+\end{itemize*}
+
+\subsubsection{Spliced Interpolation}
+
+Splicing interpolation is used to expand a list into multiple arguments \textit{before} a command
+line is processed.  Both commands and values can be interpolated.  When \verb|@()| is used, the
+supplied symbol is treated as a variable name, and the list value of the variable is interpolated
+into the command arguments (if the value is not a list, an error occurs).  When \verb|@[]| is used,
+the contents are treated as a command line which is executed, the list return result of which is
+spliced into the surrounding command sequence (again, if the result is not a list then an error
+occurs).
+
+\begin{itemize*}
+\item \verb|math:add @(args)                  (* splice variable *)|
+\item \verb|math:add @[read]                  (* splice command *)|
+\end{itemize*}
+
+The idea of spliced interpolation comes from Tcl's \verb|{*}| operator.  This is one of a very small
+number of unique syntaxes in Tcl; the equivalent in \texttt{s4cola} is de-emphasized and made to be
+visually similar to the direct interpolation syntax.
+
+\subsubsection{Direct Interpolation}
+
+This is the typical variable insertion.  Lists stay lists, and other return types remain the way
+they were returned.
+
+\begin{itemize*}
+\item \verb|print $(msg)                      (* interpolate variable *)|
+\item \verb|print $[read]                     (* interpolate command *)|
+\end{itemize*}
+
+\subsection{Verbatim Strings}
+
+Verbatim strings do not enjoy interpolation.  They are enclosed in matching curly braces.
+
+\begin{itemize*}
+\item \verb|{some text here}|
+\item \verb|{$(foo) $[bar] @(alpha) @[beta]}|
+\end{itemize*}
+
+Verbatim strings are typically used to employ ``scripts'' which are just strings that are evaluated
+by the interpreter as requested by a command.  The syntax is meant to emulate a block of source code
+from a language like C, C++, or Java; where curly braces creates blocks with local scopes.  Since
+these are not syntactic elements in \texttt{s4cola}, scoping is handled differently (see
+\PageRef{sec:scoping}).
+
+\subsection{Lists}
+
+A list consists of a sequence of space-separated items.  The items of a list must all be the same
+type.  Lists are delimited by matching square brackets.
+
+\begin{itemize*}
+\item \verb|[]                                (* a' list *)|
+\item \verb|[foo]                             (* symbol list *)|
+\item \verb|["one" "two"]                     (* string list *)|
+\item \verb|[1 2 3 4]                         (* integer list *)|
+\item \verb|[[1 2] [3 4]]                     (* list list *)|
+\end{itemize*}
+
+Note that we borrow ML's polymorphic type syntax to refer to a type which isn't fully decided.  A
+type of \verb|a' list| is some kind of list, although what specifically we don't (yet) know.
+Although the syntax is the same, the concept is still at this phase of design different.
+
+\subsection{Tuples}
+
+A tuple is a kind of structured data.  Tuples can contain any types.
+
+\begin{itemize*}
+\item \verb|< name "taylor" age 25 >|
+\item \verb|< foo bar 1776 >|
+\end{itemize*}
+
+The type of a tuple is decided spontaneously per each value created.  It is written a style similar
+to that used by ML, but with angle brackets.  For the above two values, the types are:
+
+\begin{itemize*}
+\item \verb|<symbol * string * symbol * int>|
+\item \verb|<symbol * symbol * int>|
+\end{itemize*}
+
+\subsection{Namespaces}
+
+To facilitate libraries and splitting apart code, namespaces isolate commands and variables.
+(Namespaces are identified by symbols.)  To call a command from another namespace, separate them
+with a colon.  To indicate namespaces in a hierarchy, just keep joining them together; the last
+symbol in the sequence names the command.
+
+\begin{itemize*}
+\item \verb|math:sin 3.14|
+\item \verb|net:socket:listen -addr 0.0.0.0 80|
+\end{itemize*}
+
+\section{Usage}
+
+\subsection{Namespaces}
+
+\subsubsection{Members}
+
+A member is a value which is bound to a name (colloquially, a variable) within a namespace.  They
+can be configured to support various levels of protection from other namespaces.  Members are
+created with the \texttt{member} command.
+
+\cmd{member}{}{\flag*[p]{protection} \var{name} \var*{value}}
+\begin{params}{6pc}
+\item[\var{p}] A list of tuples of protection options; the first element of the tuple is the
+  visibility level (private or public), and the second element is the access (read or write).  The
+  default private visibility is write, and the default public visibility is none.  Some examples:
+  \begin{itemize*}
+  \item \verb|-protection [<private read>]|
+  \item \verb|-protection [<private write> <public write>]|
+  \end{itemize*}
+\item[\var{name}] The binding name of the value.
+\item[\var{value}] Initial value of the binding.  If no visibility level can write to the member,
+  then the member becomes immutable with this value; essentially a constant.
+\end{params}
+
+\appendix
+\printindex
+\end{document}
+$pdflatex = "xelatex %O %S";
+$pdf_mode = 1;
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.