added documentation sources

doc/Makefile

@@ -0,0 +1,216 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/testy_sphinxy.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/testy_sphinxy.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/testy_sphinxy"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/testy_sphinxy"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

doc/make.bat

@@ -0,0 +1,263 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+set I18NSPHINXOPTS=%SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 1>NUL 2>NUL
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\testy_sphinxy.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\testy_sphinxy.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

doc/source/conf.py

@@ -0,0 +1,289 @@
+# -*- coding: utf-8 -*-
+#
+# Squirrel documentation build configuration file, created by
+# sphinx-quickstart on Sun Jan 31 00:26:52 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import time
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.pngmath',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Squirrel documentation'
+copyright = '2003-%s, Alberto Demichelis' % time.strftime('%Y')
+author = u'Alberto Demichelis'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'3.1'
+# The full version, including alpha/beta/rc tags.
+release = u'3.1 stable'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'squirrel_doc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+_stdauthor = r'Alberto Demichelis'
+latex_documents = [
+    ('reference/index', 'reference.tex',
+     'Squirrel Reference Manual', _stdauthor, 'manual'),
+     ('stdlib/index', 'stdlib.tex',
+     'Squirrel Standard Library', _stdauthor, 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'Squirrel', u'Squirrel Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Squirrel', u'Squirrel Documentation',
+     author, 'Squirrel', 'The Programming Language.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

doc/source/index.rst

@@ -0,0 +1,24 @@
+.. Squirrel documentation master file, created by
+   sphinx-quickstart on Sun Jan 31 00:26:52 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Squirrel's documentation
+=========================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   reference/index.rst
+   stdlib/index.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+
+

doc/source/reference/api/bytecode_serialization.rst

@@ -0,0 +1,32 @@
+.. _api_ref_bytecode_serialization:
+
+======================
+Bytecode serialization
+======================
+
+.. _sq_readclosure:
+
+.. c:function:: SQRESULT sq_readclosure(HSQUIRRELVM v, SQREADFUNC readf, SQUserPointer up)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQREADFUNC readf: pointer to a read function that will be invoked by the vm during the serialization.
+    :param SQUserPointer up: pointer that will be passed to each call to the read function
+    :returns: a SQRESULT
+
+serialize (read) a closure and pushes it on top of the stack, the source is user defined through a read callback.
+
+
+
+
+
+.. _sq_writeclosure:
+
+.. c:function:: SQRESULT sq_writeclosure(HSQUIRRELVM v, SQWRITEFUNC writef, SQUserPointer up)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQWRITEFUNC writef: pointer to a write function that will be invoked by the vm during the serialization.
+    :param SQUserPointer up: pointer that will be passed to each call to the write function
+    :returns: a SQRESULT
+    :remarks: closures with free variables cannot be serialized
+
+serializes(writes) the closure on top of the stack, the desination is user defined through a write callback.

doc/source/reference/api/calls.rst

@@ -0,0 +1,115 @@
+.. _api_ref_calls:
+
+=====
+Calls
+=====
+
+.. _sq_call:
+
+.. c:function:: SQRESULT sq_call(HSQUIRRELVM v, SQInteger params, SQBool retval, SQBool raiseerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger params: number of parameters of the function
+    :param SQBool retval: if true the function will push the return value in the stack
+    :param SQBool raiseerror: if true, if a runtime error occurs during the execution of the call, the vm will invoke the error handler.
+    :returns: a SQRESULT
+    :remarks: the function pops all the parameters and leave the closure in the stack; if retval is true the return value of the closure is pushed. If the execution of the function is suspended through sq_suspendvm(), the closure and the arguments will not be automatically popped from the stack.
+
+calls a closure or a native closure.
+
+
+
+
+
+.. _sq_getcallee:
+
+.. c:function:: SQRESULT sq_getcallee(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: a SQRESULT
+
+push in the stack the currently running closure.
+
+
+
+
+
+.. _sq_getlasterror:
+
+.. c:function:: SQRESULT sq_getlasterror(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: a SQRESULT
+    :remarks: the pushed error descriptor can be any valid squirrel type.
+
+pushes the last error in the stack.
+
+
+
+
+
+.. _sq_getlocal:
+
+.. c:function:: const SQChar * sq_getlocal(HSQUIRRELVM v, SQUnsignedInteger level, SQUnsignedInteger nseq)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQUnsignedInteger level: the function index in the calls stack, 0 is the current function
+    :param SQUnsignedInteger nseq: the index of the local variable in the stack frame (0 is 'this')
+    :returns: the name of the local variable if a variable exists at the given level/seq otherwise NULL.
+
+Returns the name of a local variable given stackframe and sequence in the stack and pushes is current value. Free variables are treated as local variables, by sq_getlocal(), and will be returned as they would be at the base of the stack, just before the real local variables.
+
+
+
+
+
+.. _sq_reseterror:
+
+.. c:function:: void sq_reseterror(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+reset the last error in the virtual machine to null
+
+
+
+
+
+.. _sq_resume:
+
+.. c:function:: SQRESULT sq_resume(HSQUIRRELVM v, SQBool retval, SQBool raiseerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQBool retval: if true the function will push the return value in the stack
+    :param SQBool raiseerror: if true, if a runtime error occurs during the execution of the call, the vm will invoke the error handler.
+    :returns: a SQRESULT
+    :remarks: if retval != 0 the return value of the generator is pushed.
+
+resumes the generator at the top position of the stack.
+
+
+
+
+
+.. _sq_throwerror:
+
+.. c:function:: SQRESULT sq_throwerror(HSQUIRRELVM v, const SQChar * err)
+
+    :param HSQUIRRELVM v: the target VM
+    :param const SQChar * err: the description of the error that has to be thrown
+    :returns: the value that has to be returned by a native closure in order to throw an exception in the virtual machine.
+
+sets the last error in the virtual machine and returns the value that has to be returned by a native closure in order to trigger an exception in the virtual machine.
+
+
+
+
+
+.. _sq_throwobject:
+
+.. c:function:: SQRESULT sq_throwobject(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: the value that has to be returned by a native closure in order to throw an exception in the virtual machine.
+
+pops a value from the stack sets it as the last error in the virtual machine. Returns the value that has to be returned by a native closure in order to trigger an exception in the virtual machine (aka SQ_ERROR).

doc/source/reference/api/compiler.rst

@@ -0,0 +1,79 @@
+.. _api_ref_compiler:
+
+========
+Compiler
+========
+
+.. _sq_compile:
+
+.. c:function:: SQRESULT sq_compile(HSQUIRRELVM v, HSQLEXREADFUNC read, SQUserPointer p, const SQChar * sourcename, SQBool raiseerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param HSQLEXREADFUNC read: a pointer to a read function that will feed the compiler with the program.
+    :param SQUserPointer p: a user defined pointer that will be passed by the compiler to the read function at each invocation.
+    :param const SQChar * sourcename: the symbolic name of the program (used only for more meaningful runtime errors)
+    :param SQBool raiseerror: if this value is true the compiler error handler will be called in case of an error
+    :returns: a SQRESULT. If the sq_compile fails nothing is pushed in the stack.
+    :remarks: in case of an error the function will call the function set by sq_setcompilererrorhandler().
+
+compiles a squirrel program; if it succeeds, push the compiled script as function in the stack.
+
+
+
+
+
+.. _sq_compilebuffer:
+
+.. c:function:: SQRESULT sq_compilebuffer(HSQUIRRELVM v, const SQChar* s, SQInteger size, const SQChar * sourcename, SQBool raiseerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param const SQChar* s: a pointer to the buffer that has to be compiled.
+    :param SQInteger size: size in characters of the buffer passed in the parameter 's'.
+    :param const SQChar * sourcename: the symbolic name of the program (used only for more meaningful runtime errors)
+    :param SQBool raiseerror: if this value true the compiler error handler will be called in case of an error
+    :returns: a SQRESULT. If the sq_compilebuffer fails nothing is pushed in the stack.
+    :remarks: in case of an error the function will call the function set by sq_setcompilererrorhandler().
+
+compiles a squirrel program from a memory buffer; if it succeeds, push the compiled script as function in the stack.
+
+
+
+
+
+.. _sq_enabledebuginfo:
+
+.. c:function:: void sq_enabledebuginfo(HSQUIRRELVM v, SQBool enable)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQBool enable: if true enables the debug info generation, if == 0 disables it.
+    :remarks: The function affects all threads as well.
+
+enable/disable the debug line information generation at compile time.
+
+
+
+
+
+.. _sq_notifyallexceptions:
+
+.. c:function:: void sq_notifyallexceptions(HSQUIRRELVM v, SQBool enable)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQBool enable: if true enables the error callback notification of handled exceptions.
+    :remarks: By default the VM will invoke the error callback only if an exception is not handled (no try/catch traps are present in the call stack). If notifyallexceptions is enabled, the VM will call the error callback for any exception even if between try/catch blocks. This feature is useful for implementing debuggers.
+
+enable/disable the error callback notification of handled exceptions.
+
+
+
+
+
+.. _sq_setcompilererrorhandler:
+
+.. c:function:: void sq_setcompilererrorhandler(HSQUIRRELVM v, SQCOMPILERERROR f)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQCOMPILERERROR f: A pointer to the error handler function
+    :remarks: if the parameter f is NULL no function will be called when a compiler error occurs. The compiler error handler is shared between friend VMs.
+
+sets the compiler error handler function

doc/source/reference/api/debug_interface.rst

@@ -0,0 +1,72 @@
+.. _api_ref_debug_interface:
+
+===============
+Debug interface
+===============
+
+.. _sq_getfunctioninfo:
+
+.. c:function:: SQRESULT sq_getfunctioninfo(HSQUIRRELVM v, SQInteger level, SQFunctionInfo * fi)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger level: calls stack level
+    :param SQFunctionInfo * fi: pointer to the SQFunctionInfo structure that will store the closure informations
+    :returns: a SQRESULT.
+    :remarks: the member 'funcid' of the returned SQFunctionInfo structure is a unique identifier of the function; this can be useful to identify a specific piece of squirrel code in an application like for instance a profiler. this method will fail if the closure in the stack is a native C closure.
+
+
+
+*.eg*
+
+::
+
+
+    typedef struct tagSQFunctionInfo {
+        SQUserPointer funcid; //unique idetifier for a function (all it's closures will share the same funcid)
+        const SQChar *name; //function name
+        const SQChar *source; //function source file name
+    }SQFunctionInfo;
+
+
+
+
+
+
+
+.. _sq_setdebughook:
+
+.. c:function:: void sq_setdebughook(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :remarks: In order to receive a 'per line' callback, is necessary to compile the scripts with the line informations. Without line informations activated, only the 'call/return' callbacks will be invoked.
+
+pops a closure from the stack an sets it as debug hook. When a debug hook is set it overrides any previously set native or non native hooks. if the hook is null the debug hook will be disabled.
+
+
+
+
+
+.. _sq_setnativedebughook:
+
+.. c:function:: void sq_setnativedebughook(HSQUIRRELVM v, SQDEBUGHOOK hook)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQDEBUGHOOK hook: the native hook function
+    :remarks: In order to receive a 'per line' callback, is necessary to compile the scripts with the line informations. Without line informations activated, only the 'call/return' callbacks will be invoked.
+
+sets the native debug hook. When a native hook is set it overrides any previously set native or non native hooks. if the hook is NULL the debug hook will be disabled.
+
+
+
+
+
+.. _sq_stackinfos:
+
+.. c:function:: SQRESULT sq_stackinfos(HSQUIRRELVM v, SQInteger level, SQStackInfos * si)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger level: calls stack level
+    :param SQStackInfos * si: pointer to the SQStackInfos structure that will store the stack informations
+    :returns: a SQRESULT.
+
+retrieve the calls stack informations of a ceratain level in the calls stack.

doc/source/reference/api/garbage_collector.rst

@@ -0,0 +1,27 @@
+.. _api_ref_garbage_collector:
+
+=================
+Garbage Collector
+=================
+
+.. _sq_collectgarbage:
+
+.. c:function:: SQInteger sq_collectgarbage(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :remarks: this api only works with gabage collector builds (NO_GARBAGE_COLLECTOR is not defined)
+
+runs the garbage collector and returns the number of reference cycles found(and deleted)
+
+
+
+
+
+.. _sq_resurrectunreachable:
+
+.. c:function:: SQRESULT sq_resurrectunreachable(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :remarks: this api only works with gabage collector builds (NO_GARBAGE_COLLECTOR is not defined)
+
+runs the garbage collector and pushes an array in the stack containing all unreachable object found. If no unreachable object is found, null is pushed instead. This function is meant to help debugging reference cycles.

doc/source/reference/api/raw_object_handling.rst

@@ -0,0 +1,163 @@
+.. _api_ref_raw_object_handling:
+
+===================
+Raw object handling
+===================
+
+.. _sq_addref:
+
+.. c:function:: void sq_addref(HSQUIRRELVM v, HSQOBJECT* po)
+
+    :param HSQUIRRELVM v: the target VM
+    :param HSQOBJECT* po: pointer to an object handler
+
+adds a reference to an object handler.
+
+
+
+
+
+.. _sq_getobjtypetag:
+
+.. c:function:: SQRESULT sq_getobjtypetag(HSQOBJECT* o, SQUserPointer* typetag)
+
+    :param HSQOBJECT* o: pointer to an object handler
+    :param SQUserPointer* typetag: a pointer to the variable that will store the tag
+    :returns: a SQRESULT
+    :remarks: the function works also with instances. if the taget object is an instance, the typetag of it's base class is fetched.
+
+gets the typetag of a raw object reference(userdata or class).
+
+
+
+
+
+.. _sq_getrefcount:
+
+.. c:function:: SQUnsignedInteger sq_getrefcount(HSQUIRRELVM v, HSQOBJECT* po)
+
+    :param HSQUIRRELVM v: the target VM
+    :param HSQOBJECT* po: object handler
+
+returns the number of references of a given object.
+
+
+
+
+
+.. _sq_getstackobj:
+
+.. c:function:: SQRESULT sq_getstackobj(HSQUIRRELVM v, SQInteger idx, HSQOBJECT* po)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger idx: index of the target object in the stack
+    :param HSQOBJECT* po: pointer to an object handler
+    :returns: a SQRESULT
+
+gets an object from the stack and stores it in a object handler.
+
+
+
+
+
+.. _sq_objtobool:
+
+.. c:function:: SQBool sq_objtobool(HSQOBJECT* po)
+
+    :param HSQOBJECT* po: pointer to an object handler
+    :remarks: If the object is not a bool will always return false.
+
+return the bool value of a raw object reference.
+
+
+
+
+
+.. _sq_objtofloat:
+
+.. c:function:: SQFloat sq_objtofloat(HSQOBJECT* po)
+
+    :param HSQOBJECT* po: pointer to an object handler
+    :remarks: If the object is an integer will convert it to float. If the object is not a number will always return 0.
+
+return the float value of a raw object reference.
+
+
+
+
+
+.. _sq_objtointeger:
+
+.. c:function:: SQInteger sq_objtointeger(HSQOBJECT* po)
+
+    :param HSQOBJECT* po: pointer to an object handler
+    :remarks: If the object is a float will convert it to integer. If the object is not a number will always return 0.
+
+return the integer value of a raw object reference.
+
+
+
+
+
+.. _sq_objtostring:
+
+.. c:function:: const SQChar* sq_objtostring(HSQOBJECT* po)
+
+    :param HSQOBJECT* po: pointer to an object handler
+    :remarks: If the object doesn't reference a string it returns NULL.
+
+return the string value of a raw object reference.
+
+
+
+
+
+.. _sq_objtouserpointer:
+
+.. c:function:: SQUserPointer sq_objtouserpointer(HSQOBJECT* po)
+
+    :param HSQOBJECT* po: pointer to an object handler
+    :remarks: If the object doesn't reference a userpointer it returns NULL.
+
+return the userpointer value of a raw object reference.
+
+
+
+
+
+.. _sq_pushobject:
+
+.. c:function:: void sq_pushobject(HSQUIRRELVM v, HSQOBJECT obj)
+
+    :param HSQUIRRELVM v: the target VM
+    :param HSQOBJECT obj: object handler
+
+push an object referenced by an object handler into the stack.
+
+
+
+
+
+.. _sq_release:
+
+.. c:function:: SQBool sq_release(HSQUIRRELVM v, HSQOBJECT* po)
+
+    :param HSQUIRRELVM v: the target VM
+    :param HSQOBJECT* po: pointer to an object handler
+    :returns: SQTrue if the object handler released has lost all is references(the ones added with sq_addref). SQFalse otherwise.
+    :remarks: the function will reset the object handler to null when it losts all references.
+
+remove a reference from an object handler.
+
+
+
+
+
+.. _sq_resetobject:
+
+.. c:function:: void sq_resetobject(HSQOBJECT* po)
+
+    :param HSQOBJECT* po: pointer to an object handler
+    :remarks: Every object handler has to be initialized with this function.
+
+resets(initialize) an object handler.

doc/source/reference/api/stack_operations.rst

@@ -0,0 +1,107 @@
+.. _api_ref_stack_operations:
+
+================
+Stack Operations
+================
+
+.. _sq_cmp:
+
+.. c:function:: SQInteger sq_cmp(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: > 0 if obj1>obj2
+    :returns: == 0 if obj1==obj2
+    :returns: < 0 if obj1<obj2
+
+compares 2 object from the stack and compares them.
+
+
+
+
+
+.. _sq_gettop:
+
+.. c:function:: SQInteger sq_gettop(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an integer representing the index of the top of the stack
+
+returns the index of the top of the stack
+
+
+
+
+
+.. _sq_pop:
+
+.. c:function:: void sq_pop(HSQUIRRELVM v, SQInteger nelementstopop)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger nelementstopop: the number of elements to pop
+
+pops n elements from the stack
+
+
+
+
+
+.. _sq_poptop:
+
+.. c:function:: void sq_poptop(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+pops 1 object from the stack
+
+
+
+
+
+.. _sq_push:
+
+.. c:function:: void sq_push(HSQUIRRELVM v, SQInteger idx)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger idx: the index in the stack of the value that has to be pushed
+
+pushes in the stack the value at the index idx
+
+
+
+
+
+.. _sq_remove:
+
+.. c:function:: void sq_remove(HSQUIRRELVM v, SQInteger idx)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger idx: index of the element that has to be removed
+
+removes an element from an arbitrary position in the stack
+
+
+
+
+
+.. _sq_reservestack:
+
+.. c:function:: SQRESULT sq_reservestack(HSQUIRRELVM v, SQInteger nsize)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger nsize: required stack size
+    :returns: a SQRESULT
+
+ensure that the stack space left is at least of a specified size.If the stack is smaller it will automatically grow. if there's a memtamethod currently running the function will fail and the stack will not be resized, this situatuation has to be considered a "stack overflow".
+
+
+
+
+
+.. _sq_settop:
+
+.. c:function:: void sq_settop(HSQUIRRELVM v, SQInteger v)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger v: the new top index
+
+resize the stack, if new top is bigger then the current top the function will push nulls.

doc/source/reference/api/virtual_machine.rst

@@ -0,0 +1,341 @@
+.. _api_ref_virtual_machine:
+
+===============
+Virtual Machine
+===============
+
+
+.. _sq_close:
+
+.. c:function:: void sq_close(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+releases a squirrel VM and all related friend VMs
+
+
+
+
+
+.. _sq_geterrorfunc:
+
+.. c:function:: SQPRINTFUNCTION sq_geterrorfunc(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: a pointer to a SQPRINTFUNCTION, or NULL if no function has been set.
+
+returns the current error function of the given Virtual machine. (see sq_setprintfunc())
+
+
+
+
+
+.. _sq_getforeignptr:
+
+.. c:function:: SQUserPointer sq_getforeignptr(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: the current VMs foreign pointer.
+
+Returns the foreign pointer of a VM instance.
+
+
+
+
+
+.. _sq_getprintfunc:
+
+.. c:function:: SQPRINTFUNCTION sq_getprintfunc(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: a pointer to a SQPRINTFUNCTION, or NULL if no function has been set.
+
+returns the current print function of the given Virtual machine. (see sq_setprintfunc())
+
+
+
+
+
+.. _sq_getsharedforeignptr:
+
+.. c:function:: SQUserPointer sq_getsharedforeignptr(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: the current VMs shared foreign pointer
+
+Returns the shared foreign pointer of a group of friend VMs .
+
+
+
+
+
+.. _sq_getsharedreleasehook:
+
+.. c:function:: SQUserPointer sq_getsharedreleasehook(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: the current VMs release hook.
+
+Returns the shared release hook of a group of friend VMs .
+
+
+
+
+
+.. _sq_getversion:
+
+.. c:function:: SQInteger sq_getversion()
+
+    :returns: version number of the vm(as in SQUIRREL_VERSION_NUMBER).
+
+returns the version number of the vm.
+
+
+
+
+
+.. _sq_getvmreleasehook:
+
+.. c:function:: SQUserPointer sq_getvmreleasehook(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: the current VMs release hook.
+
+Returns the release hook of a VM instance.
+
+
+
+
+
+.. _sq_getvmstate:
+
+.. c:function:: SQInteger sq_getvmstate(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: the state of the vm encoded as integer value. The following constants are defined: SQ_VMSTATE_IDLE, SQ_VMSTATE_RUNNING, SQ_VMSTATE_SUSPENDED.
+
+returns the execution state of a virtual machine
+
+
+
+
+
+.. _sq_move:
+
+.. c:function:: void sq_move(HSQUIRRELVM dest, HSQUIRRELVM src, SQInteger idx)
+
+    :param HSQUIRRELVM dest: the destination VM
+    :param HSQUIRRELVM src: the source VM
+    :param SQInteger idx: the index in the source stack of the value that has to be moved
+
+pushes the object at the position 'idx' of the source vm stack in the destination vm stack.
+
+
+
+
+
+.. _sq_newthread:
+
+.. c:function:: HSQUIRRELVM sq_newthread(HSQUIRRELVM friendvm, SQInteger initialstacksize)
+
+    :param HSQUIRRELVM friendvm: a friend VM
+    :param SQInteger initialstacksize: the size of the stack in slots(number of objects)
+    :returns: a pointer to the new VM.
+    :remarks: By default the roottable is shared with the VM passed as first parameter. The new VM lifetime is bound to the "thread" object pushed in the stack and behave like a normal squirrel object.
+
+creates a new vm friendvm of the one passed as first parmeter and pushes it in its stack as "thread" object.
+
+
+
+
+
+.. _sq_open:
+
+.. c:function:: HSQUIRRELVM sq_open(SQInteger initialstacksize)
+
+    :param SQInteger initialstacksize: the size of the stack in slots(number of objects)
+    :returns: an handle to a squirrel vm
+    :remarks: the returned VM has to be released with sq_releasevm
+
+creates a new instance of a squirrel VM that consists in a new execution stack.
+
+
+
+
+
+.. _sq_pushconsttable:
+
+.. c:function:: void sq_pushconsttable(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+pushes the current const table in the stack
+
+
+
+
+
+.. _sq_pushregistrytable:
+
+.. c:function:: void sq_pushregistrytable(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+pushes the registry table in the stack
+
+
+
+
+
+.. _sq_pushroottable:
+
+.. c:function:: void sq_pushroottable(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+pushes the current root table in the stack
+
+
+
+
+
+.. _sq_setconsttable:
+
+.. c:function:: void sq_setconsttable(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+pops a table from the stack and set it as const table
+
+
+
+
+
+.. _sq_seterrorhandler:
+
+.. c:function:: void sq_seterrorhandler(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :remarks: the error handler is shared by friend VMs
+
+pops from the stack a closure or native closure an sets it as runtime-error handler.
+
+
+
+
+
+.. _sq_setforeignptr:
+
+.. c:function:: void sq_setforeignptr(HSQUIRRELVM v, SQUserPointer p)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQUserPointer p: The pointer that has to be set
+
+Sets the foreign pointer of a certain VM instance. The foreign pointer is an arbitrary user defined pointer associated to a VM (by default is value id 0). This pointer is ignored by the VM.
+
+
+
+
+
+.. _sq_setprintfunc:
+
+.. c:function:: void sq_setprintfunc(HSQUIRRELVM v, SQPRINTFUNCTION printfunc, SQPRINTFUNCTION errorfunc)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQPRINTFUNCTION printfunc: a pointer to the print func or NULL to disable the output.
+    :param SQPRINTFUNCTION errorfunc: a pointer to the error func or NULL to disable the output.
+    :remarks: the print func has the following prototype: void printfunc(HSQUIRRELVM v,const SQChar \*s,...)
+
+sets the print function of the virtual machine. This function is used by the built-in function '::print()' to output text.
+
+
+
+
+
+.. _sq_setroottable:
+
+.. c:function:: void sq_setroottable(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+pops a table from the stack and set it as root table
+
+
+
+
+
+.. _sq_setsharedforeignptr:
+
+.. c:function:: void sq_setsharedforeignptr(HSQUIRRELVM v, SQUserPointer p)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQUserPointer p: The pointer that has to be set
+
+Sets the shared foreign pointer. The foreign pointer is an arbitrary user defined pointer associated to a group of friend VMs (by default is value id 0). After a "main" VM is created using sq_open() all friend VMs created with sq_newthread share the same shared pointer.
+
+
+
+
+
+.. _sq_setsharedreleasehook:
+
+.. c:function:: void sq_setsharedreleasehook(HSQUIRRELVM v, SQRELESEHOOK hook)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQRELESEHOOK hook: The hook that has to be set
+
+Sets the release hook of a certain VM group. The release hook is invoked when the last vm of the group vm is destroyed (usually when sq_close() is invoked). The userpointer passed to the function is the shared foreignpointer(see sq_getsharedforeignptr()). After a "main" VM is created using sq_open() all friend VMs created with sq_newthread() share the same shared release hook.
+
+
+
+
+
+.. _sq_setvmreleasehook:
+
+.. c:function:: void sq_setvmreleasehook(HSQUIRRELVM v, SQRELESEHOOK hook)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQRELESEHOOK hook: The hook that has to be set
+
+Sets the release hook of a certain VM instance. The release hook is invoked when the vm is destroyed. The userpointer passed to the function is the vm foreignpointer(see sq_setforeignpointer())
+
+
+
+
+
+.. _sq_suspendvm:
+
+.. c:function:: HRESULT sq_suspendvm(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an SQRESULT(that has to be returned by a C function)
+    :remarks: sq_result can only be called as return expression of a C function. The function will fail is the suspension is done through more C calls or in a metamethod.
+
+Suspends the execution of the specified vm.
+
+*.eg*
+
+::
+
+    SQInteger suspend_vm_example(HSQUIRRELVM v)
+    {
+        return sq_suspendvm(v);
+    }
+
+
+
+
+
+
+.. _sq_wakeupvm:
+
+.. c:function:: HRESULT sq_wakeupvm(HSQUIRRELVM v, SQBool resumedret, SQBool retval, SQBool raiseerror, SQBool throwerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQBool resumedret: if true the function will pop a value from the stack and use it as return value for the function that has previously suspended the virtual machine.
+    :param SQBool retval: if true the function will push the return value of the function that suspend the excution or the main function one.
+    :param SQBool raiseerror: if true, if a runtime error occurs during the execution of the call, the vm will invoke the error handler.
+    :param SQBool throwerror: if true, the vm will thow an exception as soon as is resumed. the exception payload must be set beforehand invoking sq_thowerror().
+    :returns: an HRESULT.
+
+Wake up the execution a previously suspended virtual machine.

doc/source/reference/api_reference.rst

@@ -0,0 +1,18 @@
+.. _api_reference:
+
+
+*************
+API Reference
+*************
+
+.. toctree::
+   api/virtual_machine.rst
+   api/compiler.rst
+   api/stack_operations.rst
+   api/object_creation_and_handling.rst
+   api/calls.rst
+   api/object_manipulation.rst
+   api/bytecode_serialization.rst
+   api/raw_object_handling.rst
+   api/garbage_collector.rst
+   api/debug_interface.rst

doc/source/reference/embedding/build_configuration.rst

@@ -0,0 +1,59 @@
+.. _embedding_build_configuration:
+
+========================
+Build Configuration
+========================
+
+.. _unicode:
+
+----------
+Unicode
+----------
+
+.. index:: single: Unicode
+
+By default Squirrel strings are plain 8-bits ASCII characters; however if the symbol
+'SQUNICODE' is defined the VM, compiler and API will use 16-bits characters (UCS2).
+
+.. _squirrel_64bits:
+
+---------------------------------
+Squirrel on 64 bits architectures
+---------------------------------
+
+.. index::
+    single: Squirrel on 64 bits architectures
+    single: 64 bits
+
+Squirrel can be compiled on 64 bits architectures by defining '_SQ64' in the C++
+preprocessor. This flag should be defined in any project that includes 'squirrel.h'.
+
+.. _userdata_alignment:
+
+------------------
+Userdata Alignment
+------------------
+
+.. index:: single: Userdata Alignment
+
+Both class instances and userdatas can have a buffer associated to them.
+Squirrel specifies the alignment(in bytes) through the peroprocessor defining 'SQ_ALIGNMENT'.
+By default SQ_ALIGNMENT is defined as 4 for 32 bits builds and 8 for 64bits builds and builds that use 64bits floats.
+It is possible to override the value of SQ_ALIGNMENT respecting the following rules.
+SQ_ALIGNMENT shall be less than or equal to SQ_MALLOC alignments, and it shall be power of 2.
+
+.. note:: This only applies for userdata allocated by the VM, specified via sq_setclassudsize() or belonging to a userdata object.
+        userpointers specified by the user are not affected by alignemnt rules.
+
+.. _standalone_vm:
+
+------------------------------------
+Stand-alone VM without compiler
+------------------------------------
+
+.. index:: single: Stand-alone VM without compiler
+
+Squirrel's VM can be compiled without it's compiler by defining 'NO_COMPILER' in the C++ preprocessor.
+When 'NO_COMPILER' is defined all function related to the compiler (eg. sq_compile) will fail. Other functions
+that conditionally load precompiled bytecode or compile a file (eg. sqstd_dofile) will only work with
+precompiled bytecode.

doc/source/reference/embedding/calling_a_function.rst

@@ -0,0 +1,27 @@
+.. _embedding_calling_a_function:
+
+==================
+Calling a function
+==================
+
+To call a squirrel function it is necessary to push the function in the stack followed by the
+parameters and then call the function sq_call.
+The function will pop the parameters and push the return value if the last sq_call
+parameter is > 0. ::
+
+    sq_pushroottable(v);
+    sq_pushstring(v,"foo",-1);
+    sq_get(v,-2); //get the function from the root table
+    sq_pushroottable(v); //'this' (function environment object)
+    sq_pushinteger(v,1);
+    sq_pushfloat(v,2.0);
+    sq_pushstring(v,"three",-1);
+    sq_call(v,4,SQFalse);
+    sq_pop(v,2); //pops the roottable and the function
+
+this is equivalent to the following Squirrel code::
+
+    foo(1,2.0,"three");
+
+If a runtime error occurs (or a exception is thrown) during the squirrel code execution
+the sq_call will fail.

doc/source/reference/embedding/compiling_a_script.rst

@@ -0,0 +1,58 @@
+.. embedding_compiling_a_script:
+
+==================
+Compiling a script
+==================
+
+You can compile a Squirrel script with the function *sq_compile*.::
+
+    typedef SQInteger (*SQLEXREADFUNC)(SQUserPointer userdata);
+
+    SQRESULT sq_compile(HSQUIRRELVM v,SQREADFUNC read,SQUserPointer p,
+                const SQChar *sourcename,SQBool raiseerror);
+
+In order to compile a script is necessary for the host application to implement a reader
+function (SQLEXREADFUNC); this function is used to feed the compiler with the script
+data.
+The function is called every time the compiler needs a character; It has to return a
+character code if succeed or 0 if the source is finished.
+
+If sq_compile succeeds, the compiled script will be pushed as Squirrel function in the
+stack.
+
+.. :note::
+    In order to execute the script, the function generated by *sq_compile()* has
+    to be called through *sq_call()*
+
+Here an example of a 'read' function that read from a file: ::
+
+    SQInteger file_lexfeedASCII(SQUserPointer file)
+    {
+        int ret;
+        char c;
+        if( ( ret=fread(&c,sizeof(c),1,(FILE *)file )>0) )
+            return c;
+        return 0;
+    }
+
+    int compile_file(HSQUIRRELVM v,const char *filename)
+    {
+        FILE *f=fopen(filename,"rb");
+        if(f)
+        {
+             sq_compile(v,file_lexfeedASCII,f,filename,1);
+             fclose(f);
+             return 1;
+        }
+        return 0;
+    }
+
+When the compiler fails for a syntax error it will try to call the 'compiler error handler';
+this function must be declared as follow: ::
+
+    typedef void (*SQCOMPILERERROR)(HSQUIRRELVM /*v*/,const SQChar * /*desc*/,const SQChar * /*source*/,
+                            SQInteger /*line*/,SQInteger /*column*/);
+
+and can be set with the following API call::
+
+    void sq_setcompilererrorhandler(HSQUIRRELVM v,SQCOMPILERERROR f);

doc/source/reference/embedding/creating_a_c_function.rst

@@ -0,0 +1,105 @@
+.. _embedding_creating_a_c_function:
+
+===================
+Create a C function
+===================
+
+A native C function must have the following prototype: ::
+
+    typedef SQInteger (*SQFUNCTION)(HSQUIRRELVM);
+
+The parameters is an handle to the calling VM and the return value is an integer
+respecting the following rules:
+
+* 1 if the function returns a value
+* 0 if the function does not return a value
+* SQ_ERROR runtime error is thrown
+
+In order to obtain a new callable squirrel function from a C function pointer, is necessary
+to call sq_newclosure() passing the C function to it; the new Squirrel function will be
+pushed in the stack.
+
+When the function is called, the stackbase is the first parameter of the function and the
+top is the last. In order to return a value the function has to push it in the stack and
+return 1.
+
+Function parameters are in the stack from postion 1 ('this') to *n*.
+*sq_gettop()* can be used to determinate the number of parameters.
+
+If the function has free variables, those will be in the stack after the explicit parameters
+an can be handled as normal parameters. Note also that the value returned by *sq_gettop()* will be
+affected by free variables. *sq_gettop()* will return the number of parameters plus
+number of free variables.
+
+Here an example, the following function print the value of each argument and return the
+number of arguments. ::
+
+    SQInteger print_args(HSQUIRRELVM v)
+    {
+        SQInteger nargs = sq_gettop(v); //number of arguments
+        for(SQInteger n=1;n<=nargs;n++)
+        {
+            printf("arg %d is ",n);
+            switch(sq_gettype(v,n))
+            {
+                case OT_NULL:
+                    printf("null");
+                    break;
+                case OT_INTEGER:
+                    printf("integer");
+                    break;
+                case OT_FLOAT:
+                    printf("float");
+                    break;
+                case OT_STRING:
+                    printf("string");
+                    break;
+                case OT_TABLE:
+                    printf("table");
+                    break;
+                case OT_ARRAY:
+                    printf("array");
+                    break;
+                case OT_USERDATA:
+                    printf("userdata");
+                    break;
+                case OT_CLOSURE:
+                    printf("closure(function)");
+                    break;
+                case OT_NATIVECLOSURE:
+                    printf("native closure(C function)");
+                    break;
+                case OT_GENERATOR:
+                    printf("generator");
+                    break;
+                case OT_USERPOINTER:
+                    printf("userpointer");
+                    break;
+                case OT_CLASS:
+                    printf("class");
+                    break;
+                case OT_INSTANCE:
+                    printf("instance");
+                    break;
+                case OT_WEAKREF:
+                    printf("weak reference");
+                    break;
+                default:
+                    return sq_throwerror(v,"invalid param"); //throws an exception
+            }
+        }
+        printf("\n");
+        sq_pushinteger(v,nargs); //push the number of arguments as return value
+        return 1; //1 because 1 value is returned
+    }
+
+Here an example of how to register a function::
+
+    SQInteger register_global_func(HSQUIRRELVM v,SQFUNCTION f,const char *fname)
+    {
+        sq_pushroottable(v);
+        sq_pushstring(v,fname,-1);
+        sq_newclosure(v,f,0,0); //create a new function
+        sq_newslot(v,-3,SQFalse);
+        sq_pop(v,1); //pops the root table
+    }

doc/source/reference/embedding/debug_interface.rst

@@ -0,0 +1,58 @@
+.. _embedding_debug_interface:
+
+===============
+Debug Interface
+===============
+
+The squirrel VM exposes a very simple debug interface that allows to easily built a full
+featured debugger.
+Through the functions sq_setdebughook and sq_setnativedebughook is possible in fact to set a callback function that
+will be called every time the VM executes an new line of a script or if a function get
+called/returns. The callback will pass as argument the current line the current source and the
+current function name (if any).::
+
+    SQUIRREL_API void sq_setdebughook(HSQUIRRELVM v);
+
+or ::
+
+    SQUIRREL_API void sq_setnativedebughook(HSQUIRRELVM v,SQDEBUGHOOK hook);
+
+The following code shows how a debug hook could look like(obviously is possible to
+implement this function in C as well). ::
+
+    function debughook(event_type,sourcefile,line,funcname)
+    {
+        local fname=funcname?funcname:"unknown";
+        local srcfile=sourcefile?sourcefile:"unknown"
+        switch (event_type) {
+        case 'l': //called every line(that contains some code)
+            ::print("LINE line [" + line + "] func [" + fname + "]");
+            ::print("file [" + srcfile + "]\n");
+            break;
+        case 'c': //called when a function has been called
+            ::print("LINE line [" + line + "] func [" + fname + "]");
+            ::print("file [" + srcfile + "]\n");
+            break;
+        case 'r': //called when a function returns
+            ::print("LINE line [" + line + "] func [" + fname + "]");
+            ::print("file [" + srcfile + "]\n");
+            break;
+        }
+    }
+
+The parameter *event_type* can be 'l' ,'c' or 'r' ; a hook with a 'l' event is called for each line that
+gets executed, 'c' every time a function gets called and 'r' every time a function returns.
+
+A full-featured debugger always allows displaying local variables and calls stack.
+The call stack information are retrieved through sq_getstackinfos()::
+
+    SQInteger sq_stackinfos(HSQUIRRELVM v,SQInteger level,SQStackInfos *si);
+
+While the local variables info through sq_getlocal()::
+
+    SQInteger sq_getlocal(HSQUIRRELVM v,SQUnsignedInteger level,SQUnsignedInteger nseq);
+
+In order to receive line callbacks the scripts have to be compiled with debug infos enabled
+this is done through sq_enabledebuginfo(); ::
+
+    void sq_enabledebuginfo(HSQUIRRELVM v, SQInteger debuginfo);

doc/source/reference/embedding/error_conventions.rst

@@ -0,0 +1,16 @@
+.. _embedding_error_convetions:
+
+
+========================
+Error Conventions
+========================
+
+.. index::
+    single: Error Conventions
+
+Most of the functions in the API return a SQRESULT value; SQRESULT indicates if a
+function completed successfully or not.
+The macros SQ_SUCCEEDED() and SQ_FAILED() are used to test the result of a function.::
+
+    if(SQ_FAILED(sq_getstring(v,-1,&s)))
+        printf("getstring failed");

doc/source/reference/embedding/memory_management.rst

@@ -0,0 +1,28 @@
+.. _embedding_memory_management:
+
+========================
+Memory Management
+========================
+
+.. index:: single: Memory Management
+
+Squirrel uses reference counting (RC) as primary system for memory management;
+however, the virtual machine (VM) has an auxiliary
+mark and sweep garbage collector that can be invoked on demand.
+
+There are 2 possible compile time options:
+
+    * The default configuration consists in RC plus a mark and sweep garbage collector.
+      The host program can call the function sq_collectgarbage() and perform a garbage collection cycle
+      during the program execution. The garbage collector isn't invoked by the VM and has to
+      be explicitly called by the host program.
+
+    * The second a situation consists in RC only(define NO_GARBAGE_COLLECTOR); in this case is impossible for
+      the VM to detect reference cycles, so is the programmer that has to solve them explicitly in order to
+      avoid memory leaks.
+
+The only advantage introduced by the second option is that saves 2 additional
+pointers that have to be stored for each object in the default configuration with
+garbage collector(8 bytes for 32 bits systems).
+The types involved are: tables, arrays, functions, threads, userdata and generators; all other
+types are untouched. These options do not affect execution speed.

doc/source/reference/embedding/references_from_c.rst

@@ -0,0 +1,21 @@
+.. embedding_references_from_c:
+
+========================================================
+Mantaining references to Squirrel values from the C API
+========================================================
+
+Squirrel allows to reference values through the C API; the function sq_getstackobj() gets
+a handle to a squirrel object(any type). The object handle can be used to control the lifetime
+of an object by adding or removing references to it( see sq_addref() and sq_release()).
+The object can be also re-pushed in the VM stack using sq_pushobject().::
+
+    HSQOBJECT obj;
+
+    sq_resetobject(v,&obj) //initialize the handle
+    sq_getstackobj(v,-2,&obj); //retrieve an object handle from the pos -2
+    sq_addref(v,&obj); //adds a reference to the object
+
+    ... //do stuff
+
+    sq_pushobject(v,&obj); //push the object in the stack
+    sq_release(v,&obj); //relese the object

doc/source/reference/embedding/runtime_error_handling.rst

@@ -0,0 +1,17 @@
+.. _embedding_runtime_error_handling:
+
+======================
+Runtime error handling
+======================
+
+When an exception is not handled by Squirrel code with a try/catch statement, a runtime
+error is raised and the execution of the current program is interrupted. It is possible to
+set a call back function to intercept the runtime error from the host program; this is
+useful to show meaningful errors to the script writer and for implementing visual
+debuggers.
+The following API call pops a Squirrel function from the stack and sets it as error handler.::
+
+    SQUIRREL_API void sq_seterrorhandler(HSQUIRRELVM v);
+
+The error handler is called with 2 parameters, an environment object (this) and a object.
+The object can be any squirrel type.

doc/source/reference/embedding/tables_and_arrays_manipulation.rst

@@ -0,0 +1,70 @@
+.. _embedding_tables_and_arrays_manipulation:
+
+==============================
+Tables and arrays manipulation
+==============================
+
+A new table is created calling sq_newtable, this function pushes a new table in the stack.::
+
+    void sq_newtable(HSQUIRRELVM v);
+
+To create a new slot::
+
+    SQRESULT sq_newslot(HSQUIRRELVM v,SQInteger idx,SQBool bstatic);
+
+To set or get the table delegate::
+
+    SQRESULT sq_setdelegate(HSQUIRRELVM v,SQInteger idx);
+    SQRESULT sq_getdelegate(HSQUIRRELVM v,SQInteger idx);
+
+
+A new array is created calling sq_newarray, the function pushes a new array in the
+stack; if the parameters size is bigger than 0 the elements are initialized to null.::
+
+    void sq_newarray (HSQUIRRELVM v,SQInteger size);
+
+To append a value to the back of the array::
+
+    SQRESULT sq_arrayappend(HSQUIRRELVM v,SQInteger idx);
+
+To remove a value from the back of the array::
+
+    SQRESULT sq_arraypop(HSQUIRRELVM v,SQInteger idx,SQInteger pushval);
+
+To resize the array::
+
+    SQRESULT sq_arrayresize(HSQUIRRELVM v,SQInteger idx,SQInteger newsize);
+
+To retrieve the size of a table or an array you must use sq_getsize()::
+
+    SQInteger sq_getsize(HSQUIRRELVM v,SQInteger idx);
+
+To set a value in an array or table::
+
+    SQRESULT sq_set(HSQUIRRELVM v,SQInteger idx);
+
+To get a value from an array or table::
+
+    SQRESULT sq_get(HSQUIRRELVM v,SQInteger idx);
+
+To get or set a value from a table without employ delegation::
+
+    SQRESULT sq_rawget(HSQUIRRELVM v,SQInteger idx);
+    SQRESULT sq_rawset(HSQUIRRELVM v,SQInteger idx);
+
+To iterate a table or an array::
+
+    SQRESULT sq_next(HSQUIRRELVM v,SQInteger idx);
+
+Here an example of how to perform an iteration: ::
+
+    //push your table/array here
+    sq_pushnull(v)  //null iterator
+    while(SQ_SUCCEEDED(sq_next(v,-2)))
+    {
+        //here -1 is the value and -2 is the key
+
+        sq_pop(v,2); //pops key and val before the nex iteration
+    }
+
+    sq_pop(v,1); //pops the null iterator

doc/source/reference/embedding/the_registry_table.rst

@@ -0,0 +1,14 @@
+.. _embedding_the_registry_table:
+
+==================
+The registry table
+==================
+
+The registry table is an hidden table shared between vm and all his thread(friend vms).
+This table is accessible only through the C API and is ment to be an utility structure
+for native C library implementation.
+For instance the sqstdlib(squirrel standard library)uses it to store configuration and shared objects
+delegates.
+The registry is accessible through the API call *sq_pushregistrytable()*.::
+
+    void sq_pushregistrytable(HSQUIRRELVM v);

doc/source/reference/embedding/the_stack.rst

@@ -0,0 +1,103 @@
+.. _embedding_the_stack:
+
+
+==========
+The Stack
+==========
+
+Squirrel exchanges values with the virtual machine through a stack. This mechanism has
+been inherited from the language Lua.
+For instance to call a Squirrel function from C it is necessary to push the function and the
+arguments in the stack and then invoke the function; also when Squirrel calls a C
+function the parameters will be in the stack as well.
+
+-------------
+Stack indexes
+-------------
+
+Many API functions can arbitrarily refer to any element in the stack through an index.
+The stack indexes follow those conventions:
+
+* 1 is the stack base
+* Negative indexes are considered an offset from top of the stack. For instance -1 isthe top of the stack.
+* 0 is an invalid index
+
+Here an example (let's pretend that this table is the VM stack)
+
++------------+--------------------+--------------------+
+| **STACK**  | **positive index** | **negative index** |
++============+====================+====================+
+| "test"     | 4                  | -1(top)            |
++------------+--------------------+--------------------+
+| 1          | 3                  | -2                 |
++------------+--------------------+--------------------+
+| 0.5        | 2                  | -3                 |
++------------+--------------------+--------------------+
+| "foo"      | 1(base)            | -4                 |
++------------+--------------------+--------------------+
+
+In this case, the function *sq_gettop* would return 4;
+
+------------------
+Stack manipulation
+------------------
+
+The API offers several functions to push and retrieve data from the Squirrel stack.
+
+To push a value that is already present in the stack in the top position::
+
+    void sq_push(HSQUIRRELVM v,SQInteger idx);
+
+To pop an arbitrary number of elements::
+
+    void sq_pop(HSQUIRRELVM v,SQInteger nelemstopop);
+
+To remove an element from the stack::
+
+    void sq_remove(HSQUIRRELVM v,SQInteger idx);
+
+To retrieve the top index (and size) of the current
+virtual stack you must call *sq_gettop* ::
+
+    SQInteger sq_gettop(HSQUIRRELVM v);
+
+To force the stack to a certain size you can call *sq_settop* ::
+
+    void sq_settop(HSQUIRRELVM v,SQInteger newtop);
+
+If the newtop is bigger than the previous one, the new posistions in the stack will be
+filled with null values.
+
+The following function pushes a C value into the stack::
+
+    void sq_pushstring(HSQUIRRELVM v,const SQChar *s,SQInteger len);
+    void sq_pushfloat(HSQUIRRELVM v,SQFloat f);
+    void sq_pushinteger(HSQUIRRELVM v,SQInteger n);
+    void sq_pushuserpointer(HSQUIRRELVM v,SQUserPointer p);
+    void sq_pushbool(HSQUIRRELVM v,SQBool b);
+
+this function pushes a null into the stack::
+
+    void sq_pushnull(HSQUIRRELVM v);
+
+returns the type of the value in a arbitrary position in the stack::
+
+    SQObjectType sq_gettype(HSQUIRRELVM v,SQInteger idx);
+
+the result can be one of the following values: ::
+
+    OT_NULL,OT_INTEGER,OT_FLOAT,OT_STRING,OT_TABLE,OT_ARRAY,OT_USERDATA,
+    OT_CLOSURE,OT_NATIVECLOSURE,OT_GENERATOR,OT_USERPOINTER,OT_BOOL,OT_INSTANCE,OT_CLASS,OT_WEAKREF
+
+The following functions convert a squirrel value in the stack to a C value::
+
+    SQRESULT sq_getstring(HSQUIRRELVM v,SQInteger idx,const SQChar **c);
+    SQRESULT sq_getinteger(HSQUIRRELVM v,SQInteger idx,SQInteger *i);
+    SQRESULT sq_getfloat(HSQUIRRELVM v,SQInteger idx,SQFloat *f);
+    SQRESULT sq_getuserpointer(HSQUIRRELVM v,SQInteger idx,SQUserPointer *p);
+    SQRESULT sq_getuserdata(HSQUIRRELVM v,SQInteger idx,SQUserPointer *p,SQUserPointer *typetag);
+    SQRESULT sq_getbool(HSQUIRRELVM v,SQInteger idx,SQBool *p);
+
+The function sq_cmp compares 2 values from the stack and returns their relation (like strcmp() in ANSI C).::
+
+    SQInteger sq_cmp(HSQUIRRELVM v);

doc/source/reference/embedding/userdata_and_userpointers.rst

@@ -0,0 +1,33 @@
+.. _embedding_userdata_and_userpointers:
+
+=========================
+Userdata and UserPointers
+=========================
+
+Squirrel allows the host application put arbitrary data chunks into a Squirrel value, this is
+possible through the data type userdata.::
+
+    SQUserPointer sq_newuserdata(HSQUIRRELVM v,SQUnsignedInteger size);
+
+When the function *sq_newuserdata* is called, Squirrel allocates a new userdata with the
+specified size, returns a pointer to his payload buffer and push the object in the stack; at
+this point the application can do whatever it want with this memory chunk, the VM will
+automatically take cake of the memory deallocation like for every other built-in type.
+A userdata can be passed to a function or stored in a table slot. By default Squirrel
+cannot manipulate directly userdata; however is possible to assign a delegate to it and
+define a behavior like it would be a table.
+Because the application would want to do something with the data stored in a userdata
+object when it get deleted, is possible to assign a callback that will be called by the VM
+just before deleting a certain userdata.
+This is done through the API call *sq_setreleasehook*.::
+
+    typedef SQInteger (*SQRELEASEHOOK)(SQUserPointer,SQInteger size);
+
+    void sq_setreleasehook(HSQUIRRELVM v,SQInteger idx,SQRELEASEHOOK hook);
+
+Another kind of userdata is the userpointer; this type is not a memory chunk like the
+normal userdata, but just a 'void*' pointer. It cannot have a delegate and is passed by
+value, so pushing a userpointer doesn't cause any memory allocation.::
+
+    void sq_pushuserpointer(HSQUIRRELVM v,SQUserPointer p);
+

doc/source/reference/embedding/vm_initialization.rst

@@ -0,0 +1,21 @@
+.. _embedding_vm_initialization:
+
+==============================
+Virtual Machine Initialization
+==============================
+
+The first thing that a host application has to do, is create a virtual machine.
+The host application can create any number of virtual machines through the function
+*sq_open()*.
+Every single VM that was created using *sq_open()* has to be released with the function *sq_close()* when it is no
+longer needed.::
+
+    int main(int argc, char* argv[])
+    {
+        HSQUIRRELVM v;
+        v = sq_open(1024); //creates a VM with initial stack size 1024
+
+        //do some stuff with squirrel here
+
+        sq_close(v);
+    }

doc/source/reference/embedding_squirrel.rst

@@ -0,0 +1,29 @@
+.. _embedding_squirrel:
+
+***************************
+  Embedding Squirrel
+***************************
+
+*This section describes how to embed Squirrel in a host application,
+C language knowledge is required to understand this part of the manual.*
+
+Because of his nature of extension language, Squirrel's compiler and virtual machine
+are implemented as C library. The library exposes a set of functions to compile scripts,
+call functions, manipulate data and extend the virtual machine.
+All declarations needed for embedding the language in an application are in the header file 'squirrel.h'.
+
+.. toctree::
+    embedding/memory_management.rst
+    embedding/build_configuration.rst
+    embedding/error_conventions.rst
+    embedding/vm_initialization.rst
+    embedding/the_stack.rst
+    embedding/runtime_error_handling.rst
+    embedding/compiling_a_script.rst
+    embedding/calling_a_function.rst
+    embedding/creating_a_c_function.rst
+    embedding/tables_and_arrays_manipulation.rst
+    embedding/userdata_and_userpointers.rst
+    embedding/the_registry_table.rst
+    embedding/references_from_c.rst
+    embedding/debug_interface.rst

doc/source/reference/index.rst

@@ -0,0 +1,34 @@
+.. _reference:
+
+#################################
+  Squirrel 3.1 Reference Manual
+#################################
+
+Copyrigth (c) 2003-2016 Alberto Demichelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+.. toctree::
+   :maxdepth: 3
+   :numbered:
+
+   introduction.rst
+   language.rst
+   embedding_squirrel.rst
+   api_reference.rst

doc/source/reference/introduction.rst

@@ -0,0 +1,16 @@
+.. _introduction:
+
+************
+Introduction
+************
+
+.. index::
+    single: introduction
+
+Squirrel is a high level imperative-OO programming language, designed to be a powerful
+scripting tool that fits in the size, memory bandwidth, and real-time requirements of
+applications like games.
+Although Squirrel offers a wide range of features like dynamic typing, delegation, higher
+order functions, generators, tail recursion, exception handling, automatic memory
+management, both compiler and virtual machine fit together in about 6k lines of C++
+code.

doc/source/reference/language.rst

@@ -0,0 +1,23 @@
+.. _thelanguage:
+
+***************************
+  The language
+***************************
+
+.. toctree::
+   language/lexical_structure.rst
+   language/datatypes.rst
+   language/execution_context.rst
+   language/statements.rst
+   language/expressions.rst
+   language/tables.rst
+   language/arrays.rst
+   language/functions.rst
+   language/classes.rst
+   language/generators.rst
+   language/constants_and_enumerations.rst
+   language/threads.rst
+   language/weak_references.rst
+   language/delegation.rst
+   language/metamethods.rst
+   language/builtin_functions.rst

doc/source/reference/language/arrays.rst

@@ -0,0 +1,19 @@
+.. _arrays:
+
+
+=================
+Arrays
+=================
+
+.. index::
+    single: Arrays
+
+An array is a sequence of values indexed by a integer number from 0 to the size of the
+array minus 1. Arrays elements can be obtained through their index.::
+
+    local a=["I'm a string", 123]
+    print(typeof a[0]) //prints "string"
+    print(typeof a[1]) //prints "integer"
+
+Resizing, insertion, deletion of arrays and arrays elements is done through a set of
+standard functions (see :ref:`built-in functions <builtin_functions>`).

doc/source/reference/language/classes.rst

@@ -0,0 +1,429 @@
+.. _classes:
+
+
+=================
+Classes
+=================
+
+.. index::
+    single: Classes
+
+Squirrel implements a class mechanism similar to languages like Java/C++/etc...
+however because of its dynamic nature it differs in several aspects.
+Classes are first class objects like integer or strings and can be stored in
+table slots local variables, arrays and passed as function parameters.
+
+-----------------
+Class Declaration
+-----------------
+
+.. index::
+    pair: declaration; Class
+    single: Class Declaration
+
+A class object is created through the keyword 'class' . The class object follows
+the same declaration syntax of a table(see :ref:`Tables <tables>`) with the only difference
+of using ';' as optional separator rather than ','.
+
+For instance: ::
+
+    class Foo {
+        //constructor
+        constructor(a)
+        {
+            testy = ["stuff",1,2,3,a];
+        }
+        //member function
+        function PrintTesty()
+        {
+            foreach(i,val in testy)
+            {
+                ::print("idx = "+i+" = "+val+" \n");
+            }
+        }
+        //property
+        testy = null;
+
+    }
+
+the previous code examples is a syntactic sugar for: ::
+
+    Foo <- class {
+        //constructor
+        constructor(a)
+        {
+            testy = ["stuff",1,2,3,a];
+        }
+        //member function
+        function PrintTesty()
+        {
+            foreach(i,val in testy)
+            {
+                ::print("idx = "+i+" = "+val+" \n");
+            }
+        }
+        //property
+        testy = null;
+
+    }
+
+in order to emulate namespaces, is also possible to declare something like this::
+
+    //just 2 regular nested tables
+    FakeNamespace <- {
+        Utils = {}
+    }
+
+    class FakeNamespace.Utils.SuperClass {
+        constructor()
+        {
+            ::print("FakeNamespace.Utils.SuperClass")
+        }
+        function DoSomething()
+        {
+            ::print("DoSomething()")
+        }
+    }
+
+    function FakeNamespace::Utils::SuperClass::DoSomethingElse()
+    {
+        ::print("FakeNamespace::Utils::SuperClass::DoSomethingElse()")
+    }
+
+    local testy = FakeNamespace.Utils.SuperClass();
+    testy.DoSomething();
+    testy.DoSomethingElse();
+
+After its declaration, methods or properties can be added or modified by following
+the same rules that apply to a table(operator ``<-``).::
+
+    //adds a new property
+    Foo.stuff <- 10;
+
+    //modifies the default value of an existing property
+    Foo.testy <- "I'm a string";
+
+    //adds a new method
+    function Foo::DoSomething(a,b)
+    {
+        return a+b;
+    }
+
+After a class is instantiated is no longer possible to add new properties however is possible to add or replace methods.
+
+^^^^^^^^^^^^^^^^
+Static variables
+^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: static variables; Class
+    single: Static variables
+
+Squirrel's classes support static member variables. A static variable shares its value
+between all instances of the class. Statics are declared by prefixing the variable declaration
+with the keyword ``static``; the declaration must be in the class body.
+
+.. note:: Statics are read-only.
+
+::
+
+    class Foo {
+        constructor()
+        {
+            //..stuff
+        }
+        name = "normal variable";
+        //static variable
+        static classname = "The class name is foo";
+    };
+
+^^^^^^^^^^^^^^^^
+Class Attributes
+^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: attributes; Class
+    single: Class Attributes
+
+Classes allow to associate attributes to it's members. Attributes are a form of metadata
+that can be used to store application specific informations, like documentations
+strings, properties for IDEs, code generators etc...
+Class attributes are declared in the class body by preceding the member declaration and
+are delimited by the symbol ``</`` and ``/>``.
+Here an example: ::
+
+    class Foo </ test = "I'm a class level attribute" />{
+        </ test = "freakin attribute" /> //attributes of PrintTesty
+        function PrintTesty()
+        {
+            foreach(i,val in testy)
+            {
+                ::print("idx = "+i+" = "+val+" \n");
+            }
+        }
+        </ flippy = 10 , second = [1,2,3] /> //attributes of testy
+        testy = null;
+    }
+
+Attributes are, matter of fact, a table. Squirrel uses ``</ />`` syntax
+instead of curly brackets ``{}`` for the attribute declaration to increase readability.
+
+This means that all rules that apply to tables apply to attributes.
+
+Attributes can be retrieved through the built-in function ``classobj.getattributes(membername)`` (see <link linkend="builtin">built-in functions</link>).
+and can be modified/added through the built-in function ``classobj.setattributes(membername,val)``.
+
+the following code iterates through the attributes of all Foo members.::
+
+    foreach(member,val in Foo)
+    {
+        ::print(member+"\n");
+        local attr;
+        if((attr = Foo.getattributes(member)) != null) {
+            foreach(i,v in attr)
+            {
+                ::print("\t"+i+" = "+(typeof v)+"\n");
+            }
+        }
+        else {
+            ::print("\t<no attributes>\n")
+        }
+    }
+
+-----------------
+Class Instances
+-----------------
+
+.. index::
+    pair: instances; Class
+    single: Class Instances
+
+The class objects inherits several of the table's feature with the difference that multiple instances of the
+same class can be created.
+A class instance is an object that share the same structure of the table that created it but
+holds is own values.
+Class *instantiation* uses function notation.
+A class instance is created by calling a class object. Can be useful to imagine a class like a function
+that returns a class instance.::
+
+    //creates a new instance of Foo
+    local inst = Foo();
+
+When a class instance is created its member are initialized *with the same value* specified in the
+class declaration. The values are copied verbatim, *no cloning is performed* even if the value is a container or a class instances.
+
+.. note:: FOR C# and Java programmers:
+
+            Squirrel doesn't clone member's default values nor executes the member declaration for each instace(as C# or java).
+
+            So consider this example: ::
+
+                class Foo {
+                  myarray = [1,2,3]
+                  mytable = {}
+                }
+
+                local a = Foo();
+                local b = Foo();
+
+            In the snippet above both instances will refer to the same array and same table.To archieve what a C# or Java programmer would
+            exepect, the following approach should be taken. ::
+
+                class Foo {
+                  myarray = null
+                  mytable = null
+                  constructor()
+                  {
+                    myarray = [1,2,3]
+                    mytable = {}
+                  }
+                }
+
+                local a = Foo();
+                local b = Foo();
+
+When a class defines a method called 'constructor', the class instantiation operation will
+automatically invoke it for the newly created instance.
+The constructor method can have parameters, this will impact on the number of parameters
+that the *instantiation operation* will require.
+Constructors, as normal functions, can have variable number of parameters (using the parameter ``...``).::
+
+    class Rect {
+        constructor(w,h)
+        {
+            width = w;
+            height = h;
+        }
+        x = 0;
+        y = 0;
+        width = null;
+        height = null;
+    }
+
+    //Rect's constructor has 2 parameters so the class has to be 'called'
+    //with 2 parameters
+    local rc = Rect(100,100);
+
+After an instance is created, its properties can be set or fetched following the
+same rules that apply to tables. Methods cannot be set.
+
+Instance members cannot be removed.
+
+The class object that created a certain instance can be retrieved through the built-in function
+``instance.getclass()`` (see :ref:`built-in functions <builtin_functions>`)
+
+The operator ``instanceof`` tests if a class instance is an instance of a certain class.::
+
+    local rc = Rect(100,100);
+    if(rc instanceof ::Rect) {
+        ::print("It's a rect");
+    }
+    else {
+        ::print("It isn't a rect");
+    }
+
+.. note:: Since Squirrel 3.x instanceof doesn't throw an exception if the left expression is not a class, it simply fails
+
+--------------
+Inheritance
+--------------
+
+.. index::
+    pair: inheritance; Class
+    single: Inheritance
+
+Squirrel's classes support single inheritance by adding the keyword ``extends``, followed
+by an expression, in the class declaration.
+The syntax for a derived class is the following: ::
+
+    class SuperFoo extends Foo {
+        function DoSomething() {
+            ::print("I'm doing something");
+        }
+    }
+
+When a derived class is declared, Squirrel first copies all base's members in the
+new class then proceeds with evaluating the rest of the declaration.
+
+A derived class inherit all members and properties of it's base, if the derived class
+overrides a base function the base implementation is shadowed.
+It's possible to access a overridden method of the base class by fetching the method from
+through the 'base' keyword.
+
+Here an example: ::
+
+    class Foo {
+        function DoSomething() {
+            ::print("I'm the base");
+        }
+    };
+
+    class SuperFoo extends Foo {
+        //overridden method
+        function DoSomething() {
+            //calls the base method
+            base.DoSomething();
+            ::print("I'm doing something");
+        }
+    }
+
+Same rule apply to the constructor. The constructor is a regular function (apart from being automatically invoked on contruction).::
+
+    class BaseClass {
+        constructor()
+        {
+            ::print("Base constructor\n");
+        }
+    }
+
+    class ChildClass extends BaseClass {
+        constructor()
+        {
+            base.constructor();
+            ::print("Child constructor\n");
+        }
+    }
+
+    local test = ChildClass();
+
+The base class of a derived class can be retrieved through the built-in method ``getbase()``.::
+
+    local thebaseclass = SuperFoo.getbase();
+
+Note that because methods do not have special protection policies when calling methods of the same
+objects, a method of a base class that calls a method of the same class can end up calling a overridden method of the derived class.
+
+A method of a base class can be explicitly invoked by a method of a derived class though the keyword ``base`` (as in base.MyMethod() ).::
+
+    class Foo {
+        function DoSomething() {
+            ::print("I'm the base");
+        }
+        function DoIt()
+        {
+            DoSomething();
+        }
+    };
+
+    class SuperFoo extends Foo {
+        //overridden method
+        function DoSomething() {
+            ::print("I'm the derived");
+
+        }
+        function DoIt() {
+            base.DoIt();
+        }
+    }
+
+    //creates a new instance of SuperFoo
+    local inst = SuperFoo();
+
+    //prints "I'm the derived"
+    inst.DoIt();
+
+----------------------
+Metamethods
+----------------------
+
+.. index::
+    pair: metamethods; Class
+    single: Class metamethods
+
+Class instances allow the customization of certain aspects of the
+their semantics through metamethods(see see :ref:`Metamethods <metamethods>`).
+For C++ programmers: "metamethods behave roughly like overloaded operators".
+The metamethods supported by classes are ``_add, _sub, _mul, _div, _unm, _modulo,
+_set, _get, _typeof, _nexti, _cmp, _call, _delslot, _tostring``
+
+Class objects instead support only 2 metamethods : ``_newmember`` and ``_inherited``
+
+the following example show how to create a class that implements the metamethod ``_add``.::
+
+    class Vector3 {
+        constructor(...)
+        {
+            if(vargv.len() >= 3) {
+                x = vargv[0];
+                y = vargv[1];
+                z = vargv[2];
+            }
+        }
+        function _add(other)
+        {
+            return ::Vector3(x+other.x,y+other.y,z+other.z);
+        }
+
+        x = 0;
+        y = 0;
+        z = 0;
+    }
+
+    local v0 = Vector3(1,2,3)
+    local v1 = Vector3(11,12,13)
+    local v2 = v0 + v1;
+    ::print(v2.x+","+v2.y+","+v2.z+"\n");
+
+Since version 2.1, classes support 2 metamethods ``_inherited`` and ``_newmember``.
+``_inherited`` is invoked when a class inherits from the one that implements ``_inherited``.
+``_newmember`` is invoked for each member that is added to the class(at declaration time).

doc/source/reference/language/constants_and_enumerations.rst

@@ -0,0 +1,97 @@
+.. _constants_and_enumerations:
+
+
+========================
+Constants & Enumarations
+========================
+
+.. index::
+    single: Constants & Enumarations
+
+
+
+Squirrel allows to bind constant values to an identifier that will be evaluated compile-time.
+This is archieved though constants and enumarations.
+
+---------------
+Constants
+---------------
+
+.. index::
+    single: Constants
+
+Constants bind a specific value to an indentifier. Constants are similar to
+global values, except that they are evaluated compile time and their value cannot be changed.
+
+constants values can only be integers, floats or string literals. No expression are allowed.
+are declared with the following syntax.::
+
+    const foobar = 100;
+    const floatbar = 1.2;
+    const stringbar = "I'm a contant string";
+
+constants are always globally scoped, from the moment they are declared, any following code
+can reference them.
+Constants will shadow any global slot with the same name( the global slot will remain visible by using the ``::`` syntax).::
+
+    local x = foobar * 2;
+
+---------------
+Enumrations
+---------------
+
+.. index::
+    single: Enumrations
+
+As Constants, Enumerations bind a specific value to a name. Enumerations are also evaluated compile time
+and their value cannot be changed.
+
+An enum declaration introduces a new enumeration into the program.
+Enumerations values can only be integers, floats or string literals. No expression are allowed.::
+
+    enum Stuff {
+      first, //this will be 0
+      second, //this will be 1
+      third //this will be 2
+    }
+
+or::
+
+    enum Stuff {
+      first = 10
+      second = "string"
+      third = 1.2
+    }
+
+An enum value is accessed in a manner that's similar to accessing a static class member.
+The name of the member must be qualified with the name of the enumeration, for example ``Stuff.second``
+Enumerations will shadow any global slot with the same name( the global slot will remain visible by using the ``::`` syntax).::
+
+    local x = Stuff.first * 2;
+
+--------------------
+Implementation notes
+--------------------
+
+Enumerations and Contants are a compile-time feature. Only integers, string and floats can be declared as const/enum;
+No expressions are allowed(because they would have to be evaluated compile time).
+When a const or an enum is declared, it is added compile time to the ``consttable``. This table is stored in the VM shared state
+and is shared by the VM and all its threads.
+The ``consttable`` is a regular squirrel table; In the same way as the ``roottable``
+it can be modified runtime.
+You can access the ``consttable`` through the built-in function ``getconsttable()``
+and also change it through the built-in function ``setconsttable()``
+
+here some example: ::
+
+    //creates a constant
+    getconsttable()["something"] <- 10"
+    //creates an enumeration
+    getconsttable()["somethingelse"] <- { a = "10", c = "20", d = "200"};
+    //deletes the constant
+    delete getconsttable()["something"]
+    //deletes the enumeration
+    delete getconsttable()["somethingelse"]
+
+This system allows to procedurally declare constants and enumerations, it is also possible to assign any squirrel type
+to a constant/enumeration(function,classes etc...). However this will make serialization of a code chunk impossible.

doc/source/reference/language/datatypes.rst

@@ -0,0 +1,158 @@
+.. _datatypes_and_values:
+
+=====================
+Values and Data types
+=====================
+
+Squirrel is a dynamically typed language so variables do not have a type, although they
+refer to a value that does have a type.
+Squirrel basic types are integer, float, string, null, table, array, function, generator,
+class, instance, bool, thread and userdata.
+
+.. _userdata-index:
+
+--------
+Integer
+--------
+
+An Integer represents a 32 bits (or better) signed number.::
+
+    local a = 123 //decimal
+    local b = 0x0012 //hexadecimal
+    local c = 075 //octal
+    local d = 'w' //char code
+
+--------
+Float
+--------
+
+A float represents a 32 bits (or better) floating point number.::
+
+    local a=1.0
+    local b=0.234
+
+--------
+String
+--------
+
+Strings are an immutable sequence of characters to modify a string is necessary create a new one.
+
+Squirrel's strings, behave like C or C++, are delimited by quotation marks(``"``) and can contain
+escape sequences(``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``, ``\\``, ``\"``, ``\'``, ``\0``,
+``\x<hh>``, ``\u<hhhh>`` and ``\U<hhhhhhhh>``).
+
+Verbatim string literals begin with ``@"`` and end with the matching quote.
+Verbatim string literals also can extend over a line break. If they do, they
+include any white space characters between the quotes: ::
+
+    local a = "I'm a wonderful string\n"
+    // has a newline at the end of the string
+    local x = @"I'm a verbatim string\n"
+    // the \n is copied in the string same as \\n in a regular string "I'm a verbatim string\n"
+
+The only exception to the "no escape sequence" rule for verbatim
+string literals is that you can put a double quotation mark inside a
+verbatim string by doubling it: ::
+
+    local multiline = @"
+        this is a multiline string
+        it will ""embed"" all the new line
+        characters
+    "
+
+--------
+Null
+--------
+
+The null value is a primitive value that represents the null, empty, or non-existent
+reference. The type Null has exactly one value, called null.::
+
+    local a = null
+
+--------
+Bool
+--------
+
+the bool data type can have only two. They are the literals ``true``
+and ``false``. A bool value expresses the validity of a condition
+(tells whether the condition is true or false).::
+
+    local a = true;
+
+--------
+Table
+--------
+
+Tables are associative containers implemented as pairs of key/value (called a slot).::
+
+    local t={}
+    local test=
+    {
+        a=10
+        b=function(a) { return a+1; }
+    }
+
+--------
+Array
+--------
+
+Arrays are simple sequence of objects, their size is dynamic and their index starts always from 0.::
+
+    local a  = ["I'm","an","array"]
+    local b = [null]
+    b[0] = a[2];
+
+--------
+Function
+--------
+
+Functions are similar to those in other C-like languages and to most programming
+languages in general, however there are a few key differences (see below).
+
+--------
+Class
+--------
+
+Classes are associative containers implemented as pairs of key/value. Classes are created through
+a 'class expression' or a 'class statement'. class members can be inherited from another class object
+at creation time. After creation members can be added until a instance of the class is created.
+
+--------------
+Class Instance
+--------------
+
+Class instances are created by calling a *class object*. Instances, as tables, are
+implemented as pair of key/value. Instances members cannot be dyncamically added or removed however
+the value of the members can be changed.
+
+
+
+---------
+Generator
+---------
+
+Generators are functions that can be suspended with the statement 'yield' and resumed
+later (see :ref:`Generators <generators>`).
+
+---------
+Userdata
+---------
+
+Userdata objects are blobs of memory(or pointers) defined by the host application but
+stored into Squirrel variables (See :ref:`Userdata and UserPointers <embedding_userdata_and_userpointers>`).
+
+
+---------
+Thread
+---------
+
+Threads are objects that represents a cooperative thread of execution, also known as coroutines.
+
+--------------
+Weak Reference
+--------------
+
+Weak References are objects that point to another(non scalar) object but do not own a strong reference to it.
+(See :ref:`Weak References <weak_references>`).
+
+

doc/source/reference/language/delegation.rst

@@ -0,0 +1,35 @@
+.. _delegation:
+
+
+========================
+Delegation
+========================
+
+.. index::
+    single: Delegation
+
+Squirrel supports implicit delegation. Every table or userdata can have a parent table
+(delegate). A parent table is a normal table that allows the definition of special behaviors
+for his child.
+When a table (or userdata) is indexed with a key that doesn't correspond to one of its
+slots, the interpreter automatically delegates the get (or set) operation to its parent.::
+
+    Entity <- {
+    }
+
+    function Entity::DoStuff()
+    {
+        ::print(_name);
+    }
+
+    local newentity = {
+        _name="I'm the new entity"
+    }
+    newentity.setdelegate(Entity)
+
+    newentity.DoStuff(); //prints "I'm the new entity"
+
+The delegate of a table can be retreived through built-in method ``table.getdelegate()``.::
+
+    local thedelegate = newentity.getdelegate();
+

doc/source/reference/language/execution_context.rst

@@ -0,0 +1,95 @@
+.. _executioncontext:
+
+=======================
+Execution Context
+=======================
+
+.. index::
+    single: execution context
+
+The execution context is the union of the function stack frame and the function
+environment object(this) and the function root(root table).
+The stack frame is the portion of stack where the local variables declared in its body are
+stored.
+The environment object is an implicit parameter that is automatically passed by the
+function caller (see see :ref:`functions <functions>`).
+The root table is a table associated to the function during its creation.
+The root table value of a function is the root table of the VM at the function creation.
+The root table of function can also be changed after creation with closure.setroot().
+During the execution, the body of a function can only transparently refer to his execution
+context.
+This mean that a single identifier can refer to a local variable, to an environment object slot
+or to the slot of the closure root table;
+The environment object can be explicitly accessed by the keyword ``this``.
+The closure root table can be explicitly accessed through the operator ``::`` (see :ref:`Variables <variables>`).
+
+.. _variables:
+
+-----------------
+Variables
+-----------------
+
+There are two types of variables in Squirrel, local variables and tables/arrays slots.
+Because global variables(variables stored in the root of a closure) are stored in a table, they are table slots.
+
+A single identifier refers to a local variable or a slot in the environment object.::
+
+    derefexp := id;
+
+::
+
+    _table["foo"]
+    _array[10]
+
+with tables we can also use the '.' syntax::
+
+    derefexp := exp '.' id
+
+::
+
+    _table.foo
+
+Squirrel first checks if an identifier is a local variable (function arguments are local
+variables) if not looks up the environment object (this) and finally looksup
+to the closure root.
+
+For instance:::
+
+    function testy(arg)
+    {
+        local a=10;
+        print(a);
+        return arg;
+    }
+
+in this case 'foo' will be equivalent to 'this.foo' or this["foo"].
+
+Global variables are stored in a table called the root table. Usually in the global scope the
+environment object is the root table, but to explicitly access the closure root of the function from
+another scope, the slot name must be prefixed with ``'::'`` (``::foo``).
+
+For instance:::
+
+    function testy(arg)
+    {
+        local a=10;
+        return arg+::foo;
+    }
+
+accesses the variable 'foo' in the closure root table.
+
+Since Squirrel 3.1 each function has a weak reference to a specific root table, this can differ from the current VM root table.::
+
+    function test() {
+        foo = 10;
+    }
+
+is equivalent to write::
+
+    function test() {
+        if("foo" in this) {
+            this.foo = 10;
+        }else {
+            ::foo = 10;
+        }
+    }

doc/source/reference/language/expressions.rst

@@ -0,0 +1,374 @@
+.. _expressions:
+
+
+=================
+Expressions
+=================
+
+.. index::
+    single: Expressions
+
+----------------
+Assignment
+----------------
+
+.. index::
+    single: assignment(=)
+    single: new slot(<-)
+
+::
+
+    exp := derefexp '=' exp
+    exp:= derefexp '<-' exp
+
+squirrel implements 2 kind of assignment: the normal assignment(=)::
+
+    a = 10;
+
+and the "new slot" assignment.::
+
+    a <- 10;
+
+The new slot expression allows to add a new slot into a table(see :ref:`Tables <tables>`). If the slot
+already exists in the table it behaves like a normal assignment.
+
+----------------
+Operators
+----------------
+
+.. index::
+    single: Operators
+
+^^^^^^^^^^^^^
+?: Operator
+^^^^^^^^^^^^^
+
+.. index::
+    pair: ?: Operator; Operators
+
+::
+
+    exp := exp_cond '?' exp1 ':' exp2
+
+conditionally evaluate an expression depending on the result of an expression.
+
+^^^^^^^^^^^^^
+Arithmetic
+^^^^^^^^^^^^^
+
+.. index::
+    pair: Arithmetic Operators; Operators
+
+::
+
+    exp:= 'exp' op 'exp'
+
+Squirrel supports the standard arithmetic operators ``+, -, *, / and %``.
+Other than that is also supports compact operators (``+=,-=,*=,/=,%=``) and
+increment and decrement operators(++ and --);::
+
+    a += 2;
+    //is the same as writing
+    a = a + 2;
+    x++
+    //is the same as writing
+    x = x + 1
+
+All operators work normally with integers and floats; if one operand is an integer and one
+is a float the result of the expression will be float.
+The + operator has a special behavior with strings; if one of the operands is a string the
+operator + will try to convert the other operand to string as well and concatenate both
+together. For instances and tables, ``_tostring`` is invoked.
+
+^^^^^^^^^^^^^
+Relational
+^^^^^^^^^^^^^
+
+.. index::
+    pair: Relational Operators; Operators
+
+::
+
+    exp:= 'exp' op 'exp'
+
+Relational operators in Squirrel are : ``==, <, <=, <, <=, !=``
+
+These operators return true if the expression is false and a value different than true if the
+expression is true. Internally the VM uses the integer 1 as true but this could change in
+the future.
+
+^^^^^^^^^^^^^^
+3 ways compare
+^^^^^^^^^^^^^^
+
+.. index::
+    pair: 3 ways compare operator; Operators
+
+::
+
+    exp:= 'exp' <=> 'exp'
+
+the 3 ways compare operator <=> compares 2 values A and B and returns an integer less than 0
+if A < B, 0 if A == B and an integer greater than 0 if A > B.
+
+^^^^^^^^^^^^^^
+Logical
+^^^^^^^^^^^^^^
+
+.. index::
+    pair: Logical operators; Operators
+
+::
+
+    exp := exp op exp
+    exp := '!' exp
+
+Logical operators in Squirrel are : ``&&, ||, !``
+
+The operator ``&&`` (logical and) returns null if its first argument is null, otherwise returns
+its second argument.
+The operator ``||`` (logical or) returns its first argument if is different than null, otherwise
+returns the second argument.
+
+The '!' operator will return null if the given value to negate was different than null, or a
+value different than null if the given value was null.
+
+^^^^^^^^^^^^^^^
+in operator
+^^^^^^^^^^^^^^^
+
+.. index::
+    pair: in operator; Operators
+
+::
+
+    exp:= keyexp 'in' tableexp
+
+Tests the existence of a slot in a table.
+Returns true if *keyexp* is a valid key in *tableexp* ::
+
+    local t=
+    {
+        foo="I'm foo",
+        [123]="I'm not foo"
+    }
+
+    if("foo" in t) dostuff("yep");
+    if(123 in t) dostuff();
+
+^^^^^^^^^^^^^^^^^^^
+instanceof operator
+^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: instanceof operator; Operators
+
+::
+
+    exp:= instanceexp 'instanceof' classexp
+
+Tests if a class instance is an instance of a certain class.
+Returns true if *instanceexp* is an instance of *classexp*.
+
+^^^^^^^^^^^^^^^^^^^
+typeof operator
+^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: typeof operator; Operators
+
+::
+
+    exp:= 'typeof' exp
+
+returns the type name of a value as string.::
+
+    local a={},b="squirrel"
+    print(typeof a); //will print "table"
+    print(typeof b); //will print "string"
+
+^^^^^^^^^^^^^^^^^^^
+Comma operator
+^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: Comma operator; Operators
+
+::
+
+    exp:= exp ',' exp
+
+The comma operator evaluates two expression left to right, the result of the operator is
+the result of the expression on the right; the result of the left expression is discarded.::
+
+    local j=0,k=0;
+    for(local i=0; i<10; i++ , j++)
+    {
+        k = i + j;
+    }
+    local a,k;
+    a = (k=1,k+2); //a becomes 3
+
+^^^^^^^^^^^^^^^^^^^
+Bitwise Operators
+^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: Bitwise Operators; Operators
+
+::
+
+    exp:= 'exp' op 'exp'
+    exp := '~' exp
+
+Squirrel supports the standard c-like bit wise operators ``&, |, ^, ~, <<, >>`` plus the unsigned
+right shift operator ``<<<``. The unsigned right shift works exactly like the normal right shift operator(``<<``)
+except for treating the left operand as an unsigned integer, so is not affected by the sign. Those operators
+only work on integers values, passing of any other operand type to these operators will
+cause an exception.
+
+^^^^^^^^^^^^^^^^^^^^^
+Operators precedence
+^^^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: Operators precedence; Operators
+
++---------------------------------------+-----------+
+| ``-, ~, !, typeof , ++, --``          | highest   |
++---------------------------------------+-----------+
+| ``/, *, %``                           | ...       |
++---------------------------------------+-----------+
+| ``+, -``                              |           |
++---------------------------------------+-----------+
+| ``<<, >>, >>>``                       |           |
++---------------------------------------+-----------+
+| ``<, <=, >, >=``                      |           |
++---------------------------------------+-----------+
+| ``==, !=, <=>``                       |           |
++---------------------------------------+-----------+
+| ``&``                                 |           |
++---------------------------------------+-----------+
+| ``^``                                 |           |
++---------------------------------------+-----------+
+| ``&&, in``                            |           |
++---------------------------------------+-----------+
+| ``+=, =, -=``                         | ...       |
++---------------------------------------+-----------+
+| ``,(comma operator)``                 | lowest    |
++---------------------------------------+-----------+
+
+.. _table_contructor:
+
+-----------------
+Table Constructor
+-----------------
+
+.. index::
+    single: Table Contructor
+
+::
+
+    tslots := ( 'id' '=' exp | '[' exp ']' '=' exp ) [',']
+    exp := '{' [tslots] '}'
+
+Creates a new table.::
+
+    local a = {} //create an empty table
+
+A table constructor can also contain slots declaration; With the syntax: ::
+
+    local a = {
+        slot1 = "I'm the slot value"
+    }
+
+An alternative syntax can be::
+
+    '[' exp1 ']' = exp2 [',']
+
+A new slot with exp1 as key and exp2 as value is created::
+
+    local a=
+    {
+        [1]="I'm the value"
+    }
+
+both syntaxes can be mixed::
+
+    local table=
+    {
+        a=10,
+        b="string",
+        [10]={},
+        function bau(a,b)
+        {
+            return a+b;
+        }
+    }
+
+The comma between slots is optional.
+
+^^^^^^^^^^^^^^^^^^^^^^
+Table with JSON syntax
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    single: Table with JSON syntax
+
+Since Squirrel 3.0 is possible to declare a table using JSON syntax(see http://www.wikipedia.org/wiki/JSON).
+
+the following JSON snippet: ::
+
+    local x = {
+      "id": 1,
+      "name": "Foo",
+      "price": 123,
+      "tags": ["Bar","Eek"]
+    }
+
+is equivalent to the following squirrel code: ::
+
+    local x = {
+      id = 1,
+      name = "Foo",
+      price = 123,
+      tags = ["Bar","Eek"]
+    }
+
+-----------------
+clone
+-----------------
+
+.. index::
+    single: clone
+
+::
+
+    exp:= 'clone' exp
+
+Clone performs shallow copy of a table, array or class instance (copies all slots in the new object without
+recursion). If the source table has a delegate, the same delegate will be assigned as
+delegate (not copied) to the new table (see :ref:`Delegation <delegation>`).
+
+After the new object is ready the "_cloned" meta method is called (see :ref:`Metamethods <metamethods>`).
+
+When a class instance is cloned the constructor is not invoked(initializations must rely on ```_cloned``` instead
+
+-----------------
+Array contructor
+-----------------
+
+.. index::
+    single: Array constructor
+
+::
+
+    exp := '[' [explist] ']'
+
+Creates a new array.::
+
+    a <- [] //creates an empty array
+
+arrays can be initialized with values during the construction::
+
+    a <- [1,"string!",[],{}] //creates an array with 4 elements

doc/source/reference/language/functions.rst

@@ -0,0 +1,260 @@
+.. _functions:
+
+
+=================
+Functions
+=================
+
+.. index::
+    single: Functions
+
+Functions are first class values like integer or strings and can be stored in table slots,
+local variables, arrays and passed as function parameters.
+Functions can be implemented in Squirrel or in a native language with calling conventions
+compatible with ANSI C.
+
+--------------------
+Function declaration
+--------------------
+
+.. index::
+    single: Function Declaration
+
+Functions are declared through the function expression::
+
+    local a = function(a, b, c) { return a + b - c; }
+
+or with the syntactic sugar::
+
+    function ciao(a,b,c)
+    {
+        return a+b-c;
+    }
+
+that is equivalent to::
+
+    this.ciao <- function(a,b,c)
+    {
+        return a+b-c;
+    }
+
+a local function can be declared with this syntactic sugar::
+
+    local function tuna(a,b,c)
+    {
+        return a+b-c;
+    }
+
+that is equivalent to::
+
+    local tuna = function(a,b,c)
+    {
+        return a+b-c;
+    }
+
+is also possible to declare something like::
+
+    T <- {}
+    function T::ciao(a,b,c)
+    {
+        return a+b-c;
+    }
+
+    //that is equivalent to write
+
+    T.ciao <- function(a,b,c)
+    {
+        return a+b-c;
+    }
+
+    //or
+
+    T <- {
+        function ciao(a,b,c)
+        {
+            return a+b-c;
+        }
+    }
+
+^^^^^^^^^^^^^^^^^^
+Default Paramaters
+^^^^^^^^^^^^^^^^^^
+
+.. index::
+    single: Function Default Paramaters
+
+Squirrel's functions can have default parameters.
+
+A function with default parameters is declared as follows: ::
+
+    function test(a,b,c = 10, d = 20)
+    {
+        ....
+    }
+
+when the function *test* is invoked and the parameter c or d are not specified,
+the VM autometically assigns the default value to the unspecified parameter. A default parameter can be
+any valid squirrel expression. The expression is evaluated at runtime.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Function with variable number of paramaters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index::
+    single: Function with variable number of paramaters
+
+Squirrel's functions can have variable number of parameters(varargs functions).
+
+A vararg function is declared by adding three dots (`...`) at the end of its parameter list.
+
+When the function is called all the extra parameters will be accessible through the *array*
+called ``vargv``, that is passed as implicit parameter.
+
+``vargv`` is a regular squirrel array and can be used accordingly.::
+
+    function test(a,b,...)
+    {
+        for(local i = 0; i< vargv.len(); i++)
+        {
+            ::print("varparam "+i+" = "+vargv[i]+"\n");
+        }
+      foreach(i,val in vargv)
+        {
+            ::print("varparam "+i+" = "+val+"\n");
+        }
+    }
+
+    test("goes in a","goes in b",0,1,2,3,4,5,6,7,8);
+
+---------------
+Function calls
+---------------
+
+.. index::
+    single: Function calls
+
+::
+
+    exp:= derefexp '(' explist ')'
+
+The expression is evaluated in this order: derefexp after the explist (arguments) and at
+the end the call.
+
+Every function call in Squirrel passes the environment object *this* as hidden parameter
+to the called function. The 'this' parameter is the object where the function was indexed
+from.
+
+If we call a function with this syntax::
+
+    table.foo(a)
+
+the environment object passed to foo will be 'table'::
+
+    foo(x,y) // equivalent to this.foo(x,y)
+
+The environment object will be *this* (the same of the caller function).
+
+---------------------------------------------
+Binding an environment to a function
+---------------------------------------------
+
+.. index::
+    single: Binding an environment to a function
+
+while by default a squirrel function call passes as environment object 'this', the object
+where the function was indexed from. However, is also possible to statically bind an evironment to a
+closure using the built-in method ``closure.bindenv(env_obj)``.
+The method bindenv() returns a new instance of a closure with the environment bound to it.
+When an environment object is bound to a function, every time the function is invoked, its
+'this' parameter will always be the previously bound environent.
+This mechanism is useful to implement callbacks systems similar to C# delegates.
+
+.. note:: The closure keeps a weak reference to the bound environmet object, because of this if
+          the object is deleted, the next call to the closure will result in a ``null``
+          environment object.
+
+---------------------------------------------
+Lambda Expressions
+---------------------------------------------
+
+.. index::
+    single: Lambda Expressions
+
+::
+
+    exp := '@' '(' paramlist ')' exp
+
+Lambda expressions are a synctactic sugar to quickly define a function that consists of a single expression.
+This feature comes handy when functional programming patterns are applied, like map/reduce or passing a compare method to
+array.sort().
+
+here a lambda expression::
+
+    local myexp = @(a,b) a + b
+
+that is equivalent to::
+
+    local myexp = function(a,b) { return a + b; }
+
+a more useful usage could be::
+
+    local arr = [2,3,5,8,3,5,1,2,6];
+    arr.sort(@(a,b) a <=> b);
+    arr.sort(@(a,b) -(a <=> b));
+
+that could have been written as::
+
+    local arr = [2,3,5,8,3,5,1,2,6];
+    arr.sort(function(a,b) { return a <=> b; } );
+    arr.sort(function(a,b) { return -(a <=> b); } );
+
+other than being limited to a single expression lambdas support all features of regular functions.
+in fact are implemented as a compile time feature.
+
+---------------------------------------------
+Free Variables
+---------------------------------------------
+
+.. index::
+    single: Free Variables
+
+A free variable is a variable external from the function scope as is not a local variable
+or parameter of the function.
+Free variables reference a local variable from a outer scope.
+In the following example the variables 'testy', 'x' and 'y' are bound to the function 'foo'.::
+
+    local x=10,y=20
+    local testy="I'm testy"
+
+    function foo(a,b)
+    {
+        ::print(testy);
+        return a+b+x+y;
+    }
+
+A program can read or write a free variable.
+
+---------------------------------------------
+Tail Recursion
+---------------------------------------------
+
+.. index::
+    single: Tail Recursion
+
+Tail recursion is a method for partially transforming a recursion in a program into an
+iteration: it applies when the recursive calls in a function are the last executed
+statements in that function (just before the return).
+If this happenes the squirrel interpreter collapses the caller stack frame before the
+recursive call; because of that very deep recursions are possible without risk of a stack
+overflow.::
+
+    function loopy(n)
+    {
+        if(n>0){
+            ::print("n="+n+"\n");
+            return loopy(n-1);
+        }
+    }
+
+    loopy(1000);
+

doc/source/reference/language/generators.rst

@@ -0,0 +1,51 @@
+.. _generators:
+
+
+=================
+Generators
+=================
+
+.. index::
+    single: Generators
+
+A function that contains a ``yield`` statement is called *'generator function'* .
+When a generator function is called, it does not execute the function body, instead it
+returns a new suspended generator.
+The returned generator can be resumed through the resume statement while it is alive.
+The yield keyword, suspends the execution of a generator and optionally returns the
+result of an expression to the function that resumed the generator.
+The generator dies when it returns, this can happen through an explicit return
+statement or by exiting the function body; If an unhandled exception (or runtime error)
+occurs while a generator is running, the generator will automatically die. A dead
+generator cannot be resumed anymore.::
+
+    function geny(n)
+    {
+        for(local i=1;i<=n;i+=1)
+            yield i;
+        return null;
+    }
+
+    local gtor=geny(10);
+    local x;
+    while(x=resume gtor) print(x+"\n");
+
+the output of this program will be::
+
+    1
+    2
+    3
+    4
+    5
+    6
+    7
+    8
+    9
+    10
+
+generators can also be iterated using the foreach statement. When a generator is evaluated
+by ``foreach``, the generator will be resumed for each iteration until it returns. The value
+returned by the ``return`` statement will be ignored.
+
+.. note:: A suspended generator will hold a strong reference to all the values stored in it's local variables except the ``this``
+        object that is only a weak reference. A running generator hold a strong reference also to the ``this`` object.

doc/source/reference/language/lexical_structure.rst

@@ -0,0 +1,156 @@
+.. _lexical_structure:
+
+
+=================
+Lexical Structure
+=================
+
+.. index:: single: lexical structure
+
+-----------
+Identifiers
+-----------
+
+.. index:: single: identifiers
+
+Identifiers start with a alphabetic character or '_' followed by any number of alphabetic
+characters, '_' or digits ([0-9]). Squirrel is a case sensitive language, this means that the
+lowercase and uppercase representation of the same alphabetic character are considered
+different characters. For instance "foo", "Foo" and "fOo" will be treated as 3 distinct
+identifiers.
+
+-----------
+Keywords
+-----------
+
+.. index:: single: keywords
+
+The following words are reserved words by the language and cannot be used as identifiers:
+
++------------+------------+-----------+------------+------------+-------------+
+| base       | break      | case      | catch      | class      | clone       |
++------------+------------+-----------+------------+------------+-------------+
+| continue   | const      | default   | delete     | else       | enum        |
++------------+------------+-----------+------------+------------+-------------+
+| extends    | for        | foreach   | function   | if         | in          |
++------------+------------+-----------+------------+------------+-------------+
+| local      | null       | resume    | return     | switch     | this        |
++------------+------------+-----------+------------+------------+-------------+
+| throw      | try        | typeof    | while      | yield      | constructor |
++------------+------------+-----------+------------+------------+-------------+
+| instanceof | true       | false     | static     | __LINE__   | __FILE__    |
++------------+------------+-----------+------------+------------+-------------+
+
+Keywords are covered in detail later in this document.
+
+-----------
+Operators
+-----------
+
+.. index:: single: operators
+
+Squirrel recognizes the following operators:
+
++----------+----------+----------+----------+----------+----------+----------+----------+
+| ``!``    | ``!=``   | ``||``   | ``==``   | ``&&``   | ``>=``   | ``<=``   | ``>``    |
++----------+----------+----------+----------+----------+----------+----------+----------+
+| ``<=>``  | ``+``    | ``+=``   | ``-``    | ``-=``   | ``/``    | ``/=``   | ``*``    |
++----------+----------+----------+----------+----------+----------+----------+----------+
+| ``*=``   | ``%``    | ``%=``   | ``++``   | ``--``   | ``<-``   | ``=``    | ``&``    |
++----------+----------+----------+----------+----------+----------+----------+----------+
+| ``^``    | ``|``    | ``~``    | ``>>``   | ``<<``   | ``>>>``  |          |          |
++----------+----------+----------+----------+----------+----------+----------+----------+
+
+------------
+Other tokens
+------------
+
+.. index::
+    single: delimiters
+    single: other tokens
+
+Other used tokens are:
+
++----------+----------+----------+----------+----------+----------+
+| ``{``    | ``}``    | ``[``    | ``]``    | ``.``    | ``:``    |
++----------+----------+----------+----------+----------+----------+
+| ``::``   | ``'``    | ``;``    | ``"``    | ``@"``   |          |
++----------+----------+----------+----------+----------+----------+
+
+-----------
+Literals
+-----------
+
+.. index::
+    single: literals
+    single: string literals
+    single: numeric literals
+
+Squirrel accepts integer numbers, floating point numbers and strings literals.
+
++-------------------------------+------------------------------------------+
+| ``34``                        | Integer number(base 10)                  |
++-------------------------------+------------------------------------------+
+| ``0xFF00A120``                | Integer number(base 16)                  |
++-------------------------------+------------------------------------------+
+| ``0753``                      | Integer number(base 8)                   |
++-------------------------------+------------------------------------------+
+| ``'a'``                       | Integer number                           |
++-------------------------------+------------------------------------------+
+| ``1.52``                      | Floating point number                    |
++-------------------------------+------------------------------------------+
+| ``1.e2``                      | Floating point number                    |
++-------------------------------+------------------------------------------+
+| ``1.e-2``                     | Floating point number                    |
++-------------------------------+------------------------------------------+
+| ``"I'm a string"``            | String                                   |
++-------------------------------+------------------------------------------+
+| ``@"I'm a verbatim string"``  | String                                   |
++-------------------------------+------------------------------------------+
+| ``@" I'm a``                  |                                          |
+| ``multiline verbatim string`` |                                          |
+| ``"``                         | String                                   |
++-------------------------------+------------------------------------------+
+
+Pesudo BNF
+
+.. productionlist::
+    IntegerLiteral : [1-9][0-9]* | '0x' [0-9A-Fa-f]+ | ''' [.]+ ''' | 0[0-7]+
+    FloatLiteral : [0-9]+ '.' [0-9]+
+    FloatLiteral : [0-9]+ '.' 'e'|'E' '+'|'-' [0-9]+
+    StringLiteral: '"'[.]* '"'
+    VerbatimStringLiteral: '@''"'[.]* '"'
+
+-----------
+Comments
+-----------
+
+.. index:: single: comments
+
+A comment is text that the compiler ignores but that is useful for programmers.
+Comments are normally used to embed annotations in the code. The compiler
+treats them as white space.
+
+The ``/*`` (slash, asterisk) characters, followed by any
+sequence of characters (including new lines),
+followed by the ``*/`` characters. This syntax is the same as ANSI C.::
+
+    /*
+    this is
+    a multiline comment.
+    this lines will be ignored by the compiler
+    */
+
+The ``//`` (two slashes) characters, followed by any sequence of characters.
+A new line not immediately preceded by a backslash terminates this form of comment.
+It is commonly called a *"single-line comment."*::
+
+    //this is a single line comment. this line will be ignored by the compiler
+
+The character ``#`` is an alternative syntax for single line comment.::
+
+    # this is also a single line comment.
+
+This to facilitate the use of squirrel in UNIX-style shell scripts.
+
+

doc/source/reference/language/metamethods.rst

@@ -0,0 +1,270 @@
+.. _metamethods:
+
+-----------
+Metamethods
+-----------
+
+Metamethods are a mechanism that allows the customization of certain aspects of the
+language semantics. Those methods are normal functions placed in a table
+parent(delegate) or class declaration; Is possible to change many aspect of a table/class instance behavior by just defining
+a metamethod. Class objects(not instances) supports only 2 metamethods ``_newmember, _inherited`` .
+
+For example when we use relational operators other than '==' on 2 tables, the VM will
+check if the table has a method in his parent called '_cmp' if so it will call it to determine
+the relation between the tables.::
+
+    local comparable={
+        _cmp = function (other)
+        {
+            if(name<other.name)return -1;
+            if(name>other.name)return 1;
+            return 0;
+        }
+    }
+
+    local a={ name="Alberto" }.setdelegate(comparable);
+    local b={ name="Wouter" }.setdelegate(comparable);
+
+    if(a>b)
+        print("a>b")
+    else
+        print("b<=a");
+
+for classes the previous code become: ::
+
+    class Comparable {
+        constructor(n)
+        {
+            name = n;
+        }
+        function _cmp(other)
+        {
+            if(name<other.name) return -1;
+            if(name>other.name) return 1;
+            return 0;
+        }
+        name = null;
+    }
+
+    local a = Comparable("Alberto");
+    local b = Comparable("Wouter");
+
+    if(a>b)
+        print("a>b")
+    else
+        print("b<=a");
+
+^^^^^
+_set
+^^^^^
+
+::
+
+    _set(idx,val)
+
+invoked when the index idx is not present in the object or in its delegate chain.
+``_set`` must 'throw null' to notify that a key wasn't found but the there were not runtime errors(clean failure).
+This allows the program to defferentieate between a runtime error and a 'index not found'.
+
+^^^^^
+_get
+^^^^^
+
+::
+
+    _get(idx,val)
+
+invoked when the index idx is not present in the object or in its delegate chain.
+_get must 'throw null' to notify that a key wasn't found but the there were not runtime errors(clean failure).
+This allows the program to defferentieate between a runtime error and a 'index not found'.
+
+^^^^^^^^^
+_newslot
+^^^^^^^^^
+
+::
+
+    _newslot(key,value)
+
+invoked when a script tries to add a new slot in a table.
+
+if the slot already exists in the target table the method will not be invoked also if the
+"new slot" operator is used.
+
+^^^^^^^^^
+_delslot
+^^^^^^^^^
+
+::
+
+    _delslot(key)
+
+invoked when a script deletes a slot from a table.
+if the method is invoked squirrel will not try to delete the slot himself
+
+^^^^^^^^
+_add
+^^^^^^^^
+
+::
+
+    _add(other)
+
+the + operator
+
+returns this + other
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_sub
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _sub(other)
+
+the - operator (like _add)
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_mul
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _mul(other)
+
+the ``*`` operator (like _add)
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_div
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _div(other)
+
+the ``/`` operator (like _add)
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_modulo
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _modulo(other)
+
+the ``%`` operator (like _add)
+
+^^^^^^^^^
+_unm
+^^^^^^^^^
+
+::
+
+    _unm()
+
+the unary minus operator
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_tyoeof
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _tyoeof()
+
+invoked by the typeof operator on tables ,userdata and class instances
+
+returns the type of ``this`` as string
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_cmp
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _cmp(other)
+
+invoked to emulate the ``< > <= >=`` and ``<=>`` operators
+
+returns an integer as follow:
+
++-----------+----------------------------+
+| returns   | relationship               |
++===========+============================+
+|  > 0      | if ``this`` > ``other``    |
++-----------+----------------------------+
+|  0        | if ``this`` == ``other``   |
++-----------+----------------------------+
+|  < 0      | if ``this`` < ``other``    |
++-----------+----------------------------+
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_call
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _call(other)
+
+invoked when a table, userdata or class instance is called
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_cloned
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _cloned(original)
+
+invoked when a table or class instance is cloned(in the cloned table)
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_nexti
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _nexti(previdx)
+
+invoked when a userdata or class instance is iterated by a foreach loop
+
+if previdx==null it means that it is the first iteration.
+The function has to return the index of the 'next' value.
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_tostring
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _tostring(previdx)
+
+invoked when during string conacatenation or when the ``print`` function prints a table, instance or userdata.
+The method is also invoked by the sq_tostring() api
+
+must return a string representation of the object.
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_inherited
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _inherited(attributes)
+
+invoked when a class object inherits from the class implementing ``_inherited``
+the ``this`` contains the new class.
+
+return value is ignored.
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+_newmember
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _newmember(index,value,attributes,isstatic)
+
+invoked for each member declared in a class body(at declaration time).
+
+if the function is implemented, members will not be added to the class.

doc/source/reference/language/statements.rst

@@ -0,0 +1,386 @@
+.. _statements:
+
+
+=================
+Statements
+=================
+
+.. index::
+    single: statements
+
+A squirrel program is a simple sequence of statements.::
+
+    stats := stat [';'|'\n'] stats
+
+Statements in squirrel are comparable to the C-Family languages (C/C++, Java, C#
+etc...): assignment, function calls, program flow control structures etc.. plus some
+custom statement like yield, table and array constructors (All those will be covered in detail
+later in this document).
+Statements can be separated with a new line or ';' (or with the keywords case or default if
+inside a switch/case statement), both symbols are not required if the statement is
+followed by '}'.
+
+------
+Block
+------
+
+.. index::
+    pair: block; statement
+
+::
+
+    stat := '{' stats '}'
+
+A sequence of statements delimited by curly brackets ({ }) is called block;
+a block is a statement itself.
+
+-----------------------
+Control Flow Statements
+-----------------------
+
+.. index::
+    single: control flow statements
+
+squirrel implements the most common control flow statements: ``if, while, do-while, switch-case, for, foreach``
+
+^^^^^^^^^^^^^^
+true and false
+^^^^^^^^^^^^^^
+
+.. index::
+    single: true and false
+    single: true
+    single: false
+
+Squirrel has a boolean type(bool) however like C++ it considers null, 0(integer) and 0.0(float)
+as *false*, any other value is considered *true*.
+
+^^^^^^^^^^^^^^^^^
+if/else statement
+^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: if/else; statement
+    pair: if; statement
+    pair: else; statement
+
+::
+
+    stat:= 'if' '(' exp ')' stat ['else' stat]
+
+Conditionally execute a statement depending on the result of an expression.::
+
+    if(a>b)
+        a=b;
+    else
+        b=a;
+    ////
+    if(a==10)
+    {
+        b=a+b;
+        return a;
+    }
+
+^^^^^^^^^^^^^^^^^
+while statement
+^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: while; statement
+
+::
+
+    stat:= 'while' '(' exp ')' stat
+
+Executes a statement while the condition is true.::
+
+    function testy(n)
+    {
+        local a=0;
+        while(a<n) a+=1;
+
+        while(1)
+        {
+            if(a<0) break;
+            a-=1;
+        }
+    }
+
+^^^^^^^^^^^^^^^^^^
+do/while statement
+^^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: do/while; statement
+
+::
+
+    stat:= 'do' stat 'while' '(' expression ')'
+
+Executes a statement once, and then repeats execution of the statement until a condition
+expression evaluates to false.::
+
+    local a=0;
+    do
+    {
+        print(a+"\n");
+        a+=1;
+    } while(a>100)
+
+^^^^^^^^^^^^^^^^^
+switch statement
+^^^^^^^^^^^^^^^^^
+
+.. index::
+    pair: switch; statement
+
+::
+
+    stat := 'switch' ''( exp ')' '{'
+    'case' case_exp ':'
+        stats
+    ['default' ':'
+        stats]
+    '}'
+
+Switch is a control statement allows multiple selections of code by passing control to one of the
+case statements within its body.
+The control is transferred to the case label whose case_exp matches with exp if none of
+the case match will jump to the default label (if present).
+A switch statement can contain any number if case instances, if 2 case have the same
+expression result the first one will be taken in account first. The default label is only
+allowed once and must be the last one.
+A break statement will jump outside the switch block.
+
+-----
+Loops
+-----
+
+.. index::
+    single: Loops
+
+^^^^^^^^
+for
+^^^^^^^^
+
+.. index::
+    pair: for; statement
+
+::
+
+    stat:= 'for' '(' [initexp] ';' [condexp] ';' [incexp] ')' statement
+
+Executes a statement as long as a condition is different than false.::
+
+    for(local a=0;a<10;a+=1)
+        print(a+"\n");
+    //or
+    glob <- null
+    for(glob=0;glob<10;glob+=1){
+        print(glob+"\n");
+    }
+    //or
+    for(;;){
+        print(loops forever+"\n");
+    }
+
+^^^^^^^^
+foreach
+^^^^^^^^
+
+.. index::
+    pair: foreach; statement
+
+::
+
+    'foreach' '(' [index_id','] value_id 'in' exp ')' stat
+
+Executes a statement for every element contained in an array, table, class, string or generator.
+If exp is a generator it will be resumed every iteration as long as it is alive; the value will
+be the result of 'resume' and the index the sequence number of the iteration starting
+from 0.::
+
+    local a=[10,23,33,41,589,56]
+    foreach(idx,val in a)
+        print("index="+idx+" value="+val+"\n");
+    //or
+    foreach(val in a)
+        print("value="+val+"\n");
+
+-------
+break
+-------
+
+.. index::
+    pair: break; statement
+
+::
+
+    stat := 'break'
+
+The break statement terminates the execution of a loop (for, foreach, while or do/while)
+or jumps out of switch statement;
+
+---------
+continue
+---------
+
+.. index::
+    pair: continue; statement
+
+::
+
+    stat := 'continue'
+
+The continue operator jumps to the next iteration of the loop skipping the execution of
+the following statements.
+
+---------
+return
+---------
+
+.. index::
+    pair: return; statement
+
+::
+
+    stat:= return [exp]
+
+The return statement terminates the execution of the current function/generator and
+optionally returns the result of an expression. If the expression is omitted the function
+will return null. If the return statement is used inside a generator, the generator will not
+be resumable anymore.
+
+---------
+yield
+---------
+
+.. index::
+    pair: yield; statement
+
+::
+
+    stat := yield [exp]
+
+(see :ref:`Generators <generators>`).
+
+
+---------------------------
+Local variables declaration
+---------------------------
+
+.. index::
+    pair: Local variables declaration; statement
+
+::
+
+    initz := id [= exp][',' initz]
+    stat := 'local' initz
+
+Local variables can be declared at any point in the program; they exist between their
+declaration to the end of the block where they have been declared.
+*EXCEPTION:* a local declaration statement is allowed as first expression in a for loop.::
+
+    for(local a=0;a<10;a+=1)
+        print(a);
+
+--------------------
+Function declaration
+--------------------
+
+.. index::
+    pair: Function declaration; statement
+
+::
+
+    funcname := id ['::' id]
+    stat:= 'function' id ['::' id]+ '(' args ')' stat
+
+creates a new function.
+
+-----------------
+Class declaration
+-----------------
+
+.. index::
+    pair: Class declaration; statement
+
+::
+
+    memberdecl := id '=' exp [';'] |    '[' exp ']' '=' exp [';'] | functionstat | 'constructor' functionexp
+    stat:= 'class' derefexp ['extends' derefexp] '{'
+            [memberdecl]
+        '}'
+
+creates a new class.
+
+-----------
+try/catch
+-----------
+
+.. index::
+    pair: try/catch; statement
+
+::
+
+    stat:= 'try' stat 'catch' '(' id ')' stat
+
+The try statement encloses a block of code in which an exceptional condition can occur,
+such as a runtime error or a throw statement. The catch clause provides the exceptionhandling
+code. When a catch clause catches an exception, its id is bound to that
+exception.
+
+-----------
+throw
+-----------
+
+.. index::
+    pair: throw; statement
+
+::
+
+    stat:= 'throw' exp
+
+Throws an exception. Any value can be thrown.
+
+--------------
+const
+--------------
+
+.. index::
+    pair: const; statement
+
+::
+
+    stat:= 'const' id '=' 'Integer | Float | StringLiteral
+
+Declares a constant (see :ref:`Constants & Enumerations <constants_and_enumerations>`).
+
+--------------
+enum
+--------------
+
+.. index::
+    pair: enum; statement
+
+::
+
+    enumerations := ( 'id' '=' Integer | Float | StringLiteral ) [',']
+    stat:= 'enum' id '{' enumerations '}'
+
+Declares an enumeration (see :ref:`Constants & Enumerations <constants_and_enumerations>`).
+
+--------------------
+Expression statement
+--------------------
+
+.. index::
+    pair: Expression statement; statement
+
+::
+
+    stat := exp
+
+In Squirrel every expression is also allowed as statement, if so, the result of the
+expression is thrown away.
+

doc/source/reference/language/tables.rst

@@ -0,0 +1,71 @@
+.. _tables:
+
+
+=================
+Tables
+=================
+
+.. index::
+    single: Tables
+
+Tables are associative containers implemented as pairs of key/value (called slot); values
+can be any possible type and keys any type except 'null'.
+Tables are squirrel's skeleton, delegation and many other features are all implemented
+through this type; even the environment, where "global" variables are stored, is a table
+(known as root table).
+
+------------------
+Construction
+------------------
+
+Tables are created through the table constructor (see :ref:`Table constructor <table_contructor>`)
+
+------------------
+Slot creation
+------------------
+
+.. index::
+    single: Slot Creation(table)
+
+Adding a new slot in a existing table is done through the "new slot" operator ``<-``; this
+operator behaves like a normal assignment except that if the slot does not exists it will
+be created.::
+
+    local a = {}
+
+The following line will cause an exception because the slot named 'newslot' does not exist
+in the table 'a'::
+
+    a.newslot = 1234
+
+this will succeed: ::
+
+    a.newslot <- 1234;
+
+or::
+
+    a[1] <- "I'm the value of the new slot";
+
+-----------------
+Slot deletion
+-----------------
+
+.. index::
+    single: Slot Deletion(table)
+
+
+::
+
+    exp:= delete derefexp
+
+Deletion of a slot is done through the keyword delete; the result of this expression will be
+the value of the deleted slot.::
+
+    a <- {
+        test1=1234
+        deleteme="now"
+    }
+
+    delete a.test1
+    print(delete a.deleteme); //this will print the string "now"
+

doc/source/reference/language/threads.rst

@@ -0,0 +1,106 @@
+.. _threads:
+
+
+========================
+Threads
+========================
+
+.. index::
+    single: Threads
+
+Squirrel supports cooperative threads(also known as coroutines).
+A cooperative thread is a subroutine that can suspended in mid-execution and provide a value to the
+caller without returning program flow, then its execution can be resumed later from the same
+point where it was suspended.
+At first look a Squirrel thread can be confused with a generator, in fact their behaviour is quite similar.
+However while a generator runs in the caller stack and can suspend only the local routine stack a thread
+has its own execution stack, global table and error handler; This allows a thread to suspend nested calls and
+have it's own error policies.
+
+------------------
+Using threads
+------------------
+
+.. index::
+    single: Usign Threads
+
+Threads are created through the built-in function 'newthread(func)'; this function
+gets as parameter a squirrel function and bind it to the new thread objecs(will be the thread body).
+The returned thread object is initially in 'idle' state. the thread can be started with the function
+'threadobj.call()'; the parameters passed to 'call' are passed to the thread function.
+
+A thread can be be suspended calling the function suspend(), when this happens the function
+that wokeup(or started) the thread returns (If a parametrer is passed to suspend() it will
+be the return value of the wakeup function , if no parameter is passed the return value will be null).
+A suspended thread can be resumed calling the funtion 'threadobj.wakeup', when this happens
+the function that suspended the thread will return(if a parameter is passed to wakeup it will
+be the return value of the suspend function, if no parameter is passed the return value will be null).
+
+A thread terminates when its main function returns or when an unhandled exception occurs during its execution.::
+
+    function coroutine_test(a,b)
+    {
+        ::print(a+" "+b+"\n");
+        local ret = ::suspend("suspend 1");
+        ::print("the coroutine says "+ret+"\n");
+        ret = ::suspend("suspend 2");
+        ::print("the coroutine says "+ret+"\n");
+        ret = ::suspend("suspend 3");
+        ::print("the coroutine says "+ret+"\n");
+        return "I'm done"
+    }
+
+    local coro = ::newthread(coroutine_test);
+
+    local susparam = coro.call("test","coroutine"); //starts the coroutine
+
+    local i = 1;
+    do
+    {
+        ::print("suspend passed ("+susparam+")\n")
+        susparam = coro.wakeup("ciao "+i);
+        ++i;
+    }while(coro.getstatus()=="suspended")
+
+    ::print("return passed ("+susparam+")\n")
+
+the result of this program will be::
+
+    test coroutine
+    suspend passed (suspend 1)
+    the coroutine says ciao 1
+    suspend passed (suspend 2)
+    the coroutine says ciao 2
+    suspend passed (suspend 3)
+    the coroutine says ciao 3
+    return passed (I'm done).
+
+
+the following is an interesting example of how threads and tail recursion
+can be combined.::
+
+    function state1()
+    {
+        ::suspend("state1");
+        return state2(); //tail call
+    }
+
+    function state2()
+    {
+        ::suspend("state2");
+        return state3(); //tail call
+    }
+
+    function state3()
+    {
+        ::suspend("state3");
+        return state1(); //tail call
+    }
+
+    local statethread = ::newthread(state1)
+
+    ::print(statethread.call()+"\n");
+
+    for(local i = 0; i < 10000; i++)
+        ::print(statethread.wakeup()+"\n");
+

doc/source/reference/language/weak_references.rst

@@ -0,0 +1,61 @@
+.. _weak_references:
+
+
+========================
+Weak References
+========================
+
+.. index::
+    single: Weak References
+
+
+The weak references allows the programmers to create references to objects without
+influencing the lifetime of the object itself.
+In squirrel Weak references are first-class objects created through the built-in method obj.weakref().
+All types except null implement the weakref() method; however in bools,integers and float the method
+simply returns the object itself(this because this types are always passed by value).
+When a weak references is assigned to a container (table slot,array,class or
+instance) is treated differently than other objects; When a container slot that hold a weak
+reference is fetched, it always returns the value pointed by the weak reference instead of the weak
+reference object. This allow the programmer to ignore the fact that the value handled is weak.
+When the object pointed by weak reference is destroyed, the weak reference is automatically set to null.::
+
+    local t = {}
+    local a = ["first","second","third"]
+    //creates a weakref to the array and assigns it to a table slot
+    t.thearray <- a.weakref();
+
+The table slot 'thearray' contains a weak reference to an array.
+The following line prints "first", because tables(and all other containers) always return
+the object pointed by a weak ref::
+
+    print(t.thearray[0]);
+
+the only strong reference to the array is owned by the local variable 'a', so
+because the following line assigns a integer to 'a' the array is destroyed.::
+
+    a = 123;
+
+When an object pointed by a weak ref is destroyed the weak ref is automatically set to null,
+so the following line will print "null".::
+
+    ::print(typeof(t.thearray))
+
+-----------------------------------
+Handling weak references explicitly
+-----------------------------------
+
+If a weak reference is assigned to a local variable, then is treated as any other value.::
+
+    local t = {}
+    local weakobj = t.weakref();
+
+the following line prints "weakref".::
+
+    ::print(typeof(weakobj))
+
+the object pointed by the weakref can be obtained through the built-in method weakref.ref().
+
+The following line prints "table".::
+
+    ::print(typeof(weakobj.ref()))

doc/source/stdlib/index.rst

@@ -0,0 +1,39 @@
+.. _stdlib:
+
+#################################
+  Squirrel Standard Library 3.1
+#################################
+
+Copyrigth (c) 2003-2016 Alberto Demichelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   introduction.rst
+   stdiolib.rst
+   stdbloblib.rst
+   stdmathlib.rst
+   stdsystemlib.rst
+   stdstringlib.rst
+   stdauxlib.rst
+

doc/source/stdlib/introduction.rst

@@ -0,0 +1,22 @@
+.. _stdlib_introduction:
+
+============
+Introduction
+============
+
+The squirrel standard libraries consist in a set of modules implemented in C++.
+While are not essential for the language, they provide a set of useful services that are
+commonly used by a wide range of applications(file I/O, regular expressions, etc...),
+plus they offer a foundation for developing additional libraries.
+
+All libraries are implemented through the squirrel API and the ANSI C runtime library.
+The modules are organized in the following way:
+
+* I/O : input and output
+* blob : binary buffers manipilation
+* math : basic mathematical routines
+* system : system access function
+* string : string formatting and manipulation
+* aux : auxiliary functions
+
+The libraries can be registered independently,except for the IO library that depends from the bloblib.

doc/source/stdlib/stdauxlib.rst

@@ -0,0 +1,31 @@
+.. _stdlib_stdauxlib:
+
+===============
+The Aux library
+===============
+
+The aux library implements default handlers for compiler and runtime errors and a stack dumping.
+
++++++++++++
+C API
++++++++++++
+
+.. _sqstd_seterrorhandlers:
+
+.. c:function:: void sqstd_seterrorhandlers(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+    initialize compiler and runtime error handlers, the handlers
+    use the print function set through(:ref:`sq_setprintfunc <sq_setprintfunc>`) to output
+    the error.
+
+.. _sqstd_printcallstack:
+
+.. c:function:: void sqstd_printcallstack(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+
+    prints the call stack and stack contents. the function
+    uses the print function set through(:ref:`sq_setprintfunc <sq_setprintfunc>`) to output
+    the stack dump.

doc/source/stdlib/stdbloblib.rst

@@ -0,0 +1,213 @@
+.. _stdlib_stdbloblib:
+
+==================
+The Blob library
+==================
+The blob library implements binary data manipulations routines. The library is
+based on `blob objects` that rapresent a buffer of arbitrary
+binary data.
+
+---------------
+Squirrel API
+---------------
+
++++++++++++++++
+Global symbols
++++++++++++++++
+
+.. js:function:: castf2i(f)
+
+    casts a float to a int
+
+.. js:function:: casti2f(n)
+
+    casts a int to a float
+
+.. js:function:: swap2(n)
+
+    swap the byte order of a number (like it would be a 16bits integer)
+
+.. js:function:: swap4(n)
+
+    swap the byte order of an integer
+
+.. js:function:: swapfloat(n)
+
+    swaps the byteorder of a float
+
+++++++++++++++++++
+The blob class
+++++++++++++++++++
+
+The blob object is a buffer of arbitrary binary data. The object behaves like
+a file stream, it has a read/write pointer and it automatically grows if data
+is written out of his boundary.
+A blob can also be accessed byte by byte through the `[]` operator.
+
+.. js:class:: blob(size)
+
+    :param int size: initial size of the blob
+
+    returns a new instance of a blob class of the specified size in bytes
+
+.. js:function:: blob.eos()
+
+    returns a non null value if the read/write pointer is at the end of the stream.
+
+.. js:function:: blob.flush()
+
+    flushes the stream.return a value != null if succeded, otherwise returns null
+
+.. js:function:: blob.len()
+
+    returns the lenght of the stream
+
+.. js:function:: blob.readblob(size)
+
+    :param int size: number of bytes to read
+
+    read n bytes from the stream and retuns them as blob
+
+.. js:function:: blob.readn(type)
+
+    :param int type: type of the number to read
+
+    reads a number from the stream according to the type pameter.
+
+    `type` can have the following values:
+
++--------------+--------------------------------------------------------------------------------+----------------------+
+| parameter    | return description                                                             |  return type         |
++==============+================================================================================+======================+
+| 'l'          | processor dependent, 32bits on 32bits processors, 64bits on 64bits prcessors   |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'i'          | 32bits number                                                                  |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 's'          | 16bits signed integer                                                          |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'w'          | 16bits unsigned integer                                                        |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'c'          | 8bits signed integer                                                           |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'b'          | 8bits unsigned integer                                                         |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'f'          | 32bits float                                                                   |  float               |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'd'          | 64bits float                                                                   |  float               |
++--------------+--------------------------------------------------------------------------------+----------------------+
+
+.. js:function:: blob.resize(size)
+
+    :param int size: the new size of the blobl in bytes
+
+    resizes the blob to the specified `size`
+
+.. js:function:: blob.seek(offset [,origin])
+
+    :param int offset: indicates the number of bytes from `origin`.
+    :param int origin: origin of the seek
+
+                        +--------------+-------------------------------------------+
+                        |  'b'         |  beginning of the stream                  |
+                        +--------------+-------------------------------------------+
+                        |  'c'         |  current location                         |
+                        +--------------+-------------------------------------------+
+                        |  'e'         |  end of the stream                        |
+                        +--------------+-------------------------------------------+
+
+    Moves the read/write pointer to a specified location.
+
+.. note:: If origin is omitted the parameter is defaulted as 'b'(beginning of the stream).
+
+.. js:function:: blob.swap2()
+
+    swaps the byte order of the blob content as it would be an array of `16bits integers`
+
+.. js:function:: blob.swap4()
+
+    swaps the byte order of the blob content as it would be an array of `32bits integers`
+
+.. js:function:: blob.tell()
+
+    returns the read/write pointer absolute position
+
+.. js:function:: blob.writeblob(src)
+
+    :param blob src: the source blob containing the data to be written
+
+    writes a blob in the stream
+
+.. js:function:: blob.writen(n, type)
+
+    :param number n: the value to be written
+    :param int type: type of the number to write
+
+    writes a number in the stream formatted according to the `type` pameter
+
+    `type` can have the following values:
+
++--------------+--------------------------------------------------------------------------------+
+| parameter    | return description                                                             |
++==============+================================================================================+
+| 'i'          | 32bits number                                                                  |
++--------------+--------------------------------------------------------------------------------+
+| 's'          | 16bits signed integer                                                          |
++--------------+--------------------------------------------------------------------------------+
+| 'w'          | 16bits unsigned integer                                                        |
++--------------+--------------------------------------------------------------------------------+
+| 'c'          | 8bits signed integer                                                           |
++--------------+--------------------------------------------------------------------------------+
+| 'b'          | 8bits unsigned integer                                                         |
++--------------+--------------------------------------------------------------------------------+
+| 'f'          | 32bits float                                                                   |
++--------------+--------------------------------------------------------------------------------+
+| 'd'          | 64bits float                                                                   |
++--------------+--------------------------------------------------------------------------------+
+
+
+------
+C API
+------
+
+.. _sqstd_register_bloblib:
+
+.. c:function:: SQRESULT sqstd_register_bloblib(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an SQRESULT
+    :remarks: The function aspects a table on top of the stack where to register the global library functions.
+
+    initializes and registers the blob library in the given VM.
+
+.. _sqstd_getblob:
+
+.. c:function:: SQRESULT sqstd_getblob(HSQUIRRELVM v, SQInteger idx, SQUserPointer* ptr)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger idx: and index in the stack
+    :param SQUserPointer* ptr: A pointer to the userpointer that will point to the blob's payload
+    :returns: an SQRESULT
+
+    retrieve the pointer of a blob's payload from an arbitrary
+    position in the stack.
+
+.. _sqstd_getblobsize:
+
+.. c:function:: SQInteger sqstd_getblobsize(HSQUIRRELVM v, SQInteger idx)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger idx: and index in the stack
+    :returns: the size of the blob at `idx` position
+
+    retrieves the size of a blob's payload from an arbitrary
+    position in the stack.
+
+.. _sqstd_createblob:
+
+.. c:function:: SQUserPointer sqstd_createblob(HSQUIRRELVM v, SQInteger size)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger size:  the size of the blob payload that has to be created
+    :returns: a pointer to the newly created blob payload
+
+    creates a blob with the given payload size and pushes it in the stack.

doc/source/stdlib/stdiolib.rst

@@ -0,0 +1,264 @@
+.. _stdlib_stdiolib:
+
+========================
+The Input/Output library
+========================
+
+the i/o library implements basic input/output routines.
+
+--------------
+Squirrel API
+--------------
+
+++++++++++++++
+Global Symbols
+++++++++++++++
+
+
+.. js:function:: dofile(path, [raiseerror])
+
+    compiles a squirrel script or loads a precompiled one and executes it.
+    returns the value returned by the script or null if no value is returned.
+    if the optional parameter 'raiseerror' is true, the compiler error handler is invoked
+    in case of a syntax error. If raiseerror is omitted or set to false, the compiler
+    error handler is not ivoked.
+    When squirrel is compiled in unicode mode the function can handle different character ecodings,
+    UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
+    If the source stream is not prefixed UTF8 ecoding is used as default.
+
+.. js:function:: loadfile(path, [raiseerror])
+
+    compiles a squirrel script or loads a precompiled one an returns it as as function.
+    if the optional parameter 'raiseerror' is true, the compiler error handler is invoked
+    in case of a syntax error. If raiseerror is omitted or set to false, the compiler
+    error handler is not ivoked.
+    When squirrel is compiled in unicode mode the function can handle different character ecodings,
+    UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
+    If the source stream is not prefixed UTF8 ecoding is used as default.
+
+.. js:function:: writeclosuretofile(destpath, closure)
+
+    serializes a closure to a bytecode file (destpath). The serialized file can be loaded
+    using loadfile() and dofile().
+
+
+.. js:data:: stderr
+
+    File object bound on the os *standard error* stream
+
+.. js:data:: stdin
+
+    File object bound on the os *standard input* stream
+
+.. js:data:: stdout
+
+    File object bound on the os *standard output* stream
+
+
+++++++++++++++
+The file class
+++++++++++++++
+
+    The file object implements a stream on a operating system file.
+
+.. js:class:: file(path, patten)
+
+    It's contructor imitates the behaviour of the C runtime function fopen for eg. ::
+
+        local myfile = file("test.xxx","wb+");
+
+    creates a file with read/write access in the current directory.
+
+.. js:function:: file.close()
+
+    closes the file.
+
+.. js:function:: file.eos()
+
+    returns a non null value if the read/write pointer is at the end of the stream.
+
+.. js:function:: file.flush()
+
+    flushes the stream.return a value != null if succeded, otherwise returns null
+
+.. js:function:: file.len()
+
+    returns the lenght of the stream
+
+.. js:function:: file.readblob(size)
+
+    :param int size: number of bytes to read
+
+    read n bytes from the stream and retuns them as blob
+
+.. js:function:: file.readn(type)
+
+    :param int type: type of the number to read
+
+    reads a number from the stream according to the type pameter.
+
+    `type` can have the following values:
+
++--------------+--------------------------------------------------------------------------------+----------------------+
+| parameter    | return description                                                             |  return type         |
++==============+================================================================================+======================+
+| 'l'          | processor dependent, 32bits on 32bits processors, 64bits on 64bits prcessors   |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'i'          | 32bits number                                                                  |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 's'          | 16bits signed integer                                                          |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'w'          | 16bits unsigned integer                                                        |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'c'          | 8bits signed integer                                                           |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'b'          | 8bits unsigned integer                                                         |  integer             |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'f'          | 32bits float                                                                   |  float               |
++--------------+--------------------------------------------------------------------------------+----------------------+
+| 'd'          | 64bits float                                                                   |  float               |
++--------------+--------------------------------------------------------------------------------+----------------------+
+
+.. js:function:: file.resize(size)
+
+    :param int size: the new size of the blobl in bytes
+
+    resizes the blob to the specified `size`
+
+.. js:function:: file.seek(offset [,origin])
+
+    :param int offset: indicates the number of bytes from `origin`.
+    :param int origin: origin of the seek
+
+                        +--------------+-------------------------------------------+
+                        |  'b'         |  beginning of the stream                  |
+                        +--------------+-------------------------------------------+
+                        |  'c'         |  current location                         |
+                        +--------------+-------------------------------------------+
+                        |  'e'         |  end of the stream                        |
+                        +--------------+-------------------------------------------+
+
+    Moves the read/write pointer to a specified location.
+
+.. note:: If origin is omitted the parameter is defaulted as 'b'(beginning of the stream).
+
+.. js:function:: file.tell()
+
+    returns the read/write pointer absolute position
+
+.. js:function:: file.writeblob(src)
+
+    :param blob src: the source blob containing the data to be written
+
+    writes a blob in the stream
+
+.. js:function:: file.writen(n, type)
+
+    :param number n: the value to be written
+    :param int type: type of the number to write
+
+    writes a number in the stream formatted according to the `type` pameter
+
+    `type` can have the following values:
+
++--------------+--------------------------------------------------------------------------------+
+| parameter    | return description                                                             |
++==============+================================================================================+
+| 'i'          | 32bits number                                                                  |
++--------------+--------------------------------------------------------------------------------+
+| 's'          | 16bits signed integer                                                          |
++--------------+--------------------------------------------------------------------------------+
+| 'w'          | 16bits unsigned integer                                                        |
++--------------+--------------------------------------------------------------------------------+
+| 'c'          | 8bits signed integer                                                           |
++--------------+--------------------------------------------------------------------------------+
+| 'b'          | 8bits unsigned integer                                                         |
++--------------+--------------------------------------------------------------------------------+
+| 'f'          | 32bits float                                                                   |
++--------------+--------------------------------------------------------------------------------+
+| 'd'          | 64bits float                                                                   |
++--------------+--------------------------------------------------------------------------------+
+
+
+--------------
+C API
+--------------
+
+.. _sqstd_register_iolib:
+
+.. c:function:: SQRESULT sqstd_register_iolib(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an SQRESULT
+    :remarks: The function aspects a table on top of the stack where to register the global library functions.
+
+    initialize and register the io library in the given VM.
+
+++++++++++++++
+File Object
+++++++++++++++
+
+.. c:function:: SQRESULT sqstd_createfile(HSQUIRRELVM v, SQFILE file, SQBool owns)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQFILE file: the stream that will be rapresented by the file object
+    :param SQBool owns: if different true the stream will be automatically closed when the newly create file object is destroyed.
+    :returns: an SQRESULT
+
+    creates a file object bound to the SQFILE passed as parameter
+    and pushes it in the stack
+
+.. c:function:: SQRESULT sqstd_getfile(HSQUIRRELVM v, SQInteger idx, SQFILE* file)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger idx: and index in the stack
+    :param SQFILE* file: A pointer to a SQFILE handle that will store the result
+    :returns: an SQRESULT
+
+    retrieve the pointer of a stream handle from an arbitrary
+    position in the stack.
+
+++++++++++++++++++++++++++++++++
+Script loading and serialization
+++++++++++++++++++++++++++++++++
+
+.. c:function:: SQRESULT sqstd_loadfile(HSQUIRRELVM v, const SQChar* filename, SQBool printerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQChar* filename: path of the script that has to be loaded
+    :param SQBool printerror: if true the compiler error handler will be called if a error occurs
+    :returns: an SQRESULT
+
+    Compiles a squirrel script or loads a precompiled one an pushes it as closure in the stack.
+    When squirrel is compiled in unicode mode the function can handle different character ecodings,
+    UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
+    If the source stream is not prefixed UTF8 ecoding is used as default.
+
+.. c:function:: SQRESULT sqstd_dofile(HSQUIRRELVM v, const SQChar* filename, SQBool retval, SQBool printerror)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQChar* filename: path of the script that has to be loaded
+    :param SQBool retval: if true the function will push the return value of the executed script in the stack.
+    :param SQBool printerror: if true the compiler error handler will be called if a error occurs
+    :returns: an SQRESULT
+    :remarks: the function aspects a table on top of the stack that will be used as 'this' for the execution of the script. The 'this' parameter is left untouched in the stack.
+
+    Compiles a squirrel script or loads a precompiled one and executes it.
+    Optionally pushes the return value of the executed script in the stack.
+    When squirrel is compiled in unicode mode the function can handle different character ecodings,
+    UTF8 with and without prefix and UCS-2 prefixed(both big endian an little endian).
+    If the source stream is not prefixed UTF8 ecoding is used as default. ::
+
+        sq_pushroottable(v); //push the root table(were the globals of the script will are stored)
+        sqstd_dofile(v, _SC("test.nut"), SQFalse, SQTrue);// also prints syntax errors if any
+
+.. c:function:: SQRESULT sqstd_writeclosuretofile(HSQUIRRELVM v, const SQChar* filename)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQChar* filename: destination path of serialized closure
+    :returns: an SQRESULT
+
+    serializes the closure at the top position in the stack as bytecode in
+    the file specified by the paremeter filename. If a file with the
+    same name already exists, it will be overwritten.
+

doc/source/stdlib/stdmathlib.rst

@@ -0,0 +1,111 @@
+.. _stdlib_stdmathlib:
+
+================
+The Math library
+================
+
+the math lib provides basic mathematic routines. The library mimics the
+C runtime library implementation.
+
+------------
+Squirrel API
+------------
+
++++++++++++++++
+Global Symbols
++++++++++++++++
+
+.. js:function:: abs(x)
+
+    returns the absolute value of `x` as an integer
+
+.. js:function:: acos(x)
+
+    returns the arccosine of `x`
+
+.. js:function:: asin(x)
+
+    returns the arcsine of `x`
+
+.. js:function:: atan(x)
+
+    returns the arctangent of `x`
+
+.. js:function:: atan2(x,y)
+
+    returns the arctangent of  `x/y`
+
+.. js:function:: ceil(x)
+
+    returns a float value representing the smallest integer that is greater than or equal to `x`
+
+.. js:function:: cos(x)
+
+    returns the cosine of `x`
+
+.. js:function:: exp(x)
+
+    returns the exponential value of the float parameter `x`
+
+.. js:function:: fabs(x)
+
+    returns the absolute value of `x` as a float
+
+.. js:function:: floor(x)
+
+    returns a float value representing the largest integer that is less than or equal to `x`
+
+.. js:function:: log(x)
+
+    returns the natural logarithm of `x`
+
+.. js:function:: log10(x)
+
+    returns the logarithm base-10 of `x`
+
+.. js:function:: pow(x,y)
+
+    returns `x` raised to the power of `y`
+
+.. js:function:: rand()
+
+    returns a pseudorandom integer in the range 0 to `RAND_MAX`
+
+.. js:function:: sin(x)
+
+    rreturns the sine of `x`
+
+.. js:function:: sqrt(x)
+
+    returns the square root of `x`
+
+.. js:function:: srand(seed)
+
+    sets the starting point for generating a series of pseudorandom integers
+
+.. js:function:: tan(x)
+
+    returns the tangent of `x`
+
+.. js:data:: RAND_MAX
+
+    the maximum value that can be returned by the `rand()` function
+
+.. js:data:: PI
+
+    The numeric constant pi (3.141592) is the ratio of the circumference of a circle to its diameter
+
+------------
+C API
+------------
+
+.. _sqstd_register_mathlib:
+
+.. c:function:: SQRESULT sqstd_register_mathlib(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an SQRESULT
+    :remarks: The function aspects a table on top of the stack where to register the global library functions.
+
+    initializes and register the math library in the given VM.
+

doc/source/stdlib/stdstringlib.rst

@@ -0,0 +1,302 @@
+.. _stdlib_stdstringlib:
+
+==================
+The String library
+==================
+
+the string lib implements string formatting and regular expression matching routines.
+
+--------------
+Squirrel API
+--------------
+
+++++++++++++++
+Global Symbols
+++++++++++++++
+
+.. js:function:: ecape(str)
+
+    Returns a string with backslashes before characters that need to be escaped(`\",\a,\b,\t,\n,\v,\f,\r,\\,\",\',\0,\xnn`).
+
+.. js:function:: format(formatstr, ...)
+
+    Returns a string formatted according `formatstr` and the optional parameters following it.
+    The format string follows the same rules as the `printf` family of
+    standard C functions( the "*" is not supported). ::
+
+        eg.
+        sq> print(format("%s %d 0x%02X\n","this is a test :",123,10));
+        this is a test : 123 0x0A
+
+.. js:function:: lstrip(str)
+
+    Strips white-space-only characters that might appear at the beginning of the given string
+    and returns the new stripped string.
+
+.. js:function:: rstrip(str)
+
+    Strips white-space-only characters that might appear at the end of the given string
+    and returns the new stripped string.
+
+.. js:function:: split(str, separtators)
+
+    returns an array of strings split at each point where a separator character occurs in `str`.
+    The separator is not returned as part of any array element.
+    The parameter `separators` is a string that specifies the characters as to be used for the splitting.
+
+    ::
+
+        eg.
+        local a = split("1.2-3;4/5",".-/;");
+        // the result will be  [1,2,3,4,5]
+
+.. js:function:: strip(str)
+
+    Strips white-space-only characters that might appear at the beginning or end of the given string and returns the new stripped string.
+
+++++++++++++++++++
+The regexp class
+++++++++++++++++++
+
+.. js:class:: regexp(pattern)
+
+    The regexp object rapresent a precompiled regular experssion pattern. The object is created
+    trough `regexp(patern)`.
+
+
++---------------------+--------------------------------------+
+|      `\\`           |  Quote the next metacharacter        |
++---------------------+--------------------------------------+
+|      `^`            |  Match the beginning of the string   |
++---------------------+--------------------------------------+
+|      `.`            |  Match any character                 |
++---------------------+--------------------------------------+
+|      `$`            |  Match the end of the string         |
++---------------------+--------------------------------------+
+|      `|`            |  Alternation                         |
++---------------------+--------------------------------------+
+|      `(subexp)`     |  Grouping (creates a capture)        |
++---------------------+--------------------------------------+
+|      `(?:subexp)`   |  No Capture Grouping (no capture)    |
++---------------------+--------------------------------------+
+|      `[]`           |  Character class                     |
++---------------------+--------------------------------------+
+
+**GREEDY CLOSURES**
+
++---------------------+---------------------------------------------+
+|      `*`            |  Match 0 or more times                      |
++---------------------+---------------------------------------------+
+|      `+`            |  Match 1 or more times                      |
++---------------------+---------------------------------------------+
+|      `?`            |  Match 1 or 0 times                         |
++---------------------+---------------------------------------------+
+|      `{n}`          |  Match exactly n times                      |
++---------------------+---------------------------------------------+
+|      `{n,}`         |  Match at least n times                     |
++---------------------+---------------------------------------------+
+|      `{n,m}`        |  Match at least n but not more than m times |
++---------------------+---------------------------------------------+
+
+**ESCAPE CHARACTERS**
+
++---------------------+--------------------------------------+
+|      `\\t`          |  tab (HT, TAB)                       |
++---------------------+--------------------------------------+
+|      `\\n`          |  newline (LF, NL)                    |
++---------------------+--------------------------------------+
+|      `\\r`          | return (CR)                          |
++---------------------+--------------------------------------+
+|      `\\f`          |  form feed (FF)                      |
++---------------------+--------------------------------------+
+
+**PREDEFINED CLASSES**
+
++---------------------+--------------------------------------+
+|      `\\l`          |  lowercase next char                 |
++---------------------+--------------------------------------+
+|      `\\u`          |  uppercase next char                 |
++---------------------+--------------------------------------+
+|      `\\a`          |  letters                             |
++---------------------+--------------------------------------+
+|      `\\A`          |  non letters                         |
++---------------------+--------------------------------------+
+|      `\\w`          |  alphanumeric `[_0-9a-zA-Z]`         |
++---------------------+--------------------------------------+
+|      `\\W`          |  non alphanumeric `[^_0-9a-zA-Z]`    |
++---------------------+--------------------------------------+
+|      `\\s`          |  space                               |
++---------------------+--------------------------------------+
+|      `\\S`          |  non space                           |
++---------------------+--------------------------------------+
+|      `\\d`          |  digits                              |
++---------------------+--------------------------------------+
+|      `\\D`          |  non nondigits                       |
++---------------------+--------------------------------------+
+|      `\\x`          |  exadecimal digits                   |
++---------------------+--------------------------------------+
+|      `\\X`          |  non exadecimal digits               |
++---------------------+--------------------------------------+
+|      `\\c`          |  control characters                  |
++---------------------+--------------------------------------+
+|      `\\C`          |  non control characters              |
++---------------------+--------------------------------------+
+|      `\\p`          |  punctation                          |
++---------------------+--------------------------------------+
+|      `\\P`          |  non punctation                      |
++---------------------+--------------------------------------+
+|      `\\b`          |  word boundary                       |
++---------------------+--------------------------------------+
+|      `\\B`          |  non word boundary                   |
++---------------------+--------------------------------------+
+
+
+.. js:function:: regexp.capture(str [, start])
+
+    returns an array of tables containing two indexs("begin" and "end")of
+    the first match of the regular expression in the string `str`.
+    An array entry is created for each captured sub expressions. If no match occurs returns null.
+    The search starts from the index `start`
+    of the string, if `start` is omitted the search starts from the beginning of the string.
+
+    the first element of the returned array(index 0) always contains the complete match.
+
+    ::
+
+        local ex = regexp(@"(\d+) ([a-zA-Z]+)(\p)");
+        local string = "stuff 123 Test;";
+        local res = ex.capture(string);
+        foreach(i,val in res)
+        {
+            print(format("match number[%02d] %s\n",
+                    i,string.slice(val.begin,val.end))); //prints "Test"
+        }
+
+        ...
+        will print
+        match number[00] 123 Test;
+        match number[01] 123
+        match number[02] Test
+        match number[03] ;
+
+.. js:function:: regexp.match(str)
+
+    returns a true if the regular expression matches the string
+    `str`, otherwise returns false.
+
+.. js:function:: regexp.search(str [, start])
+
+    returns a table containing two indexs("begin" and "end") of the first match of the regular expression in
+    the string `str`, otherwise if no match occurs returns null. The search starts from the index `start`
+    of the string, if `start` is omitted the search starts from the beginning of the string.
+
+    ::
+
+        local ex = regexp("[a-zA-Z]+");
+        local string = "123 Test;";
+        local res = ex.search(string);
+        print(string.slice(res.begin,res.end)); //prints "Test"
+
+-------------
+C API
+-------------
+
+.. _sqstd_register_stringlib:
+
+.. c:function:: SQRESULT sqstd_register_stringlib(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an SQRESULT
+    :remarks: The function aspects a table on top of the stack where to register the global library functions.
+
+    initialize and register the string library in the given VM.
+
++++++++++++++
+Formatting
++++++++++++++
+
+.. c:function:: SQRESULT sqstd_format(HSQUIRRELVM v, SQInteger nformatstringidx, SQInteger* outlen, SQChar** output)
+
+    :param HSQUIRRELVM v: the target VM
+    :param SQInteger nformatstringidx: index in the stack of the format string
+    :param SQInteger* outlen: a pointer to an integer that will be filled with the length of the newly created string
+    :param SQChar** output: a pointer to a string pointer that will receive the newly created string
+    :returns: an SQRESULT
+    :remarks: the newly created string is allocated in the scratchpad memory.
+
+
+    creates a new string formatted according to the object at position `nformatstringidx` and the optional parameters following it.
+    The format string follows the same rules as the `printf` family of
+    standard C functions( the "*" is not supported).
+
+++++++++++++++++++
+Regular Expessions
+++++++++++++++++++
+
+.. c:function:: SQRex* sqstd_rex_compile(const SQChar *pattern, const SQChar ** error)
+
+    :param SQChar* pattern: a pointer to a zero terminated string containing the pattern that has to be compiled.
+    :param SQChar** error: a pointer to a string pointer that will be set with an error string in case of failure.
+    :returns: a pointer to the compiled pattern
+
+    compiles an expression and returns a pointer to the compiled version.
+    in case of failure returns NULL.The returned object has to be deleted
+    through the function sqstd_rex_free().
+
+.. c:function:: void sqstd_rex_free(SQRex * exp)
+
+    :param SQRex* exp: the expression structure that has to be deleted.
+
+    deletes a expression structure created with sqstd_rex_compile()
+
+.. c:function:: SQBool sqstd_rex_match(SQRex * exp,const SQChar * text)
+
+    :param SQRex* exp: a compiled expression
+    :param SQChar* text: the string that has to be tested
+    :returns: SQTrue if successful otherwise SQFalse
+
+    returns SQTrue if the string specified in the parameter text is an
+    exact match of the expression, otherwise returns SQFalse.
+
+.. c:function:: SQBool sqstd_rex_search(SQRex * exp, const SQChar * text, const SQChar ** out_begin, const SQChar ** out_end)
+
+    :param SQRex* exp: a compiled expression
+    :param SQChar* text: the string that has to be tested
+    :param SQChar** out_begin: a pointer to a string pointer that will be set with the beginning of the match
+    :param SQChar** out_end: a pointer to a string pointer that will be set with the end of the match
+    :returns: SQTrue if successful otherwise SQFalse
+
+    searches the first match of the expressin in the string specified in the parameter text.
+    if the match is found returns SQTrue and the sets out_begin to the beginning of the
+    match and out_end at the end of the match; otherwise returns SQFalse.
+
+.. c:function:: SQBool sqstd_rex_searchrange(SQRex * exp, const SQChar * text_begin, const SQChar * text_end, const SQChar ** out_begin, const SQChar ** out_end)
+
+    :param SQRex* exp: a compiled expression
+    :param SQChar* text_begin:  a pointer to the beginnning of the string that has to be tested
+    :param SQChar* text_end: a pointer to the end of the string that has to be tested
+    :param SQChar** out_begin: a pointer to a string pointer that will be set with the beginning of the match
+    :param SQChar** out_end: a pointer to a string pointer that will be set with the end of the match
+    :returns: SQTrue if successful otherwise SQFalse
+
+    searches the first match of the expressin in the string delimited
+    by the parameter text_begin and text_end.
+    if the match is found returns SQTrue and the sets out_begin to the beginning of the
+    match and out_end at the end of the match; otherwise returns SQFalse.
+
+.. c:function:: SQInteger sqstd_rex_getsubexpcount(SQRex * exp)
+
+    :param SQRex* exp: a compiled expression
+    :returns: the number of sub expressions matched by the expression
+
+    returns the number of sub expressions matched by the expression
+
+.. c:function:: SQBool sqstd_rex_getsubexp(SQRex * exp, SQInteger n, SQRexMatch *subexp)
+
+    :param SQRex* exp: a compiled expression
+    :param SQInteger n: the index of the submatch(0 is the complete match)
+    :param SQRexMatch* a: pointer to structure that will store the result
+    :returns: the function returns SQTrue if n is valid index otherwise SQFalse.
+
+    retrieve the begin and and pointer to the length of the sub expression indexed
+    by n. The result is passed trhough the struct SQRexMatch.

doc/source/stdlib/stdsystemlib.rst

@@ -0,0 +1,82 @@
+.. _stdlib_stdsystemlib:
+
+==================
+The System library
+==================
+
+The system library exposes operating system facilities like environment variables,
+date time manipulation etc..
+
+--------------
+Squirrel API
+--------------
+
+++++++++++++++
+Global Symbols
+++++++++++++++
+
+.. js:function:: clock()
+
+    returns a float representing the number of seconds elapsed since the start of the process
+
+.. js:function:: date([time [, format]])
+
+    returns a table containing a date/time splitted in the slots:
+
++-------------+----------------------------------------+
+| sec         | Seconds after minute (0 - 59).         |
++-------------+----------------------------------------+
+| min         | Minutes after hour (0 - 59).           |
++-------------+----------------------------------------+
+| hour        | Hours since midnight (0 - 23).         |
++-------------+----------------------------------------+
+| day         | Day of month (1 - 31).                 |
++-------------+----------------------------------------+
+| month       | Month (0 - 11; January = 0).           |
++-------------+----------------------------------------+
+| year        | Year (current year).                   |
++-------------+----------------------------------------+
+| wday        | Day of week (0 - 6; Sunday = 0).       |
++-------------+----------------------------------------+
+| yday        | Day of year (0 - 365; January 1 = 0).  |
++-------------+----------------------------------------+
+
+if `time` is omitted the current time is used.
+
+if `format` can be 'l' local time or 'u' UTC time, if omitted is defaulted as 'l'(local time).
+
+.. js:function:: getenv(varaname)
+
+    Returns a string containing the value of the environment variable `varname`
+
+.. js:function:: remove(path)
+
+    deletes the file specified by `path`
+
+.. js:function:: rename(oldname, newname)
+
+    renames the file or directory specified by `oldname` to the name given by `newname`
+
+.. js:function:: system(cmd)
+
+    xecutes the string `cmd` through the os command interpreter.
+
+.. js:function:: time()
+
+    returns the number of seconds elapsed since midnight 00:00:00, January 1, 1970.
+
+    the result of this function can be formatted through the function `date()`
+
+--------------
+C API
+--------------
+
+.. _sqstd_register_systemlib:
+
+.. c:function:: SQRESULT sqstd_register_systemlib(HSQUIRRELVM v)
+
+    :param HSQUIRRELVM v: the target VM
+    :returns: an SQRESULT
+    :remarks: The function aspects a table on top of the stack where to register the global library functions.
+
+    initialize and register the system library in the given VM.