Skip to content

Latest commit

 

History

History
184 lines (153 loc) · 17.3 KB

readme.md

File metadata and controls

184 lines (153 loc) · 17.3 KB
Raw

PicaxePreprocess.py

A PICAXE preprocessor to implement most preprocessor directives found in Picaxe Programming Editor 6 for use with axepad, blockly, and other non-PE6 editors.

This tool can also be used as a starting point for include/macro implementations in other software tools.

Table of contents

Setup

If you don't already have it, install python3.

Copy picaxepreprocess.py (and optionally the Makefile for advanced usage) to the directory your .bas files are in or to a known location. For ease of use this location may be in the system path such as /usr/local/bin so that the script can be accessible from anywhere on the system by entering picaxepreprocess.py in the terminal without needing to know the actual location.

You might also want to edit the compile_path variable to point to the Picaxe compilers. If you don't already have them, they can be downloaded from here. Alternatively, the compiler path can be specified with the -P option.

That's it!

Usage

Run ./picaxepreprocess.py.

If your starting file is named "main.bas", and you're ok with outputing to "compiled.bas", that's it!

You can also specify an input file with -i filename.bas or without the -i if it is the last option, such as picaxepreprocess.py input.bas Output files can be specified similarly with -o outputfilename.bas

The preprocessor will automatically look for included files in the working directory, and in a subdirectory called /include if it exists. (note: for optimal compatibility with PE6 includes, using this include directory on shared projects with PE6 users is not reccomended.) You can also specifiy absolute file paths.

Options and usage

In general usage, the script should be called and any required options and flags given after it on the same line as follows:

picaxepreprocess.py [OPTIONS] [INPUTFILE]

Optional switches

Short Extended Value expected Description
-i --file= yes Input file (default main.bas). Flag not required if it is the last argument given.
-o --ofile= yes Output file (default compiled.bas)
-u --upload no Send the file to the compiler if this option is included.
-s --syntax no Send the file to the compiler for a syntax check only (no download)
--nocolor no Disable terminal colour for systems that do not support it (Windows).
--noifs no Disable evaluation of #if and #ifdef - this will be left to the compiler if this flag is present.
--tablesertxd no Enable a non standard extension that will evaluate a ;#sertxd directive. See the Table Sertxd Extension section below for more details.
--tableserout no Enable a non standard extension that will evaluate a ;#serout directive. Also automatically enables --tablesertxd. See the Table Sertxd Extension section below for more details.
--verbose no Print preproccessor debugging info
-h --help no Display a text version of this help message

Optional switches only used if sending to the compiler

Short Extended Value expected Description
-v --variant= yes Variant (default 08m2) (alternatively use #PICAXE directive within the program. This option will be ignored if #PICAXE is used)
-s --syntax no Syntax check only (no download)
-f --firmware no Firmware check only (no download)
-c --comport= yes Assign COM/USB port device (default /dev/ttyUSB0). Alternately use #COM directive within program. This option will be ignored if #COM is used. There should be a space between the -c and the port on unix based systems, unlike the compilers.
-d --debug no Leave port open for debug display (b0-13)
--debughex no Leave port open for debug display (hex mode)
-e --edebug no Leave port open for debug display (b14-b27)
--edebughex no Leave port open for debug display (hex mode)
-t --term no Leave port open for sertxd display
--termhex no Leave port open for sertxd display (hex mode)
--termint no Leave port open for sertxd display (int mode)
-p --pass no Add pass message to error report file
--tidy no Remove the output file on completion if in upload mode.
-P --compilepath= yes Specify the path to the compilers directory (defaults to /usr/local/lib/picaxe/)

Table Sertxd/Serout Extension

Enable a non standard extension that will evaluate a ;#sertxd or ;#serout directive to automatically save, load and print a string from table memory on supported chips.

For example:

;#sertxd("Hello world", cr, lf)

Syntax is the same as the sertxd command, although dynamic content such as printing variables is not supported and may cause cryptic errors if attempted.

Two word and one byte variables are required for storing addresses and processing, as set by the defines outlined below. These variables can be modified between calls to ;#sertxd, although any call to ;#sertxd will modify them unless variable backup and restore to storage ram is enabled.

The folowing definitions can be used to change the default behaviour (and apply to both tablesertxd and tableserout:

Definition Default Value Description
TABLE_SERTXD_ADDRESS_VAR w0 Changes the word used. If not backing up, the value in it will be lost when ;#sertxd is called.
TABLE_SERTXD_ADDRESS_END_VAR w1 Changes the word used.
TABLE_SERTXD_TMP_BYTE b4 Changes the byte used.
TABLE_SERTXD_BACKUP_VARS Do not backup Enable saving & restoring the variables used to storage ram. This is slower as it uses peek & poke, but allows the variables to keep their value accross ;#sertxd calls.
TABLE_SERTXD_USE_EEPROM Use table memory If defined, uses eeprom to store strings instead of table memory, allowing this extension to be used on chips without table memory.
TABLE_SERTXD_MEM_OFFSET 0 Offset the start of the first string in case the first part of the memory is needed for something else.

Only required if backing up variables:

Definition Default Value Description
TABLE_SERTXD_BACKUP_LOC 121 The location in storage ram to save the existing values of the general purpose variables. 5 bytes are required.
TABLE_SERTXD_ADDRESS_VAR_L b0 The lower byte (I haven't had much success in using peek and poke with words, so need the individual bytes)
TABLE_SERTXD_ADDRESS_VAR_H b1 The upper byte
TABLE_SERTXD_ADDRESS_END_VAR_L b2 The lower byte
TABLE_SERTXD_ADDRESS_END_VAR_H b3 The upper byte

This flag also enables the non standard ;#sertxdnl directive that prints a new line. When called many times, this uses less program space than sertxd(cr, lf)

Only required for tableserout:

Definition Default Value Description
TABLE_SEROUT_PIN none(required) The output pin to send the serial message on (eg C.0).
TABLE_SEROUT_BAUD N4800 The baud rate to output the serial signal (see the PICAXE Command Reference for list of valid baud rates)

Table Sertxd Extension usage example

Click to expand

As an example of what it does, a cutdown version of the simple.bas example:

#picaxe 14m2
main:
    ;#sertxd("Hello World", cr, lf)
    ;#sertxd("That's a really annoying line!", cr,lf,"(because of all the characters that have to be ignored when in a string;",cr, lf, "such as ',', ''', ';', ')', '(', ']', '[', ':', '#', ...")
    ;#sertxd("This line contains dynamic content that cannot be printed", #w0)
    pause 5000
    goto main

is preprocessed (on Ubuntu) using:

cd Examples/SertxdTableExtension
# picaxepreprocess.py is copied into a folder on the path, so I can just call it as follows:
picaxepreprocess.py -s --tablesertxd simple.bas # Syntax check and enable tablesertxd extension.
'-----PREPROCESSED BY picaxepreprocess.py-----
'----UPDATED AT 12:05PM, March 13, 2021----
'----SAVING AS compiled.bas ----

'---BEGIN simple.bas ---
#picaxe 14m2      'CHIP VERSION PARSED
main:
;#sertxd("Hello World", cr, lf) 'Evaluated below
w0 = 0
w1 = 12
gosub print_table_sertxd
;#sertxd("That's a really annoying line!", cr,lf,"(because of all the characters that have to be ignored when in a string;",cr, lf, "such as ',', ''', ';', ')', '(', ']', '[', ':', '#', ...") 'Evaluated below
w0 = 13
w1 = 174
gosub print_table_sertxd
;#sertxd("This line contains dynamic content that cannot be printed", #w0) 'Evaluated below
w0 = 175
w1 = 232
gosub print_table_sertxd
    pause 5000
    goto main

'---Extras added by the preprocessor---
print_table_sertxd:
    for w0 = w0 to w1
    readtable w0, b4
    sertxd(b4)
next w0

    return

table 0, ("Hello World",cr,lf) ;#sertxd
table 13, ("That's a really annoying line!",cr,lf,"(because of all the characters that have to be ignored when in a string;",cr,lf,"such as ',', ''', ';', ')', '(', ']', '[', ':', '#', ...") ;#sertxd
table 175, ("This line contains dynamic content that cannot be printed","?") ;#sertxd

And should print something like:

Hello World
That's a really annoying line!
(because of all the characters that have to be ignored when in a string;
such as ',', ''', ';', ')', '(', ']', '[', ':', '#', ... This line contains dynamic content that cannot be printed ?

Usage with a makefile

See the Makefile for an example of advanced usage. When properly configured, the makefile can automatically handle preprocessing the code, compiling it, and uploading to a picaxe chip by simply invoking make compile and run a syntax check with make syntax. The makefile also demonstrates usage with multiple picaxe chips with separate programs in the same project directory.

Other projects

If you're interested in this project, you may also like this similar PICAXE Preprocessor implementation, or this similar C-style preprocessor from ParksProjets.