[nuttx] 04/13: Documentaion: migrate interpreters/readme

[ac...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit 0979fd0ab727f838a1d30691c7c697121fbc957a
Author: raiden00pl <ra...@railab.me>
AuthorDate: Tue Oct 24 12:22:36 2023 +0200

    Documentaion: migrate interpreters/readme
---
 .../applications/interpreters/bas/index.rst        | 64 ++++++++++++++++++++++
 .../applications/interpreters/ficl/index.rst       | 44 +++++++++++++++
 Documentation/applications/interpreters/index.rst  | 14 +++--
 .../applications/interpreters/lua/index.rst        | 17 ++++++
 .../applications/interpreters/minibasic/index.rst  | 11 ++++
 5 files changed, 146 insertions(+), 4 deletions(-)

diff --git a/Documentation/applications/interpreters/bas/index.rst b/Documentation/applications/interpreters/bas/index.rst
new file mode 100644
index 0000000000..4ae28961aa
--- /dev/null
+++ b/Documentation/applications/interpreters/bas/index.rst
@@ -0,0 +1,64 @@
+=============================
+``bas`` Bas BASIC Interpreter
+=============================
+
+Introduction
+------------
+
+Bas is an interpreter for the classic dialect of the programming language BASIC.
+It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some
+other UNIX BASIC interpreters, that implement a different syntax, breaking
+compatibility to existing programs. Bas offers many ANSI BASIC statements for
+structured programming, such as procedures, local variables and various loop
+types. Further there are matrix operations, automatic LIST indentation and many
+statements and functions found in specific classic dialects. Line numbers are
+not required.
+
+The interpreter tokenises the source and resolves references to variables and
+jump targets before running the program. This compilation pass increases
+efficiency and catches syntax errors, type errors and references to variables
+that are never initialised. Bas is written in ANSI C for UNIX systems.
+
+License
+-------
+
+BAS 2.4 is released as part of NuttX under the standard 3-clause BSD license use
+by all components of NuttX. This is not incompatible with the original BAS 2.4
+licensing
+
+Copyright (c) 1999-2014 Michael Haardt
+
+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.
+
+Bas 2.4 Release Notes
+---------------------
+
+Changes compared to version ``2.3``
+
+- Matrix inversion on integer arrays with option base 1 fixed.
+- ``PRINT USING`` behaviour for ``!`` fixed.
+- ``PRINT``, separator should advance to the next zone, even if the current
+  position is at the start of a zone.
+- Added ``ip()``, ``frac()``, ``fp()``, ``log10()``, ``log2()``, ``min()`` and ``max()``.
+- Fixed ``NEXT`` checking the variable case sensitive.
+- Use ``terminfo`` capability cr to make use of its padding.
+- ``LET`` segmentation fault fixed.
+- ``PRINT`` now uses print items.
+- ``-r`` for restricted operation.
+- ``MAT INPUT`` does not drop excess arguments, but uses them for the next row.
+- License changed to MIT.
diff --git a/Documentation/applications/interpreters/ficl/index.rst b/Documentation/applications/interpreters/ficl/index.rst
new file mode 100644
index 0000000000..1f9c8c2e43
--- /dev/null
+++ b/Documentation/applications/interpreters/ficl/index.rst
@@ -0,0 +1,44 @@
+===============================
+``ficl`` Ficl Forth interpreter
+===============================
+
+Ficl is a programming language interpreter designed to be embedded into other
+systems as a command, macro, and development prototyping language.
+
+This is DIY port of Ficl (the "Forth Inspired Command Language"). See
+http://ficl.sourceforge.net/. It is a "" port because the Ficl source is not
+in that directory, only an environment and instructions that will let you build
+Ficl under NuttX. The rest is up to you.
+
+Build Instructions
+------------------
+
+Disclaimer: This installation steps have only been exercised using Ficl 4.1.0.
+With new versions you will likely have to make some adjustments to this
+instructtions or to the files within this directory. Think of this information
+as _recommendations_ - not necessarily proven instructions.
+
+1. ``cd`` to ``interpreters/ficl``
+
+2. Download Ficl: http://sourceforge.net/projects/ficl/files/
+
+3. Uznip the Ficl compressed file.
+
+   For example, ``unzip ficl-4.1.0.zip`` will leave the file
+   ``interpreters/ficl/ficl-4.1.0``.
+
+4. Configure to build Ficl in the ``interpreters/ficl`` directory using the
+   ``configure.sh`` script.
+
+   For example, ``./configure.sh ficl-4.1.0`` will leave the Makefile fragment
+   ``Make.srcs`` in the ficl build directory.
+
+5. Create your NuttX configuration. Using the ``make menuconfig``, you should
+   select::
+
+     CONFIG_INTERPRETERS_FICL=y
+
+6. Configure and build NuttX. On successful completion, the Ficl objects will be
+   available in ``apps/libapps.a`` and that NuttX binary will be linked against
+   that file. Of course, Ficl will do nothing unless you have written some
+   application code that uses it!
diff --git a/Documentation/applications/interpreters/index.rst b/Documentation/applications/interpreters/index.rst
index c1debdfd64..ec0a879c09 100644
--- a/Documentation/applications/interpreters/index.rst
+++ b/Documentation/applications/interpreters/index.rst
@@ -2,13 +2,19 @@
 Interpreters
 ============
 
-- bas - Basic Interpreter 
+This `apps/` directory is set aside to hold interpreters that may be
+incorporated into NuttX.
+
+.. toctree::
+   :glob:
+   :maxdepth: 3
+   :titlesonly:
+   
+   */*
+
 - duktape - Duktape JavaScript interpreter
-- ficl - Ficl Forth interpreter
-- lua - Lua interpreter 
 - luajit - LuaJIT interpreter
 - luamodules: cjson, lfs, luasyslog, luv
-- minibasic - Mini Basic Interpreter
 - quickjs - QuickJS JavaScript interpreter
 - toywasm - Toywasm Webassembly Runtime
 - wamr - Webassembly Micro Runtime
diff --git a/Documentation/applications/interpreters/lua/index.rst b/Documentation/applications/interpreters/lua/index.rst
new file mode 100644
index 0000000000..1b088df1e1
--- /dev/null
+++ b/Documentation/applications/interpreters/lua/index.rst
@@ -0,0 +1,17 @@
+=======================
+``lua`` Lua interpreter
+=======================
+
+Fetch and build a Lua interpreter. Versions 5.2 through 5.4 are supported. The
+``lua`` command will be added to NSH. Lua can run a script for a given path,
+execute a string of code, or open a readline compatible REPL on the NSH console.
+The ``<lua.h>`` and ``<lauxlib.h>`` headers are available to start a new embedded
+interpreter or extend Lua with C modules. See the ``luamod_hello`` example for how
+to include a built-in module.
+
+A math library is required to build. Enable the ``LIBM`` config or use a
+toolchain provided math library.
+
+The following configs are recommended for a full featured Lua interpreter:
+- ``LIBC_FLOATINGPOINT``
+- ``SYSTEM_READLINE``
diff --git a/Documentation/applications/interpreters/minibasic/index.rst b/Documentation/applications/interpreters/minibasic/index.rst
new file mode 100644
index 0000000000..52d334313d
--- /dev/null
+++ b/Documentation/applications/interpreters/minibasic/index.rst
@@ -0,0 +1,11 @@
+====================================
+``minibasic`` Mini Basic Interpreter
+====================================
+
+The Mini Basic implementation at ``apps/interpreters`` derives from version ``1.0``
+by Malcolm McLean, Leeds University, and was released under the Creative Commons
+Attibution license. I am not legal expert, but this license appears to be
+compatible with the NuttX BSD license see:
+https://creativecommons.org/licenses/. I, however, cannot take responsibility
+for any actions that you might take based on my understanding. Please use your
+own legal judgement.