README

Leonardus is licensed under the GNU General Public License v3.0.
See the LICENSE file for more details.

Project Goal

Leonardus is an open source project. It is a minimalist, stack-based
programming system designed as a flexible framework for implementing and
exploring algorithms. The syntax and semantics of its scripting language,
LeoScript, are inspired by PostScript and Forth. It is extended with
a prototype-based, object-oriented paradigm, has seamless integration into
JupyterLab and Docker, and provides a concise and expressive environment
for learning and experimentation.

The project name is a nod to Leonardus Pisanus, who was named and
became known as Fibonacci.

Quick

There are three main ways to get started with Leonardus:

• Consult the project's help pages
• Use the published Docker images
• Compile the programs yourself

For more details, see USING.

Quick Help

Consult the project's GitLab Pages for documentation.
There you can find the latest user and developer information including content
generated from the source code files.

Type lc -h and lb -h to get command line help, either within the Docker
image or after building the project. You can also use the UNIX man page system.

Quick Docker "leonardus"

Pull the image hagenbund2/leonardus and run it with:

docker run -it --rm hagenbund2/leonardus:latest

The CLI applications lc and lb will be available in the opening shell.
lb runs LeoScripts. lc serves as command line calculator.
Follow the hints on the welcome screen.

Extra

As Docker feature you could even execute lc in one line with e.g.:

docker run --rm hagenbund2/leonardus lc 41 1 add

Quick Docker "leojupyter"

Pull the image hagenbund2/leojupyter
and run the X Application JupyterLab with the command line given in the
Docker hub "Overview".

Quick Build

Install, if not already on your system:

• the GNU C++ compiler,
• git,
• make,
• flex,
• the quadmath library,
• the Boost library and
• the GMP library

To build the CLI artifacts and run all end2end tests:

make e2e

Optionally install Doxygen, LaTeX, Drawio and cloc to generate the HTML
documentation and the man pages in ./public/ with:

make public-pages

To run an example from your own build:

make leon parser lb lc; ./lb Examples/Factorial.leo

To run all examples:

make runxtest

For your convinience make install creates an installation in your
$HOME/.local

You can use Leonardus as a calculator. For example:

lc 25346 95095 gcd  
lc 1 2 1 33 { mul } for

Technologies

This project leverages the following core technologies:

• GNU C++ 20: utilizing modern C++
• git: for version control
• GitLab with features: issues, pipelines, pages, releases, etc.
• make: automating the build process for the command-line and for CI/CD
• flex: generating the lexical analyzer
• Bash: scripting for automating tasks
• Doxygen: generating documentation for both the project's code and LeoScript
• Markdown: a lightweight format for documentation
• quadmath: supporting 128-bit integers and 128-bit floating point numbers
• LaTeX: enhancing the visual quality of Doxygen-generated documentation
• Boost C++ library 1.83: for various extensions, e.g. asserts, unit testing
• GNU Multiple Precision Arithmetic Library: as implementation of rational
  numbers

Optional tools:

• cppcheck and clang-tidy: static analysis for code quality and
  bug prevention
• KDevelop and/or Visual Studio Code: IDEs for efficient development
• cloc: to get simple code metrics
• lcov and gcov: do get and visualize test coverage data
• Docker: we are building our own images to speed up GitLab CI/CD and we deploy a Leonardus image.
• Docker Hub: to host our Docker images
• drawio aka diagrams.net: for diagrams
• man pages: traditional console help texts
• Python: for the glue code to Jupyter
• Jupyter: LeoScript integrates as Jupyter kernel for interactive sessions and documentation

Recommendations:

• Ghostscript: as reference implemenation of the PostScript language

Tools from the GitLab pipeline:

• shellcheck: a Unix shell lint integrated in the GitLab pipeline
• markdownlint-cli2: a markdown lint integrated in the GitLab pipeline
• GitLab SAST: a GitLab-maintained security scanner for the pipeline

Further Reading

Examples

The Examples directory contains sample code. The build process generates
an overview of its contents in EXAMPLES.md.

Programming Language

For a detailed description of LeoScript, the Leonardus scripting language,
see LANGUAGE.

Architecture and Coding

The Leonardus documentation on architecture and coding is divided into two parts:

• ARCHITECTURE: Project-specific details.
• CODING: Notes on general programming aspects, applicable to
  other C++ projects.

Glossary

Build Type

There are three build types for different software processes
and environments: DEVELOP PRODUCTION PROFILE

Core Code

If a LeoScript operator is coded directly in C++, it is referred to as core code.

Jupyter

Project Jupyter is a project to develop open-source software, open standards,
and services for interactive computing across multiple programming languages.
Leonardus integrates with the JupyterLab app.

leon

The second interpreter pass reads and interprets its leon-format input.

Leon-Format

The exchange format between the first interpreter pass called "parser"
und the second interpreter pass called "leon". Stored leon-format files
use the file name extension .leon.

LeoScript

The stack-based scripting language and its file format of project Leonardus.
Each line of code can contain commands, which are short, case-sensitive
keywords, and operands, which are pushed onto a data stack and
manipulated by operators. The language supports various data types,
including integers, real numbers, booleans, strings, arrays, stacks and
dictionaries, and follows a reverse Polish notation (RPN) syntax, where
operators follow their operands.

Registered and Unregistered Core Code Operators

Most of the core code operators are referenced as values in the dictionaries
at start up time. They are called registered.
There are other core code operators for internal use. These are called
unregistered.

Operator

A subspecies of semantic objects, that operates on other semantic
objects, the stacks or the interpreter itself. Some of the operators are
LeoScript procedures and the others are core code.

Object Type Code -or- OTCode

A one character code for each SO class. The virtual ot() member function
of all SO classes return this code and allows explicit type-based decisions
beside the C++ language poylmorphisms.
See: object types

On Demand Optimizer -or- ODO

Optimzes LeoScript procedures as part of the bind operator.

parser

The first interpreter pass checks the syntax and converts the program
into leon-format.

Procedure Level

The procedure level counts the nesting level of curly braces in the
program code.

Property

For the classes Interpreter and Context there are attributes, together with
setters and getters, which change the behaviour. These properties can be set
with LeoScript operators.

Prototype-based Object -or- PTBO

To distinguish them from semantic objects (SOs), the objects at the LeoScript
level are referred to as prototype-based objects (PTBOs). They provide the
features of inheritance and encapsulation.

Red Book

The PostScript Red Book, officially titled "PostScript Language Reference,"
is the authoritative manual for the PostScript programming language,
detailing its syntax, semantics, and graphics operators.

We use it as a reference for the LeoScript operators, for which we have
explicitly established full compatibility in behavior.

Semantic Object -or- SO

In LeoScript, the following elements form the semantic building blocks
of the language:

• sequences of characters separated by whitespace,
• literal values (numbers and strings), and
• boolean values.

In the interpreter’s C++ source code, these elements correspond to
C++ objects of the SO* classes. Additionally, the interpreter represents
composite objects for dictionaries, arrays, and stacks. These are also
considered Semantic Objects.

In the programming language Forth, such elements are referred to as "words".

See: object types

Task Tag

We use IDEA:, TODO: and FIXME: as Task Tags

Verbose Mode

All tools support a -v option to generate more run time information.

Vocabulary

A subdirectory as container of LeoScript files which creates one or more
functional related dictionaries if executed.

Files and Directories

File Types

Directories of the Git Repository

./AuxDoc
To store auxiliary documentation.

./Coverage
Test coverage data.

./Docker
Dockerfiles to build the images used in GitLab CI/CD.

./drawio
diagrams.net aka drawio diagrams.

./Examples
Example programs.

./Jupyter
Notebooks and support files for the Jupyter integration.

./.git
That's the git Repository.

./Index
Source for the documentation main page.

./.kdev4
Is a living propsal for a KDevelop configuration.

./man
The Doxygen-generated man pages.

./public
Location for GitLab Pages web server files.
The Doxygen-generated HTML documentation can be found in ./public/doxygen/
The test coverage results in ./public/lcov/
The PDF versions of drawio diagrams in ./public/pdf/

./TS/[0-9][0-9]*
Each 'TS/*' directory contains a test suite = a collection of test cases.

./tmp
Exists for temporary files e.g. for testing purposes.

./Tools
Contains TOOLS for the development, e.g. git hooks.

./vocabularies
Is only a container for its subdirectories.
These subdirecories are called vocabularies and the names of the
subdirectories are used to identify the vocabularies.

./.vscode
Is a living propsal for a Visual Studio Code configuration.

Set Up Created by make install

This make target creates symbolic links to the artifacts and project files
from the Git directory used to build Leonardus. It is designed for
convenient access to the project's tools and resources.

$HOME/.local/bin
Contains the links to the commands: parser leon lb lc

$HOME/.local/lib/leonardus/
Links to files boot.leo and dry.inc and to the directory vocabularies

$HOME/.local/man/
Contains a link to the generated man pages.

$HOME/.local/share/jupyter/kernels/leoscript
A true copy of the Jupyter kernel configuration.

Directories of the Docker Image "leonardus"

It is a minimal Ubuntu installation with:

/usr/local/bin
Contain the user programs: parser leon lb lc

/usr/local/lib/leonardus/
System files: boot.leo dry.inc

/usr/local/lib/leonardus/vocabularies/
The location for the vocabularies.

/usr/local/lib/leonardus/Examples/
Example *.leo LeoScripts

/usr/local/share/doc/leonardus/public/
Help and documentation HTML pages.

/usr/local/man/man7/
Generated man pages.

/usr/sbin/
Contains dockerstart.sh.

Directories of the Docker Image "leojupyter"

Contains the same files as "leonardus" and additionally:

/usr/local/share/jupyter/kernels/leoscript/
Jupyter kernel configuration.

/opt/JupyterLab/
The JupyterLab application.

/usr/share/icons/hicolor/512x512/apps/jupyterlab-desktop.png
/usr/share/doc/jupyterlab-desktop/changelog.gz
/usr/share/applications/jupyterlab-desktop.desktop
Support files for JupyterLab.

References

• Algorithms from Wikipedia
• Cppcheck
• Delegation in OOP from Wikipedia
• Doxygen GitLab Pages Example
• Flex
• flex by LeMoDa
• Flex from Wikipedia
• Forth from Wikipedia
• Gforth
• GNU Ghostscript on Savannah
• GNU Ghostscript readthedocs
• govr FAQ
• Integer from Wikipedia
• Mathematical Illustrations : A manual of geometry and PostScript, Bill Casselmann
• GNU Multiple Precision Arithmetic Library
• GNU Multiple Precision Arithmetic Library from Wikipedia
• NeWS from WIkipedia
• OOP by Event Helix
• PostScript REDBOOK, Adobe, third edition, 1999
• PostScript by Chubek
• PostScript by Weingartner
• PostScript FAQ Book from wikibooks
• PostScript by Neumerkel
• Prototype-based OOP from Wikipedia
• libquadmath
• Quadratic Field from Wikipedia
• Quadruple-precision from Wikipedia
• Stack-oriented Programming from Wikipedia