Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

pal_intro - Introduction to PAL

CONTENTS

Description
How To Create Bytecode
Source File Structure
Reserved Code Labels
Reserved Data Labels
Example Source File
Binary File Layout
See Also
Author

The PROSE Programming Language is a general-purpose scripting language that compiles into platform-independent bytecode. This bytecode is interpreted by the PROSE engine in order to perform command execution. The bytecode can also be hand-crafted with the assistance of an assembly language, which consists of human-readable symbols that bear a direct correlation with the final bytecode product.

PAL (PROSE Assembly Language) is used to refer to the language that is used to hand-craft the bytecode.

Because the PROSE engine runs within a global hierarchical structure, known as "the nexus", PAL commands are based around the concepts of tree navigation. Data is represented within the nexus as nodes, and these nodes are described using classes and attributes, in a similar way as the data is addressed in Enterprise Directory (e.g. LDAP) servers. PAL is an optimised language for working within such a hierarchical environment.

Nodes (or "objects") within the nexus, are identified using object addresses in dot-notation. The top-most node is ".prose", and all program code is loaded in modules underneath ".prose.code".

An absolute object address starts with a dot, to anchor it to the top of the tree. A relative object address does not start with a dot, and is relative to the "context root". The "context root" is a node from which relative path addresses will begin from, and is identified using the symbol PCTX. The context root is initially set to point to the object being executed, but can be changed at any time to point to another node. Its concept is similar to that of the "working directory" when navigating hierarchical filesystems.

When a PROSE binary is loaded, the code is attached to the nexus in a path underneath ".prose.code" that has been specified within the binary itself, and this is called the "module root". The code in the ._init section (see RESERVED CODE LABELS) is then executed, which sets up functions in the nexus as required, all below the module root. Functions are independent sections of code which perform specific purposes, and can be interpreted in the traditional sense as with other functional programming languages.

Once all binaries have been loaded, all function objects called "main", attached immediately below the module roots, are executed. At this time, PROSE is not multi-threaded and can only execute a single "main" thread.

Certain operations require temporary memory storage within the nexus, and this temporary storage is allocated in a container underneath the current executing object and is called the "instance container". This container is unique for the running instance of that object. If the object is called recursively, multiple instance containers may be created.

PROSE is designed to execute multiple modules simultaneously, similar in concept to an Application Server, and the PAL programmer especially is expected to write code that can operate successfully in a shared environment.

There are two ways that bytecode is generated. Firstly, and most frequently, PROSE generates bytecode directly when compiling a PROSE script. Secondly, by passing an ASCII file containing PAL commands to the prism tool, which generates bytecode from assembly language.

It is this second method that is the subject of these manual reference pages on the PROSE Assembly Language.

The prism tool generally takes a source file with a file extension of .pal, and creates a bytecode file with a .pro extension, that can be interpreted directly by the prose tool.

A PAL source file is an ASCII file that contains lines which comply with one of the following formats:

.code_label
	This is a code section label, where code_label is a unique code identifier, i.e. a text name of some meaning to the programmer that is defined only once in the source file. The lines following a code section label must be program code, consisting of assembly commands, or another code section label.
PAL_command argument, ...
	An assembly command (or "instruction"), following a code_label. A new command must begin on a new line, or following a semi-colon if multiple instructions are stacked on a single line. One or more arguments may be required, and these are separated by commas. Arguments may wrap onto subsequent lines, indicated by finishing a line with a comma. A list of assembly commands can be found in pal_commands(5), or by running ’prism -l’.
~data_label
	This is a data section label, where data_label is a unique data identifier, similar to a code section label in that it is a text name, but used to identify a section of data within the source file. The lines following a data section label must be data entry macros.
PAL_macro { argument, ... }
	A data entry macro, following a data_label. Macros are used for entering static data into the source file that will be referenced by the assembly commands. One or more arguments may be provided, and are separated by commas. Arguments may wrap onto subsequent lines. A list of data entry macros can be found in pal_macros(5), or by running ’prism -l’.
% comment
	Where a percentage symbol % appears in a line, all text following it on the same line is treated as an author’s comment, and is ignored.
Blank line
	Blank lines are ignored.

The following code labels have a special meaning when used inside a PAL source file.

._init	The code in the ._init section is executed when the module is first loaded into PROSE. It is expected to set-up structures within the nexus that are required for basic operation, such as nodes containing functions, and module variables with global scope. It is an error for a file not to contain a ._init section.
._exit	The code in the ._exit section is executed when the module is being unloaded, either because the program has completed execution, or because an unrecoverable error has occurred. Once all ._exit sections have been called for a module, all data in the nexus underneath .prose.code.module_name is deleted. It is therefore only necessary to have a ._exit section if data needs to be cleaned up in other areas of the nexus. Note that the ._exit section is not yet implemented.

The following data labels have a special meaning when used in a PAL source file:

~Module
	This data label is used to define the name of the module under which the bytecode will be attached (the "module root"). Define the actual module name using an EQUS macro following the ~Module label. All modules are anchored to the nexus underneath .prose.code.module_name, where module_name is defined by the EQUS macro, and may contain further dots to define sub-modules. A module is a collection of PAL source files, with their own ._init and ._exit sections, but only one of these files may contain a function called "main", where program execution proper begins. The purpose of modules is to provide the programmer a means of separating application code into manageably sized units, especially in large applications or those that involve multiple software developers. If the ~Module label is omitted, the module_name will be set to "default", and therefore the code will be attached to the nexus at .prose.code.default.

The following demonstrates the layout of a PAL source file. Note that the order doesn’t matter, sections can be presented in any order. It is quite legal to reference a section label before it is defined. Although to assist with human readability, it is good practise to put the labels ~Module, ._init and ._exit at the top of the file.

~Module   EQUS {[mymod]} ._init   % Initialisation commands go here % e.g. set-up the functions func/def NULL, [main], &[.main] local/rtn ._exit   % Exit commands go here local/rtn ~mydata   % Macros can go here, if any data segments are needed EQUS {[data1], [data2], [data3]} .main   % Main program starts here func/rtn

Within a compiled file, bytecode is laid out in sections. These sections can be interrogated with the prism -v command, and can be briefly described as:

Header
	File information section, containing details about the compiler, and the compile date & time, among other things.
Instruction Code
	The bytecode itself.
Code Labels
	A table of code labels, and their corresponding index numbers. These indices match those used by the code addresses table.
Code Addresses
	A table of code addresses, and their corresponding index numbers. These indices match those used by the code label table.
Text Data
	A table of arbitrary text, and their corresponding index numbers. This is text that has been provided in square brackets [] as an argument to a command.
Data Labels
	A table of data labels, and their corresponding index numbers.
Data Xref Table
	A table used for cross-referencing the indices in the data label table, with those in the data segment table.
Data Segments
	A table of data segments, and their corresponding index numbers. This is the data that has been entered using the data entry macros.

pal_commands(5), pal_macros(5), prism(1),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2017 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.