(⬑Central s2 Documentation Hub)

Table of Contents for the s2 manual...

In December 2019, the massive s2 manuals were ported from very nearly 200 pages of GoogleDocs, with more than 5 years of accumulated text, to markdown format for embedding directly in the source repository. Welcome to that markdown...

This set of documents cover essentially every aspect of working with s2, from its grammar to plugging it in to C/C++ code, to tips for using and abusing its strengths and weaknesses.

These docs get updated as the code is written, so they always reflect the current trunk state, plus or minus half a day.

Prologue

• Brief Introduction to/Overview of s2, including download/installation instructions.
• Symbol Resolution (READ THIS!!!). [Potential] Users really need to understand this unusual aspect of s2. It's in its own file, separated out from the "yeah, yeah, we know this stuff" parts of the docs for a reason.

Grammar

grammar.md covers...

• Grammar/Scripting-related Terminology
• Anatomy of an Expression
• Identifiers and Strings
• Built-in Constants
• Scopes/Scoping in s2
• Error Types: Script-fatal vs. Catchable

Related topics which live in their own pages:

• Operators
• Keywords, including flow control constructs: loops and if/else.

Data Types

• Intro & Basics: Overview of the types/type system
• Strings: UTF-8
• Numbers: Integers and Doubles
• Objects: General-purpose containers
• Arrays: Heterogenous lists
• Tuples: Feature-light/weight-light arrays
• Functions: Ya call() 'em!
• Exceptions: Error-reporting objects
• Hashtables: High-speed key/value storage
• Buffers: Work with binary data or dynamic strings
• Enums: Fixed/immutable property sets
• PathFinder: A search-for-files utility

Misc. Features & APIs

• Disabling Filesystem Access
• Loadable Modules
• JSON API
• I/O-related API
• Filesystem-related API
• Time-related API
• Output Buffering (OB) API
• Scriptable Text Templates: s2.tmpl()
• Capping s2 Memory Usage

The s2 shell - s2sh

• s2sh is "the" app for running s2 code. It also acts as:
  • A demo client for how to embed s2.
  • A customizable basis for creating client-extended s2 shell apps.
• s2sh2 is a slightly modernized rework of s2sh, more refined in some regards.
• S2_HOME is a concept closely related to s2sh.
• Building a static s2sh with Docker.

Using s2 in C/C++

• Embedding and Extending s2 from C/C++
• Extending s2sh

If it Doesn't Fit Elsewhere, it's Probably Here...

• Known Misbehaviours
• Incompatible Changes
• Script Snippets demonstrating various bits and pieces.
• The Workshop describes experimental & in-development features.
• Tips and Tricks for making good use of s2.
• TODOs: Potential and "Definite"
• More than anyone needs to know about s2 internals (other than myself, of course).
• Retrospective 2019 - looking back at 5.5-ish years of s2.
• Doc Maintenance Notes - reminders to self.
• Essay: Parsing Parentheses - because s2's approach is "interestingly unconventional."
• s2 v2 - if version 2 ever happens, this is what will change.