Home Page   We Generate Your Software.
Products Services Company Technology Demo Contact Site Map Search
Please note: this document is currently under revision.
The information herein contained, while still valid, does not reflect the latest state of the described technology.
The Somusar/SoProTech[tm] Booklet Series
Volume III

"somusar/Sisendel: A Tutorial Introduction"

Printer friendly

1. Introduction
2. Sisendel Software Entities
3. Sisendel Basic Types
4. Sisendel User Types
5. Contents of an Entity File
5.1 Syntax Conventions
5.2 Definition of Collections
6. Section CORE
7. Section DEFS
8. Section DB
9. Section LOGIC
10. Section UI
11. Implicit Section DOC
12. Section ADJUST
13. Further Reading

Chapter 5 - Contents of an Entity File

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.

5.1 - Syntax Conventions        top

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.

5.2 - Definition of Collections        top

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

such as DB.table, whereas an absolute collection path is a string of the form
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
Database table columns
DB.pkey 24-25 empl_id Database table primary key
LOGIC.class 27-28 empl_id
Object-oriented class members
LOGIC.parent 29-30 person Object-oriented parent class
UI.full_view 32-38 empl_id
User-interface edit/view form
UI.compact_view 39-40 empl_id
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
    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."
   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
   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]

http:// www.somusar.com  / doc  / booklets  / sisendel_tut  - Powered by SoProMach
Copyright © 2003-2012 Somusar - Trademarks - Legal - Privacy - Webmaster