|
As previously shown in several examples, a Software Entity,
or entity file, or simply entity, is a textual file
consisting of a fixed sequence of blocks, called sections, that
fully define the different
aspects of a Software Entity, namely:
- Its core characteristics: identity, description, and fields (section CORE);
- Further definitions of its fields' characteristics (section DEFS);
- Its persistent representation(s) within a database (section DB);
- Its in-memory representation(s) when the entity is active within the logic of the software system that it belongs to (section LOGIC);
- Its usage interface(s) when a human user or another software system is interacting with the entity (section UI);
- Its peculiarities that require some adjusting with respect to the system-wide project conventions (section ADJUST).
Section CORE is not explicitly named in the entity file, as explained later in the document.
Each section including CORE, but with the exception
of DEFS and ADJUST, corresponds to a mold group of the same name
within the set of molds used by the SoProTech project.
In fact, the contents of each entity file section instruct
the Sisendel translator on how
it should apply the molds corresponding to that section
when processing the entity file itself.
Mold group DOC does not have an entity section associated
with it: the rationale for this is that generatable DOC
files should actually document
and describe files generated according to the requirements
specified in the other sections.
As previously discussed,
each entity defines a new Sisendel type that can be embedded, or referred
to, by any other entity, independently of its location in the
project tree.
The syntax of Sisendel is rather simple, as
Sisendel is a line-oriented
description language. All important syntax conventions of
entity files are listed in the following table.
Table 2 - Syntax conventions of entity files
|
Syntax convention
|
Description
|
|
Entity filename
|
An entity file name must be (on case-sensitive file-systems) a lowercase string of alphanumeric characters without blanks, possibly containing underscores "_", and bearing the suffix ".ef".
|
|
Physical line
|
A physical line is a line of text within an entity file.
|
|
Logical line
|
A logical line is either one physical line or the concatenation of two or more contiguous physical lines whose last character (except for the last physical line) is the logical line break.
|
|
Logical line break
|
A logical line can be split across multiple physical lines using a backslash "\".
|
|
Identifiers
|
All identifiers within an entity file (extended entity id, field id's, collection id's, etc.) must be written in lowercase, and may contain underscores, for example like in customer_account. Their translation to more appropriate, language-dependent identifiers, such as CustomerAccount or CUSTOMER_ACCOUNT, takes place within the corresponding molds.
|
|
Comment lines
|
Comments are lines starting with a sharp sign "#". Contents of comments is carried over by Sisendel from the entity files and can be used within molds to print it out in the generated files.
|
|
Labels
|
Several Sisendel language items, such as entity id, fields, enumeration values, must be associated with a textual label: these labels, delimited by double quotes ", may contain any (readable) character. A mechanism for using double quotes within labels is also provided.
|
|
Section separators
|
An entity file consists of the following fixed sequence of sections: CORE, DEFS, DB, LOGIC, UI, ADJUST. The beginning of each section, except for CORE, is marked by the section id in upper case, optionally preceded by a sequence of dashes "-". Section CORE beginning is implicitly marked by the beginning of the entity file.
|
|
Field indexes
|
Each field within an entity file is identified by means of a one-character alphabetical index, which is used from within the entity collections to refer to the field itself.
|
The syntax rules for sections DB, LOGIC and UI,
are very simple: these sections may only contain ordered
lists of entity fields, called collections. Each collection
consists of two or more logical lines: the first line
specifies an identifier for the collection, and the following
line, or lines, list the indexes of zero, one or more data fields.
A collection must contain the index of at least one data field.
The order and relative positions of the data fields
are important: collections are sequentially processed by the
SoProMach[tm] - the Sisendel translator - when it applies the different
section molds, from left to right and from top to bottom.
Moreover, the row and column position
of each field within the collection is translated to
a set of (x, y) coordinates, which can be used in the molds
to exactly define the position of the implementation of the
various fields
within the resulting generated file. This feature of Sisendel
is particularly useful when designing a graphical user interface
(GUI) in the UI section, as already shown in several HTML
examples earlier in this document.
Table 3 - Collection definition syntax
|
Language item
|
Description
|
Example
|
|
identifier:
|
Identifier of the collection being defined. The identifier must appear alone on the source line.
|
table:
|
|
collection members
|
One or more lines, each containing zero, one or more field indexes.
|
b a c g
|
Collections in Sisendel are conventionally referred to by their
relative or absolute collection paths: a relative
collection path is a string of the form
section.collection
such as DB.table,
whereas an absolute collection path is a string of the form
entity.section.collection
such as employee.DB.table.
The following code example, entity "employee.ef",
defines two collections in each
one of the DB, LOGIC and UI sections.
|
Code Example 9 - Collections in Sisendel
|
Sisendel implicitly defines one collection for
section CORE, namely CORE.employee (also referred to
as CORE.entity),
which consists of all data fields in their definition order,
in this example from person to empl_id.
Beyond that, this entity explicitly defines six collections,
described in the following table.
Table 4 - Collections in employee
|
Identifier
|
Defined on lines
|
Members
|
Description
|
|
DB.table
|
22-23
|
empl_id
person
info
dept
position
salary
|
Database table columns
|
|
DB.pkey
|
24-25
|
empl_id
|
Database table primary key
|
|
LOGIC.class
|
27-28
|
empl_id
info
dept
position
salary
|
Object-oriented class members
|
|
LOGIC.parent
|
29-30
|
person
|
Object-oriented parent class
|
|
UI.full_view
|
32-38
|
empl_id
person
dept
position
salary
info
|
User-interface edit/view form
|
|
UI.compact_view
|
39-40
|
empl_id
person
position
|
User-interface reference view
|
|
|
|
Source code - File "company/employee.ef"
|
1 employee "Employee"
2 | An employee, some related information, and the department s/he works in
3
4 person person "Person"
5 person_info info "Pers. info"
6 link department dept "Department"
7 enum position "Position"
8 float salary "Salary ($)"
9 unique_id empl_id "Employee id."
10
11 ----------------------- DEFS
12 salary:
13 0/1000000
14 position:
15 president "President"
16 vice_president "Vice-president"
17 manager "Manager"
18 admin "Admin"
19 sales_rep "Sales rep."
20 engineer "Engineer"
21 ----------------------- DB
22 table:
23 empl_id, person, info, dept, position, salary
24 pkey:
25 empl_id
26 ----------------------- LOGIC
27 class:
28 empl_id, info, dept, position, salary
29 parent:
30 person
31 ----------------------- UI
32 full_view:
33 empl_id
34 person
35 dept
36 position
37 salary
38 info
39
40 compact_view:
41 empl_id, person, position
42 ----------------------- ADJUST
43 DB.table.create = "true"
|
|
The paragraphs that later in this document describe
sections DB, LOGIC, and UI, contain
the generated files resulting from applying the SoProMach[tm] to
entity employee using a small set of sample molds.
The generated files demonstrate how flexibly the concept of Sisendel collection
can be adapted to language-specific constructs, ranging from
class inheritance in Java[tm], C#, or C++, to primary key constraints in SQL, to
form layout design in HTML, and more.
[Previous chapter]
[Next chapter]
[Back to top]
|
