Proposal for new functionality to define macros in a structured way using a text-based format

[abrahamwolk]

1 Proposal for new functionality to define macros in a structured way using a text-based format

Dear All,

The following is a proposal for a new functionality for Phoebus: the functionality to define macros in a structured way using a text-based format, and to specify OPIs together with macro definitions such that OPIs can be loaded with macro definitions.

We have developed a prototype of this functionality at ESS. We believe that this is a functionality that would benefit other sites using Phoebus, as well as benefit from being included in the main Phoebus source tree. Therefore, we would like to ask whether other participants in the Phoebus collaboration are interested in this functionality, if they have any input on its design, and if they would be happy to include it in the Phoebus source tree.

The proposed design is based around a text-based format, with the intention of these files being edited in a text editor, and being version controlled in a version control system for text-based files, such as, e.g., Git.

The following is an introduction to the implemented functionality.

2. Introduction to the proposal

Sometimes, an OPI is parameterized by a set of macros, and the same .bob-file is instantiated with different sets of values for those macros, in order to obtain graphical interfaces for a range of similar systems, using the same .bob-file for each system.

In order to facilitate re-use of .bob-files in this manner, we propose the implementation of two new kinds of files: .screen-files together with the related .bindings-files. Together, these two new kinds of file would provide a structured way of instantiating the same .bob file with different sets of macro definitions: macro definitions can be split across several files, and individual .screen- and .bindings-files can import other .screen- and .bindings- files, allowing for sharing of definitions.

3. Basic functionality

3.1 Loading an OPI with macro definitions

Consider, e.g., a file test.screen with the following contents:

A=1
B=2

#opi<test.bob>

If this file is loaded in Phoebus through 'File' -> 'Open', the OPI test.bob will be loaded with the macro definitions A=1 and B=2 set.

It is also possible to effect the opening of a .screen-file from within an OPI by adding an action of type "Open Screen" to, e.g., an action button.

3.2 Referencing previously defined macro definitions

Macro definitions can also reference previously defined macros. E.g., the following .screen-file will load the OPI test.bob with the macro definitions A=1, B=2, and C=123:

A=1
B=2
C=$(A)$(B)3

#opi<test.bob>

4. Including macro definitions from .screen- and .bindings-files

4.1 Including .screen-files

It is possible to include macro definitions from another .screen-file into a .screen-file by using a #include-statement.

Consider, e.g., the file test2.screen with the following contents:

#include<test.screen>

C=1
D=2

#opi<test2.bob>

Loading this file into Phoebus, the OPI test2.bob will be loaded with the macro definitions A=1, B=2, C=1, and D=2. Note that only the OPI test2.bob is loaded, even though the included file test.screen contains the declaration #opi<test.bob>: any #opi- statements in included files are ignored, and only macro definitions in included files are imported.

4.2 Including .bindings-files

It is also possible to create files containing only macro definitions. Such files must have the file extension .bindings. The structure of a .bindings- file is the same as the structure of a .screen-file, except that it must not contain an #opi-declaration at the end of the file. The purpose of .bindings-files is to contain macro definitions that are shared between several .screen-files, without having to define an OPI that is associated with the shared macro definitions.

As an example, consider the following file test.bindings:

A=1
B=2

and the following file test3.screen, which imports the definitions in test.bindings:

#include<test.bindings>

C=1
D=2

#opi<test2.bob>

Loading the file test3.screen will have the same effect as loading the file test2.screen from section 4.1.

4.3 Limitations on inclusions

When including either .screen- or .bindings-files, the included files may in turn include other files, giving rise to a tree of .screen- and .bindings-files where the nodes of the tree are included files (with the root being the "main" .screen-file that is loaded) and the links of the tree indicating inclusions. In this tree, no file may be included twice, and no macro may be defined twice: all defined macro names must only be defined once. These constraints have been implemented in order to make .screen- files easier to reason about.

5 Comments

It is possible to add comments to .screen- and .bindings-files. Comments start with // and extend until the next newline.

For example, the following is a .screen-file with comments:

// This is a .screen-file with comments.
#include<test.bindings> // This is a comment.

C=1
D=2 // This is also a comment.

#opi<test2.bob>
// This is the last comment in this example.

6 Debugging .screen- and .bindings-files

If an error occurs when reading a .screen- or .bindings-files, then a window opens that displays a log of which bindings have been added from which file and in which order during processing, together with an error message.

If one wishes to display this information for debugging purposes (perhaps a .screen-file loads without an error, but the resulting macro bindings are not what one expects), then one can put a line containing the keyword #debug in a .screen- or .bindings-file, which will cause the loading of the file to be stopped at that point and the debug output to be printed.

E.g., loading the following file test4.screen

A=1
B=2
#debug
C=3
#opi<test.bob>

results in the following output (assuming test4.screen is located in the folder /opis/):

Loading '/opis/test4.screen'...
  A = 1
  B = 2
  Encountered '#debug'. Processing stops. (/opis/test4.screen)

In particular, neither the binding C=3 nor the statement #opi<test.bob> will be processed when loading test4.screen, since processing stops when encountering the statement #debug.

7 BNF-Style Grammars for .screen- and .bindings Files

A well-formed .screen-file must contain a valid instance of in the grammar below, while a valid .bindings-file must contain a valid instance of according to the grammar below.

The grammar is not entirely formal, and it is also incomplete:

• #debug is not part of the grammar
• Comments starting with // are not part of the grammar.
• <file-name> is left unspecified and informal in the grammar. It includes strings such as test.screen and subdirectory/shared.bindings.
• Whitespace is left unspecified in the grammar, to make the grammar more readable. Whitespace is generally allowed between tokens.

Some notes on the notation used for the grammar:

• The non-terminal <empty> refers to the empty string "".
• The non-terminal <newline> refers to a newline, which is usually
  either \n or \r\n.

Finally, it is unlikely that the grammar is error-free even for the fragment it covers, but it should provide a good starting point for understanding the proposed structure of .screen- and .bindings-files.

<bindings-file>      ::= <incl-decls> <macro-defs>
<screen-file>        ::= <incl-decls> <macro-defs> <app-spec>
<incl-decls>         ::= <empty>
                       | #include< <file-name> > <newline> <incl-decls>
<macro-defs>         ::= <empty>
                       | <macro-name> = <macro-binding> <newline> <macro-defs>
<macro-name>         ::= <alphabetic-letter> <rest-of-macro-name>
<rest-of-macro-name> ::= <empty>
                       | <alphabetic-letter> <rest-of-macro-name>
                       | <numeric-letter> <rest-of-macro-name>
                       | _ <rest-of-macro-name>
<alphabetic-letter>  ::= A | B | C | ... | X | Y | Z
                       | a | b | c | ... | x | y | z
<numeric-letter>     ::= 0 | 1 | 2 | 3 | 4
                       | 5 | 6 | 7 | 8 | 9
<macro-binding>      ::= <empty>
                       | <characters> <macro-binding>
                       | $( <macro-name> ) <macro-binding>
<app-spec>           ::= #opi< <file-name> >