Andys Binary Folding Editor, online help file, 12/01/00

--- General keys --------------------------------------------------------------

Up,Down,PgUp,PgDn,Home,End,Left,Right  Move around the list on display.
^E,^X,^R,^C,^W,^Z,^S,^D  WordStar cursor-diamond is supported too.
Esc         Discard current list on display, and step back to previous.
q,@X        Exit the editor, optionally saving any unsaved changes.
@W          Write unsaved changes back to files or extensions.
p           Print the current list on display to a file (overwrite or append).
^P          Print the current list, append to same file as last time.
f,/,F9      Find a pattern or extended regular expression.
n,F10       Repeat last find.
\           Reverse direction of next 'repeat last find'.
i,x         Pop-up new list made from current list, with just those lines
            which include or exclude a pattern or extended regular expression.
S           Pop-up new list made from current list, except lines are sorted.
N           Pop-up new list made as a snapshot of the current list.
            Useful when viewing live (continually changing) data.
@R          Toggle between pattern mode, and extended regular expression mode.
@I          Toggle between case-sensitive and non-case-sensitive modes.
r           Refresh the screen, without necessarily re-fetching data.
R           Refresh the data (if any is cached) and then the screen.
@U          Enter auto-refresh mode, which refreshes the data and screen, until
            you hit Ctrl+Break (OS/2, Windows and DOS) or Esc (elsewhere).
@T          Place or remove tag from current line.
T           Tag all lines matching pattern or extended regular expression.
U           Untag all lines matching pattern or extended regular expression.
^Home,^End  Skip to previous or next tag in current list.
@V          Pop-up list of lines in a text file, Esc to discard.
F1          Bring up this help file, Esc to discard.
F2          Bring up the initialisation file, Esc to discard.
F3          Behaves like Enter, when on a line in a list (like fold_in).
F4          Behaves like Esc, when in a list (like fold_out).
!           Execute operating system command.
@0,@1,...,@9  Jump to session 0 to 9. Initially in session 1.
@C          Copy previous session stack of lists onto current session.
@K          Show summary of all stacks of list on all sessions.
@F          Pop-up list of memory sections (ie: files/extensions being edited).
@M          Pop-up list of power address slide patterns.
@Z          Discard all popped-up lists, back to the topmost level of nesting.
@F1,@F2,@F3,@F4  Change to colour scheme 0 to 3.
A,O,L,I     Toggles display of addresses, offsets, lengths and array indices.
@A,@E,@B,@O,@D,@H  Set display of array indices to ASCII, EBCDIC, binary,
            octal, decimal or hex.
@Y          Toggles display of addresses between hex and symbol+offset forms.
@J          Toggles display of ARM specific long-jump addresses.
|           Toggles display of | symbols between flags in mappings.
&           Toggles display of pointer values
@           Display given definition at a given address.
            You'll first be prompted for definition name.
            You can append a count to this to display an array.
            Then you'll be prompted for the address.
            Pop-up a list of the fields in the definition at that address.
C           Disassemble at a given address.
            Pop-up a list of the instructions at that address.
D           Pass through user-options into disassembler.
Y           Toggle stop-disassembly at symbolic address change flag.
#           Set address-slide delta value (its initially 4).
            . in new value expression means current value.
?           Evaluate and display numeric expression.
$           Set variable to expression, or unset variable.
~F1,~F2,...,~F12  Set (or disable) power-address-slide pattern.
^L          For a given number of lines, perform a given keypress.
            ie: an easy way to do something to a number of lines on display.
            A zero or blank count means all the lines from current onwards.
^K          Toggle the ^L 'keep going on error' flag.
^           Set max number of elements in array/linked list to show.
^U,^V       Cycle memory sections one way or the other.
@G          Goto Nth line on display (numbered from 0 upwards).

--- When displaying data ------------------------------------------------------

.           Change current address (shown on title) to a new specified value.
            . in address expression means current address (shown on title).
,           Move current address (shown on title) by a specified amount.
(,)         Address-slide current address (shown on title) bwd/fwd by 1.
<,>         Address-slide current address (shown on title) bwd/fwd by delta.
[,]         Begin power-address-slide bwd/fwd (uses delta as the step).
{,}         Continue previous power-address-slide bwd/fwd. Can be stopped via
            Ctrl+Break (OS/2, Windows and DOS) or Esc (elsewhere).
@           Display given definition at a given address (as above).
            . in address expression means current address (shown on title).
?           Evaluate and display numeric expression (as above)
            . in expression means current address (shown on title).
$           Set variable to expression, or unset variable (as above)
            . in expression means current address (shown on title).
C           Disassemble at a given address (as above).
            . in address expression means current address (shown on title).
@P          Pop-up a list of all the definitions that include the current one.

--- Manipulating the current datum --------------------------------------------

g/l         Cause multibyte numeric values to be composed big or little endian.
s/u         Cause numeric values to be considered signed or unsigned.
a/e/b/o/d/h/k/y/m  Show current datum in ASCII, EBCDIC, binary, octal, decimal,
            hex, decode seconds since epoch, by symbol table, or via a mapping.
z           Toggle the 'stop displaying current buffers at 0 terminator' flag.
t           Pop-up new list with current data item split into lines of ASCII
            text, based upon CR, CR-LF or LF boundarys.
+/-         Increase or decrease the level of detail on display.
Enter       Pop-up a list made by showing the current datum in more detail.
            This can mean show the elements of a structure definition, or
            show the elements of a definition pointed to by the current datum,
            or expand an array of elements, one to a line.
            Esc discards the new list, back to the current list.
*           Current numeric datum is the address, BE prompts for definition.
            Operates much like @ key, only address is taken from numeric datum.
            Pop-up a list of the fields in the structure at that address.
P           Set/change what definition the current numeric field points to.
c           Current numeric datum is the code address.
            Pop-up a disassembly of the code at that address.
@L          When looking at a definition, and you are on a pointer to the same
            type of definition, this pops-up a list of linked-list elements.
=           Assign new value to current datum.
            If numeric, . in the new expression means the current value.
M           Pop-up a maplet list and show if each can be decoded from value.
@S          Toggle field suppress attribute (as shown in one line summary).
@N          Set field suppress attribute.
v           Disable (or re-enable) fields validity check.
V           Set/change the fields validity check expression.
w           Set field width. 0 means no padding/truncation.
Del         Copy current datum to memory clipboard or to a named file.
Ins         Paste from memory clipboard or from a named file.
E           Edit datum using external editor.
Z           Zero a data item.

--- When on a maplet list -----------------------------------------------------

0           Logically 'and' value with complement of maplet mask.
1           As above, then logically 'or' with maplet value.
@S          Toggle maplet suppress attribute.
@N          Set maplet suppress attribute.

--- When on a line of code ----------------------------------------------------

*           Current instruction has an address, BE prompts for definition.
            Pop-up a list of the fields in the structure at that address.
c           Current instruction references another code address.
            Pop-up a disassembly of the code at that address.

--- When on a memory section --------------------------------------------------

W           Write unsaved changes in this section back to files or extensions.
o           Send options to a given memory section.

--- When on a power address slide pattern -------------------------------------

=           Set (or disable) the pattern.

--- Conventions in the above --------------------------------------------------

~X is short for Shift+X, ^X is short for Ctrl+X, @X is short for Alt+X.
Note: On UNIX, Esc followed by X is equivelent to Alt+X.

--- Whats on the screen -------------------------------------------------------

Title line 1: Description of current list, line/totallines, session, nesting.
Title line 2: Subset of keys which may be used now (commonly used ones).
Title line 3: Space for prompts, status information, progress etc..
Other lines : Current list on display, current line highlighted.

--- Extended Regular Expressions ----------------------------------------------

Some basics just before we start :-

<ch>      ::= any typable character
<digit>   ::= any digit from '0' to '9'
<digits>  ::= <digit> { <digit> }
<digit19> ::= any digit from '1' to '9'
<hex>     ::= any digit or letter from 'a' to 'f' or 'A' to 'F'

Basic character definitions :-

<c> ::= '\n'                    newline
      | '\t'                    tab
      | '\r'                    carriage return
      | '\b'                    backspace
      | '\f'                    formfeed
      | '\e'                    escape
      | '\x' <hex> ( <hex> )    specify character in hex, one or two hex digits
      | '\' <ch>                other character, escaping any special meaning
      | <ch>                    normal character

Bracket element (something which goes in a bracket expression) :-

<be> ::= <c>                    a character
       | <c> '-' <c>            a range of characters
       | '[:alnum:]'            POSIX alphanumeric characters
       | '[:alpha:]'            POSIX alphabetic characters
       | '[:blank:]'            POSIX space and tab characters
       | '[:cntrl:]'            POSIX control characters
       | '[:digit:]'            POSIX numeric characters
       | '[:graph:]'            POSIX printable and visible (non-space) chars
       | '[:lower:]'            POSIX lowercase characters
       | '[:print:]'            POSIX alphanumeric characters
       | '[:punct:]'            POSIX punctuation characters
       | '[:space:]'            POSIX whitespace characters
       | '[:upper:]'            POSIX uppercase characters
       | '[:xdigit:]'           POSIX hexadecimal digits

       | '[.' ??? '.]'          POSIX collating symbols and
       | '[=' ??? '=]'          POSIX equivelence classes
                                ARE NOT SUPPORTED

Bracket expression :-

<bx> ::= [ '^' ] { <be> }       defines a set of acceptable characters
                                or a set of non-acceptable (if '^' present)

Extended Regular Expression :-

<re> ::=                        empty regular expression
       | <c>                    character
       | '~' <c>                not specified character
                                shorthand for '[^' <c> ']'
       | '\w'                   matches any 'word consituent' character
                                shorthand for '[[:alnum:]_]'
       | '\W'                   matches any non 'word consituent' character
                                shorthand for '[^[:alnum:]_]'
       | '.'                    matches any character (but not end of line)
       | '[' <bx> ']'           matches characters in the bracket expression
       | '^'                    matches empty string at the start of the 'line'
       | '$'                    matches empty string at the end of the 'line'
       | '\`'                   synonym for '^'
       | '\''                   synonym for '$'
       | '\<'                   matches empty string at the start of a 'word'
       | '\>'                   matches empty string at the end of a 'word'
       | '\B'                   matches empty string within 'word'
       | '\y'                   matches empty string at start or end of 'word'
                                shorthand for '(\<|\>)'
                                note: not '\b', as this clashes with backspace
       | <re> <re>              2 <re>'s concatenated form a <re>
       | '(' <re> ')'           nested regular expression
       | '\' <digit19>          backreference to nested regular expression
       | <re> '?'               zero or one occurrance of <re>
       | <re> '+'               one or more occurrances of <re>
       | <re> '*'               zero or more occurrances of <re>
       | <re> '{' <digits> '}'  matches M occurances of <re>
       | <re> '{' <digits> ',}' matches at least M occurances of <re>
       | <re> '{' <digits> ',' <digits> '}'
                                matches between M and N occurances of <re>
       | <re> '|' <re>          matches one <re> or the other

--- BE initialisation file language -------------------------------------------

Some basics just before we start :-

<number> ::= a number in C/C++ style
             as in 0b1101, 0o15, 13, or 0x0d, or '\r' or similar
<id>     ::= a C/C++ style identifier
<string> ::= a C/C++ style double quoted string
             which is clean (characters between 32 and 126 only)
             as in "Hello World" etc.
<buffer> ::= a string or hexstring buffer
             as in "SIGNATURE" or @FF0022

Numeric expressions :-

<sep>    ::= { ',' | ';' }

<expr13> ::= <number>
           | '+' <expr13>
           | '-' <expr13>
           | '~' <expr13>
           | '!' <expr13>
           | 'addr' <string>
           | 'sizeof' <id>
           | 'offsetof' <id> <string>
           | 'valof' <string>
           | 'map' <id> <string>
           | '(' <expr> ')'
           | <id>
           | '`' <id> <expr> '`'
           | '.'
           | '[' <n_value> <sep> <expr> [ <sep> <expr> ] ']'
           | '[[' <buffer> <sep>
             <expr> <sep> <expr> <sep> <expr> [ <sep> <expr> ] ']]'
           | 'strlen' <expr>

<expr12> ::= <expr13> { ( '*' | '/' | '%' ) <expr13> }
<expr11> ::= <expr12> { ( '+' | '-' ) <expr12> }
<expr10> ::= <expr11> { ( '<<' | '>>' | '>>>' ) <expr11> }
<expr9>  ::= <expr10> { ( '>' | '<' | '>=' | '<=' ) <expr10> }
<expr8>  ::= <expr9>  { ( '==' | '!=' ) <expr9> }
<expr7>  ::= <expr8>  { '&' <expr8> }
<expr6>  ::= <expr7>  { '^' <expr7> }
<expr5>  ::= <expr6>  { '|' <expr6> }
<expr4>  ::= <expr5>  { '&&' <expr5> }
<expr3>  ::= <expr4>  { '^^' <expr4> }
<expr2>  ::= <expr3>  { '||' <expr3> }
<expr>   ::= <expr2>  { '?' <expr2> ':' <expr2> }

Sometimes in expressions . (dot) is allowed. It usually refers to some default
amount. Other times it isn't allowed.

A maplet is mapping from a number to a string to display, and
a map is zero or more maplets. Using . in the maplet value (first expression)
means 0 or previous value plus 1, and in the maplet mask (optional second
expression) it means the same as the value.

<maplet> ::= <string> [ 'suppress' ] <expr> [ ':' <expr> ]
<map>    ::= 'map' <id> [ 'add' ] '{' { <maplet> } '}'

Numeric fields. Where the value comes from, how to display it, how to use it as
a pointer (if it is one), and putting it all together :-

<n_value>       ::= ( 'n8'  | 'n16' | 'n24' | 'n32' |
                      'n40' | 'n48' | 'n56' | 'n64' )
                    [ 'le' | 'be' ]
                    [ 'bits' <expr> ':' <expr> ]
                    [ 'signed' | 'unsigned' ]
<expr_value>    ::= 'expr' <string>
<code_attrs>    ::= [ 'lj' | 'nolj' | 'glue' | 'noglue' ]
<numeric_attrs> ::= [ 'map' <id> ]
                    [ 'asc' | 'ebc' | 'bin' | 'oct' | 
                      'dec' | 'hex' | 'sym' | 'time' ]
                    [ 'code' <code_attrs> | 'nocode' ]
<pointer_attrs> ::= [ 'ptr' <id>
                      [ 'null' | 'nonull' ]
                      [ 'rel' | 'abs' ]
                      [ 'mul' | 'nomul' ]
                      [ 'mult' <expr> ]
                      [ 'add' <expr> ]
                      [ 'align' <expr> ]
                      [ 'seg' | 'noseg' ]
                    ]
<numeric_field> ::= ( <n_value> | <expr_value> )
                    <numeric_attrs> <pointer_attrs>

The expr string is itself a numeric expression. You'll need to escape any
quotes within it.

A buffer field. How big, how to show the data, and whether to stop at a NUL
byte. Using . in the buffer size expression gives the current offset into the
definition :-

<buffer_field> ::= 'buf' <expr>
                   [ 'hex' | 'asc' | 'ebc' ]
                   [ 'zterm' | 'nozterm' ]

A field may name a nested definition :-

<def_field> ::= <id>

All fields share a set of general attributes, and have a name, so a complete
field specification looks like :-

<field> ::= ( <numeric_field> | <buffer_field> | <def_field> )
            { 'open' }
            [ 'valid' <string> ]
            [ 'width' <expr> ]
            [ 'suppress' ]
            [ 'tag' ]
            [ 'at' ]
            <string>

The valid string is itself a numeric expression.

Fields are just one type of item which can be found within a definition.
Offset within the definition, alignment and nested definitions.
Items in an itemlist follow one another (as in C/C++ structs), or overlay
each other (as in C/C++ unions). Using . in the at expression gives the
current offset into the definition. So definitions are specified as :-

<item>     ::= 'at' <expr>
             | 'align' <expr>
             | <itemlist>
             | <field>
             | ';'
<itemlist> ::= [ 'struct' | 'union' ] '{' { <item> } '}'
<def>      ::= 'def' <id> <itemlist>

File includes are specified :-

<include> := ( 'include' | 'tryinclude' ) <string>

The default attributes used, if not fully specified in the fields,
can be specified globally :-

<default> := 'asc' | 'ebc' | 'bin' | 'oct' | 'dec' | 'hex' | 'sym' | 'time'
           | 'signed' | 'unsigned'
           | 'be' | 'le'
           | 'rel' | 'abs'
           | 'mul' | 'nomul'
           | 'seg' | 'noseg'
           | 'null' | 'nonull'
           | 'code' | 'nocode'
           | 'lj' | 'nolj'
           | 'glue' | 'noglue'
           | 'zterm' | 'nozterm'
           | ( 'align' ( 'n8'  | 'n16' | 'n24' | 'n32' |
                         'n40' | 'n48' | 'n56' | 'n64' |
                         'def' | '{' | '}' )
               <expr> )

Set and unsetting :-

<set>   ::= 'set' <id> <expr>
<unset> ::= 'unset' <id>

So the total language is :-

<be> ::= <map>
       | <def>
       | <include>
       | <default>
       | <set>
       | <unset>

-------------------------------------------------------------------------------

Full documentation on WWW at http://www.interalpha.net/customer/nyangau/

{{{ Andy Key, nyangau@interalpha.co.uk
