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

Bray Keywords

General

• Keywords are not case sensitive in Bray. For example DEFINE, Define and define are all equally valid keywords.
• White-Space is not permitted between the Keyword and the opening parenthesis of the parameter block.
• A comma character is used to separate parameters.
• White-Space is generally permitted inside the parameter block to space out the parameter elements.
• The parentheses characters are always needed even if the keyword does not take a parameter.

Keyword List:

• DEFINE, DEF
• PAUSE
• PORT
• SOUND
• SWITCH

DEFINE(param1,param2)

DEF(param1,param2)

DEFINE and DEF are synonymous - either form can be used.

Description

DEFINE Creates a Braced Packet param1 with the Scancode String value param2.

If a Braced Packet of the same name already exists it will be redefined with the new Scancode String value. The Braced Packet 'key' can consist of any alphanumeric character plus the 3 characters: dot hyphen underscore.

The Braced Packet 'key' is not case sensitive so {EXAMPLE} {Example} and {example} all refer to the same Packet.

Param2 represents a Scancode String. Param2 follows all the normal rules of embedding and concatenation but param2 must resolve entirely into Scancodes and therefore ASCII strings cannot be included.

If a Braced Packet is defined in terms of a second (already defined) packet the value of the second packet is passed by value, not by reference. This means that any redefinition of a packet never affects any other packet.

define({key.k},'42F042')

define({alt.k}),{altdn}{key.k}{altup})

def({alt.k}),'11 42 F042 F011')

def({alt.k}),'{altdn} 42 F042 {altup}')

def({alt.k}),{altdn}'42F042'{altup})

DEFINE({uk.pound},'{shdn}26f026{shup}')

DEFINE({uk.hash},'5df05d')

DEFINE({uk.tilda},'{shdn}5df05d{shup}')

DEFINE({uk.dquote},'{shdn}1ef01e{shup}')

DEFINE({uk.commercial-at},'{shdn}52f052{shup}')

PAUSE(number)

Description

Where number is a value representing seconds in the range 0 - 3600.

Number must be positive. The maximum pause period is 1 hour.

Number used will be rounded to the maximum precision available from a single precision floating point value. Do not expect timing accuracy to be better than about 0.05 seconds.

pause(1.5)

pause(7)

pause(60)

PORT(comport ID)

Description

The PORT command tells the Forward Channel which port to use when sending the Action Stream to the Mule for future operations.

The PORT request is logged but no further action to initialize or verify the PORT it taken until Bray needs to output data to the Forward Channel. This allows a subsequent SWITCH command to disable port initialization if the port is not available on the current machine. The corollary is that any error resulting from port initialization is not reported until real output is attempted.

The valid PORT range is COM1 thru COM99 (depending on the availability of suitable hardware). Notice there is no trailing colon on the comport ID.

All PORT opening/closing operations and RS232 settings like baud rate, handshake, buffering, start/stop/parity bits are set up to match The Mule defaults and handled automatically.

Issuing a PORT command for non existent hardware or for ports allocated to other running applications can result in computer hangs and latch up.

Phantom COM PORTS like those emulated by special purpose hardware (example USB to RS232 adaptors) should operate correctly but this is dependant on the driver provided by the hardware manufacturer.

port(COM1)

port(COM12)

SOUND(null)

Description

This keyword does not take a parameter

SOUND plays the default Windows waveform sound, typically a ¼ second tone, through either the built-in speaker or a sound card if installed (in which case the Windows "Default Beep" sound is played). The Default Beep can be configured in the Sounds section of Control Panel. If sounds are disabled in Windows Control Panel the SOUND keyword will be ignored.

sound()

Syntax 1: Set individual flags where flag value can be are 0 1 or -

SWITCH(Channel,Flags:KAECSN)

Syntax 2:Reset channel to default state. If channel is null then both channels are reset.

SWITCH(Channel)

Syntax 3:Report state of flags for channel. If channel is null then both channels are reported.

SWITCH(?Channel)

Description

The SWITCH keyword controls how the Bray interpreter communicates with the outside world by routing the Bray Communications Streams. More on Channels and Streams here.

The parameter to address the Forward Channel is 0. To address the Backward Channel use 1.

Bray uses a set of internal flags to decide how to route each stream. Each stream can be optionally routed to either channel. By default the Action stream is routed to the Forward Channel, the other streams are routed to the Backward Channel. The SWITCH command acts directly on the internal flags.

The default behaviour is usually suitable for normal running but there are a number of situations when you may need to change things. For example...

• You may want to prevent the Action stream being sent to the COMM port when developing code on a machine which does not have a physical COMM port.
• You may want to prevent the Action stream being sent to the COMM port when the Mule is not connected.
• You may want to send the Action stream to the Backward Channel in order to debug some problem.
• On the Backward Channel you may want to disable the commentary and source streams so any errors are not overlooked.

Syntax 1: Details

Bray uses a set of internal flags to route each stream. The SWITCH command acts directly on the internal flags. Each Channel has six flags identified by a single capital letter. Flags can be set (have value 1) or cleared (have value 0) or left unchanged (have value -).

The six flags are as follows...

• K: Kill-all flag. Is a global disable flag. When set it disables ALL output for the channel.
• A: Action flag. When set it enables output of the Action Stream for the channel (unless K flag is set)
• E: Error flag. When set transmission of error messages for the channel is enabled (unless K flag is set)
• C: Commentary flag: When set commentaries are transmitted for the channel (unless K flag is set)
• S: Source flag: When set the line of source code is transmitted to the channel (unless K flag is set)
• N: Numbering flag: When set line numbers are prepended to the source code data [See notes]

When flags are specified in a SWITCH command parameter data must be in the order KAECSN. Data for ALL the switches must be provided. Data for each flag must be one of these:

• 0 To clear or disable the flag
• 1 To set or enable the flag
• - To leave the existing state of the flag unchanged.

Notes on the Numbering flag

1: The Numbering flag affects whether source lines are transmitted. If the N flag is cleared then only non-blank source lines are transmitted. If set then all lines (including blank lines) will be prepended with a line number and transmitted. This is the default.

2: A line of Bray entered into the Immediate Mode box will be numbered 1: because it is treated exactly as a 1 line script.

Syntax 2: Details

If the Channel Number is provided but the Flags parameter is not supplied then SWITCH resets the flags for the channel to default.

If neither the Channel Number nor the Flags are given (empty parentheses) then SWITCH resets the flags for both channels to default.

SWITCH(0) is exactly equivalent to SWITCH(0,010001)

SWITCH(1) is exactly equivalent to SWITCH(1,011111)

Default values for channel 0 (Forward Channel)

• K: 0 - Kill-all flag disabled
• A: 1 - Action stream enabled
• E: 0 - Error stream disabled
• C: 0 - Commentary stream disabled
• S: 0 - Source line stream disabled
• N: 1 - Numbering flag enabled

Default values for channel 1 (Backward Channel)

• K: 0 - Kill-all flag disabled
• A: 1 - Action stream enabled
• E: 1 - Error stream enabled
• C: 1 - Commentary stream enabled
• S: 1 - Source line stream enabled
• N: 1 - Numbering flag enabled

Syntax 3: Details

To learn the current state of the SWITCH flags use a '?' character before the Channel number. Bray ALWAYS returns the state using the Commentary stream by the Backward Channel. This stream/channel is ALWAYS used for this particular purpose regardless of the current SWITCH flags configuration.

If the channel number is not given the flag status of both channels is reported

switch(0,1 - - - - - )

switch(0)

switch(?0)

switch(?)

switch(1,0 0 1 0 0 1)

switch(1,0 0 1 0 1 1)

switch(1,0 1 0 0 1 1)