extensions

SPR/Python extensions

** changing again, because of WITH. **

An SPR library/module is a Python module with a python file, a yaml file and an spr file. An SPR library project can be created with the new-spr-extension-project command.

`new-spr-extension-project path/to/my/new/library/foo` 

To install, python setup.py install will install your project into your local python environment / site-packages.

Once the new module is available on the Python path SPR can import it with a command like this. namespace foo "my foo namespace" foo.core function1 function2

This will create a namespace foo within SPR with all the functions listed, as well as whatever is defined in foo/core.spr. The yaml datastore will merge in what ever structure is defined in foo/core.yaml.

How to do it.

• Make a python extension with the new-spr-extension-project path/to/project command.
• Define some data structure/YAML.
• Add in some python code. - the stuff you really want to do.
• Write some spr code if you need it.

Interact in the Repl, SPR -r to start creating new commands which are lists of other commands. Test and play with your code, and create a new process.

Make one.

A picture is worth a million words. use the new-spr-extension-project to make a project and go look at it. looking at the help for a namespace may also be enlightening. There are three core files to an SPR extension. A python module, a yaml file and an spr file. Only the python is necessary. All of the builtin extensions follow this same model. bar_qr in the repo is a good example if you want to read the source.

Here is the result of new-spr-extension-project foo.

foo
├── foo
│   ├── core.py
│   ├── core.spr
│   ├── core.yaml
│   └── __init__.py
├── README.md
└── setup.py

Python code

SPR can just import a python module and make those functions available, in the interpreter. However, there is usually some sort of wrapping up to make life easier in SPR. It is fairly easy to make an extension made from example snippets gleaned from StackOverflow.

The python functions for use as an SPR extension are generally very simple,

• Retrieve their configuration data from the yaml datastore,
• Do something,
• Save the result back into their part of the yaml datastore as needed.

To that end, the template created has example -to, -from and -with functions to be used.

Yaml Data Structure

Additionally, an extension can define a yaml file which import will integrate into the yaml datastore. It can also be included in the spr file instead using the quote syntax. Configuration settings and whatever data structure needed by the extension are defined here.

Here is how the bar/QR code module defines it's yaml datastore structure and it's configuration settings in bar_qr.yaml.

bar-QR:
    src: Null
    value: ''
    QR_code:
        code: Null
        saved: ''
    barcode:
        code: Null
        saved: ''

config:
    QR_code:
        filename_suffix: 'QR'
        prefix: 'K1'
        suffix: 'A'
        save_path: 'qrcodes'
        font: DejaVuSans.ttf
        font_size: 18
    barcode:
        filename_suffix: 'BC'
        prefix: ''
        suffix: ''
        save_path: 'barcodes'
        save_options:
            module_height: 8
            text_distance: 2

SPR code

The above method of defining the data structure still works, but it can now be within the spr code. A single quote ' on a line by it's self Followed by yaml code, and ending with 2 blank lines, will allow everything to exist together.

This is where more Libraries can be imported and new symbols and partial functions can be defined. As well as the YAML if desired.

The Bar/QR extension is a good example of all of this. It only provides a few python functions some configuration, and some SPR symbol definitions, The files in the repo are: bar_qr.py and bar_qr.spr which has both spr and yaml combined.

Here is the spr contents of bar_qr.spr. Notice it makes a new command input-code which is actually a dialog window in the ui namespace. The result value is popped to value so that the next function will pick it up.

'
bar-QR:
    src: Null
    value: ''
    QR_code:
        code: Null
        saved: ''
    barcode:
        code: Null
        saved: ''

config:
    QR_code:
        filename_suffix: 'QR'
        prefix: 'K1'
        suffix: 'A'
        save_path: 'qrcodes'
        font: DejaVuSans.ttf
        font_size: 18
    barcode:
        filename_suffix: 'BC'
        prefix: ''
        suffix: ''
        save_path: 'barcodes'
        save_options:
            module_height: 8
            text_distance: 2


def input-code
    "Dialog to get a string to encode to a bar or QR code"
    '
    - ui/input-string
    - pop results value