"To talk to a Mule you have to Bray..."

Bray Basics

• Comments, Blanks, White-Space and Capitalisation
• Channels and Streams
• Strings and Braced Packets
• String Concatenation
• Automatic Sending of Strings

---

Comments, Blanks, White-Space and Capitalisation

Comments in a Bray script

Comments are used in a script to aid human understanding and to provide other identifying content. Comments are ignored by the Bray Interpreter.

Comments are defined as any printed content on a line following a hash character (#) providing the hash character is not in an ASCII string (see Strings: later)

If the hash character is the first character on a line the whole line is comment. Alternatively comments can follow any active script content on the same line. The hash and anything following is ignored by the Bray interpreter.

Blank Lines and Spaces

The Bray interpreter ignores blank lines. Blank lines can be used to space out the script making it easier to read.

Bray defines any character with an ASCII value of 32 or less as White-Space. Note that 'White-Space' is different from 'Space'. White-Space includes the Space character PLUS all the other ASCII characters often used to space out text. The most useful White-Space characters are the 'Space' and the 'Tab', either of these can be used to format and space out components of Bray script making it easier to read and understand.

White-Space characters are generally ignored in a Bray Script unless they have significance for example in quoted strings. White-Space can be used to make the code more readable by spacing out some sections of code. For example spaces between keyword parameters or concatenated strings will be ignored by Bray.

You are encouraged to use comments, blank lines and White-Space to format and annotate the script making it easier to understand.

Capitalisation

Components of the Bray Language are not case sensitive. Capitals or lower case letters can be used for Keywords and Braced Packet Keys. For example the DEFINE keyword can equally well be written into the script as DEFINE Define or define. To aid clarity we use the capital letter form in the documentation. For working scripts professional programmers often prefer to use the lower case form. The capitalisation of quoted literal ASCII strings is respected and maintained.

---

Channels and Streams

To manage the flow of data Bray uses the concept of Channels and Streams. Bray can be thought of as a black-box. All the data leaving the Bray black-box is conveyed through a channel. Before Bray sends data to a channel it divides it into individual streams. Each stream consists of a particular category of data.

Bray has 2 channels and 4 streams. The default settings for Channels and Streams are good for most purposes. Special configurations can be set up using the SWITCH keyword.

Channels

• Forward Channel
  The Forward Channel is given the channel number 0 and is connected to the computer COM port. The Forward Channel (Channel 0) is generally the channel used to convey the Action Stream to the Mule.
• Backward Channel
  The Backward Channel is given the channel number 1. It is generally used to convey Error Messages and Commentaries. The Backward channel is used by the Mule Dispatcher and linked through to its Activity Log Monitor Panel.

Streams

Data leaving the Bray interpreter is divided into four streams. Each stream is identified by the first initial letter followed by a colon and a space (except the Action stream when sent to Channel 0)

• A: Action Stream
  The Action Stream is the end product of the Bray Interpreter. It is the actual data used to control The Mule. By default it is sent to the Forward Channel without an identifying prefix. When sent to the Backward Channel the Action Stream is prepended by A: and any ScanCode content is differentiated from ASCII codes by being surrounded by double angle bracket characters.
• E: Error Stream
  Error messages are sent with a E: prefix. By default the Error Stream is sent to the Backward Channel (Channel 1)
• C: Commentary Stream
  Bray sends messages to help understand the flow and current state of the program flow. These messages are called Commentaries or Commentary Messages. The prefix C: is used to identify them. By default commentaries are sent to the Backward Channel.
• S: Source Stream
  The Source Stream is the line of code Bray is currently working on. It is identical to the line of Source Code exactly as received by Bray except leading and trailing White-Space is stripped. The prefix S: is used to identify the Source Stream. The Source File line number is also prepended to the Stream in order to assist the debugging process. The SWITCH command can be used to disable Line Numbering if preferred. By default Line Numbering is enabled and the Source Stream is directed to the Backward Channel.

---

Strings and Braced Packets

Strings

The main objective of Bray is to emulate specific keystroke sequences. For this reason strings are of primary importance. There two types of string in Bray: ASCII strings and scancode strings.

• ASCII strings
  ASCII strings are simply a list of ASCII characters similar to strings in many other computer languages. In Bray ASCII strings are indicated by surrounding them with double-quote characters. They can only contain printable ASCII characters, the Space character and Braced Packets. Packets are used to handle non-ASCII keys like the Keyboard Function Keys and others. (for more detail refer to the Braced Packet Section). Here is an example of an ASCII string with a Carriage Return character at the end...
  "Hello World{ret}"

  Some characters have special significance and would normally be impossible to include in an ASCII string. To deal with this the character must be 'escaped' to strip it of its special significance. This is done by preceding it with a backslash character. The Double-quote, the opening curly brace and the backslash itself all need to be escaped.

• Scancode Strings
  Scancodes are the fundamental components for building Key Sequences. Scancodes are represented by pairs of hexadecimal characters. For example the 'F0' represents the Scancode which precedes most key releases. (Scancodes can be looked up in tables or more easily obtained from our Keyboard Emulator). In Bray the capitalisation of scancodes does not matter, 'F0' and 'f0' have the same meaning. In Bray Scancode Strings are indicated by surrounding them with single-quote characters (sometimes called Apostrophe). Scancode Strings can only contain Scancodes, Braced Packets and White-Space. White-space has no significance other than to make the string more comprehensible for a human reader. It is ignored by Bray. However white-space between the paired characters of a single scancode is invalid. Here is an example of a Scancode String. It holds information representing the F1 key pressed and released 2 times. The first time by a spaced set of scancodes, the second by a Braced Packet...
  '05 F005 {f1}'

Braced Packets

In Bray a Braced Packet is just a wrapper for a Scancode String with a mnemonic label. A Braced Packet can be used anywhere a Scancode string could be used. In addition Braced Packets can be embedded in ASCII strings (this would be invalid for single quoted Scancode Strings). A Braced Packet is always expanded into its Scancode Components before being used.

A Braced Packet consists of a 'Key' surrounded by the Curly Brace characters. The Key can contain any alphanumeric characters as well as dot(period) hyphen and underscore. Bray ignores the capitalisation of the Key. There must not be any White-Space between the Braces. (The maximum length for a Key is not currently defined but may be limited to around 30 characters in the future).

New Packets can be created and existing packets redefined by using the DEFINE keyword. Bray has predefined a number of Braced Packets shown the table.

Pre defined Scancode Packet Entities

Packet	Scan Code Sequence	Details
{ret}	5af05a	Return key
{shret}	125af05af012	Shifted Return
{tab}	0df00d	Tab key
{shtab}	120df00df012	Shifted Tab
{ent}	e05ae0f05a	Enter key
{esc}	76f076	Esc key
{cad}	141171f071f011f014	Cntrl+Alt+Del
{caplok}	58f058	Caps Lock key
{numlok}	77f077	Num Lock key
{scrlok}	46f046	Scr Lock key
{f1}	05f005	F1 key
{f2}	06f006	F2 key
{f3}	04f004	F3 key
{f4}	0cf00c	F4 key
{f5}	03f003	F5 key
{f6}	0bf00b	F6 key
{f7}	83f083	F7 key
{f8}	0af00a	F8 key
{f9}	01f001	F9 key
{f10}	09f009	F10 key
{f11}	78f078	F11 key
{f12}	07f007	F12 key
The following can be used as components for defining more complex packets
{shdn}	12	Left Shift key pressed (key down only)
{shup}	f012	Left Shift key released (key up only)
{ctdn}	14	Left Control key pressed (key down only)
{ctup}	f014	Left Control key released (key up only)
{aldn}	11	Left Alt key down (key down only)
{alup}	f014	Left Alt key up (key up only)

---

String Concatenation

In Bray wherever a string is valid, a list of String Entities is equally valid. The list is automatically concatenated (strung together) and used as a single string. There is no special concatenation operator. The String Entity components are just listed on the line adjacent to each other. Here is the List of valid String Entity Components.

• ASCII strings (surrounded by Double Quote characters)
• Scancode Strings (surrounded by Single Quote characters)
• Braced Packets

This syntax definition provides that Braced Packets can be used inside either type of string or can stand alone outside a string.

White-Space may be used between the components to make the whole easier to read. The White-Space is ignored by Bray and not included in the final string. If you need Space to be included it must be surrounded by Double Quote characters just like an ASCII string.

Notice that Bray takes care of all the issues resulting from the mixing of ASCII and Scancode string types. You do not need to consider when to shift the Mule in and out of scancode mode. Bray takes care of it all automatically.

Example of a list of String Entities
"Hello World{ret}" {F10} {Tab} '05 F0 05{ret}'

---

Automatic Sending of strings

In Bray a 'non-attached' String Entity is automatically processed and sent to the Action Stream (The Action stream is usually directed to the Mule). 'Non-attached' means the string is standing alone on a line and is not a parameter of a Keyword.

If more than one String Entity are found together they will be concatenated before processing. This is important because the intelligent algorithm which controls switching in and out of scancode mode is applied to the whole resultant string rather than to the individual components resulting in greater efficiency