This content is archived and may be deprecated or obsolete and is presented in the hope that it may still be useful.
Revision 2 (Mon,07 Mar 2005.14:31:01)
. Moved Easel API to http://jonripley.com/easel/api.txt
. Reordered channel stream IDs, channel 00h is now reserved
This is a request for comments. Feedback should be directed to
mailto:jon@jonripley.com include [easel] at the start of the command line.
On start Easel-PESOIX starts up in a special non-PESOISX compatibility
mode.
This will allow all PESOIX unaware applications to run correctly without
modification. (See exception below.)
To enable PESOIX your program should output the PESOIX-Initialise
command sequence:
00h 08h
If any other output is received by PESOIX prior to issuing this command
PESOIX will become locked in non-PESOISX compatibility mode. Once PESOIX
locked in non-PESOISX compatibility mode it will be impossible to issue
PESOIX command sequences. This is done to aceive maximum compatibility
between PESOIX aware esotools and PESOIX unaware applications.
There is one exception, if a PESOIX unaware program issues
PESOIX-Initialise upon start then PESOIX will be enabled and the program
will may fail to operate correctly. At this time there are no known
PESOIX unaware applications that display this behaviour.
PESOIX will respond to PESOIX-Initialise in one of two ways:
1. If the PESOIX aware esotool has declared that it supports memory
cells, the current cell will be set to NUL. 2. If memory cells are not
supported NUL will be placed in the input stream.
Where the esotool has not declared memory cell support an attempt to
complete option 1, potentially leading to undefined results. This is a
necessary evil to support BrainfuckOS.
Once PESOIX-Initialise command has completed, PESOIX will be running
EsoAPI - dialect zero.
Your application should at this point check for NUL being returned by
PESOIX.
Where NUL has not been returned your applications should exit with an
error. A suggest error message is "PESOIX Required".
Dialect zero provides EsoAPI compatibility which is required by
BrainfuckOS. Further information is available in the EsoAPI Support
section later in this document.
All implementations of PESOIX must support the minimum guaranteed EsoAPI
calls.
To select another dialect for use your application should issue the
PESOIX-SetDialect command sequence:
00h 09h xxh
Where xxh represents the Dialect ID.
A return code indicating sucess or failure will be placed on the input
channel, your application should read this value and respond
appropriately.
Return code 0 - PESOIX-SetDialect was successful
Return code 1 - PESOIX-SetDialect failed
Once a dialect has been selected you have access to the full API that
the dialect provides.
Command banks 09h and 10h are reserved in all dialects to provide PESOIX
system commands. These are currently: **CAN THESE BE MADE 0Ah instead?**
00h 09h xxh - PESOIX-SetDialect (see above)
00h 10h 00h xxh yyh - PESOIX-SetBufferedStatus
00h 10h 01h xxh - PESOIX-ReadBufferedStatus
00h 10h 02h xxh - PESOIX-ClearBuffer
PESOIX-SetBufferedStatus alters the buffered status of the named
channel and takes two arguments, channel_id and is_buffered. No result
is returned. **Should this return success/failure?**
PESOIX-ReadBufferedStatus queries the buffered status of a named channel
and takes one argument, channel_id.
Return code 0 - channel_id is buffered
Return code 1 - channel_id is not buffered
PESOIX-ClearBuffer discards all pending data in the named channel and
takes one argument, channel_id.
Currently allocated channel_ids are as follows.
00h - <Reserved>
01h - STDIN
02h - STDOUT
03h - STDERR
Currently known Dialects are:
00h - EsoAPI
01h - Easel
02h to 79h - Reserved for future dialects
7ah to 7ef - Free for users
7fh - Reserved for the testing of experimental features
Dialects 02h to 79h are reserved for future PESOIX dialects. If you wish
to create your own PESOIX dialect you should submit full specifications
of your dialect to <official body> for review. If your application is
successful you will be granted an official dialect ID and your dialect
will be added to the official list.
Dialects 7ah to 7eh are free for users to develop their own dialects.
These six dialects are for the users own private and personal use only.
Applications using user dialects should never be released to the general
public. If you wish to release your dialect you must apply for an
official dialect ID.
Easel-PESOIX supports the minumum EsoAPI guarantee, Easel and dialect
7f.
EsoAPI Support
--------------
The EsoAPI is designed to extend the functionality of esoteric languages
through use of special output escape sequences. These allow the use of
previously unsupported hardware and devices, such as disk I/O.
EsoAPI 1.0 calls replace the normal output functions. To perform an
EsoAPI operation, write the necessary NUL escape character and function
call bytes to the output stream. Some function calls may return a
status value in the current memory cell. Any other data will start in
the cell following the current memory cell.
Under PESOIX EsoAPI may be emulated, the minimum API calls that are
guaranteed to be implemented are marked with an asterisk.
API Call Description
-------- -----------
01h - FFh * OUTPUT character. Prints the character to the screen.
00h 00h * OUTPUT 00h. Prints the NUL character to the screen.
00h 01h NEXT SECTOR. Selects the next disk sector for I/O
operations.
00h 02h PREVIOUS SECTOR. Selects the preceeding disk sector
for I/O operations.
00h 03h READ SECTOR. Reads the currently selected disk sector
into memory. The sector data starts after the current
cell.
00h 04h WRITE SECTOR. Writes the currently selected disk
sector from memory. The sector data starts after the
current cell.
00h 05h RESET SECTOR POSITION. Selects the first disk sector
for I/O operations.
00h 08h * INSTALLATION CHECK. Returns a result code of 0.
00h 09h xxh * SELECT DIALECT. Selects PESOIX dialect xxh, returns a
result code of 0 if the operation is successful.
00h 10h xxh xxh * PESOIX SYSTEM CALLS. Call a PESOIX system function.
EsoAPI Code Wrapper
-------------------
To prevent PESOIX unaware interpreters from executing EsoAPI code, use
the following wrapper code (or similar):
+>.++++++++.[++++++[>++>+++++>++++++++>+++++++>+<<<<<-]>>-.>+++.----.<
----.+++++++++++++++.-------.<++++.>>+++.>+++.<-.++++.>++++.<---.>----
.-.>-.---.>>]<[ program goes here ]
Easel - Dialect 1
-----------------
The Easel is designed to provide both low level and high level operating
system abstraction layer to esoteric languages. Allowing the use of
previously unsupported features, such as file I/O and the passing of
parameters to programs from the command line. Also allowing previously
non-trivial tasks to be completed in a simple manner, such as data
output.
Easel calls replace the normal output functions. To perform an Easel
operation, write the necessary NUL escape character and function call
bytes and parameters to the output stream. Some function calls may
return a status value in the input stream.
This API is in development and a state of flux.
see http://jonripley.com/easel/api.txt for current API call specifications.
Comments, ideas and suggestions for features are requested.
Features implemented will be similiar to those available in the standard
C library along with a number of other useful calls.
Contact Information For EsoAPI - Dialect zero
---------------------------------------------
[WWW]
http://kidsquid.com/programs/bf/bf.html
[IRC]
Server: irc.freenode.net
Channel: #esoteric
Nick: calamari
[E-Mail]
bos@kidsquid.com
Contact Information For Easel and Easel-PESOIX
----------------------------------------------
[WWW]
http://jonripley.com/
[IRC] Server: irc.freenode.net
Channel: #esoteric
Nick: {^Raven^}
[E-Mail]
jon@jonripley.com