Metadata-Version: 2.4
Name: confined
Version: 0.2.0
Summary: Safe Forth inspired templating language
Home-page: http://github.org/jul/confined
Author: Julien Tayon
Author-email: julien@tayon.net
License: License :: OSI Approved :: BSD License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
License-File: LICENSE
Requires-Dist: prompt_toolkit
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

=====================================================
Confined: a safe resource bound immutable interpreter
=====================================================

* source: https://github.com/jul/confined
* ticketing: https://github.com/jul/confined/issues

.. image::
   https://travis-ci.org/jul/confined.png

Use
===

The purpose of this interpreter is to confine the user in a predictable way
so that you don't have to fear to give your user the possibility to execute 
arbitrary code on your servers.

The language is mapping its input/internal stack to immutable data structures
so that remote it is safe to pass it 

Usage
=====

Language
********

Of course, I haven't taken the time to document it, I just did the basic
stack manipulations I recalled from using the HP48SX Forth just to prove
myself it was easy to extend.

Proxied command
---------------

Recently though, many important features have been made in order to use
confined as a message passing language on use on top of a MQTT bus to
experiment to build a Central Command Center *à la* vilain hacker to
pilot independent agent.

For this, there are commands that must be implemented client side.

Such as **LUN**, *unlistenall* which gives the order to the device to
get back to its natural listening buses.

Such as, **NUM: TSSET**, *time slice set* to have devices set their time
slices for clocked device to the aforementionned clock.


** "agent_name": SEL**, *set agent_name in active mode*; launches the
measuring sonde on the agent which should expect to spew data on
*DATA/agent name* on the bus.

** "agent_name": UNSEL**, *unset agent_name in active mode*; stop the
measuring sonde.

**PING**, *ping* causes all devices to spew *"agent name":PONG* on the
broadcast bus: *DATA/*



All commands beginning with a **_** are client side provided and
expected to at most generate an error when not present.


Comments
--------


As a shell
**********

Sandbox for the language with console exists as a standalone script.
At the end of the session your code can be replayed like this:

like::

    (p3) jul@plumeau:~/src/confined$ confineds -j '{ "name":"jul", "tva":19.56}' session.2022-05-03-19:01:05.confined

results::

    **************** CODE *********************


    $name "ien": CAT
    $tva >NUM 100: DIV 40: MUL 
    $tva >NUM 100: DIV
    "tva": TAG
    DUP
    20:prix
    MUL


    **************** STACK ********************

    ******************************************
    |   3 | "julien": 
    |   2 | 7.824: 
    |   1 | 0.1956:tva 
    |   0 | 3.912:prix 
    ******************************************

As an interpreter
-----------------

If the binary is ending by an **s** it is considered a *shell*. Else it is 
an interpreter displaying the resulting stack.

Example of a valid confined script::

    #!/usr/bin/env confined
    #

    # The SECOND line beginging with a sharp is mandatory  at the beginning #
    # because confined comments are enclosed between to sharp signs         #
    2: 2: ADD

And when interpreted results in::

    $ ./test

    ******************************************
    |   0 | 4.0: 
    ******************************************




Templating
**********

Standalone
----------

Templating usage be used like python -mconfined

For usage::

    python confined -mconfined -h



As code
-------

Can also be used programmatically

Example::

    print templatize(dict(
        price=1, 
        q=3, 
        vat=19.6, 
        name="super carcajou", country="FR"
    ),'''
    <:
    "hello":world
    :> ici <:
        $name
    :> has
    <:
        $price >NUM
        $q >NUM MUL
        $vat >NUM 100:_per_cent_to_per_one DIV 
        1:_having_price_AND_vat ADD MUL >STR
        " ":_separator
        CAT
        "comment in string and drop":_or_in_tag
        DROP
        "€":_cur "$":_cur 
        $country
        "FR":_cocorico
        1:_nb_of_lines_for_looking_match
        MATCH
        IFT
        CAT :>
    may I have a dict please? <:
        $price >NUM
        $q
        "a string":with_a_name
        "ignored":_because_tag_starts_with_
        1231231231231231:a_long_int
        "a new name":_with_space
        TAG
        EDICT
    :>  ....  
    <: "fin": :>
    end''')


Gives::

    hello ici super carcajou has
    18.31 €
    may I have a dict please? {
        "q": "3", 
        "price": "1", 
        "with_a_name": "a string", 
        "a new name": "1231231231231231"
    }  ....  
    fin
    end

New callback features
*********************





Changelog
=========
* 0.2.0       adding functions to permit callbacks (for FAIM project) to use confined
            as a bus logic, adding "proxied commands", comments and *confined*
            interpreter.
* 0.1.17    adding the freeze/thaw functions that can store part of stack in 
            variables
* 0.1.16    requirements for prompt_toolkit added, fixed tokenization errors
* 0.1.15    confineds now save and restore your code at the end of session
* 0.1.14    proud enough of confineds the console to interact with stack
* 0.1.13    now put confined error in stack.
* 0.1.12    putting errors in the stack. Having fun adding function to remember how it works.
* 0.1.11    improved error handling (light), bug fixed in templating
* 0.1.10    python3 (overdue)
* 0.1.9     after too many failure, embedding check_arg in this
* 0.1.4     forgot howto declare requirements
* 0.1.2     going to fast, mis clicked a button in pypi
* 0.1.1     initial release
* 0.1.0     initial release oops forgot __name__ == main

Roadmap before 1.0.0
********************

* ensuring that stack is controled in size 
* handle Decimal nitroglycerine correctly so that users CAN multiply safely
* Having a cheatsheet for the language
* create a loads/dumps to be able to serialize code from a user for remote execution
* limiting the size of the input scripts
* using only iterator to be able to do nth repeated operation without copying everything in memory
* handle versions compatibility for remote execution
* handle the precisions and formating of Decimal
* enough tests to feel secure

Bigger roadmap
**************

Affter reading this https://compudanzas.net/uxn_tutorial.html I want to make a virtual machine
that is fun to work with for a kid.
I want to add the possibility to extend the language both in python to create interfaces/drivers
and in the language itslef (like in tcl).



