somusar/Sisendel: A Tutorial Introduction

We Generate Your Software.

Products

Services

Company

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

Contents
1. Introduction
2. Sisendel Software Entities
3. Sisendel Basic Types
4. Sisendel User Types
5. Contents of an Entity File
6. Section `CORE`
6.1	Entity Identifier
6.2	Entity Fields
6.3	Unique Collection of `CORE`
7. Section `DEFS`
8. Section `DB`
9. Section `LOGIC`
10. Section `UI`
11. Implicit Section `DOC`
12. Section `ADJUST`
13. Further Reading

Chapter 6 - Section `CORE`

As explained earlier in the document, section CORE lists all of the main characteristics (identity and fields) of a Software Entity.

Each entity is uniquely identified within a SoProTech project by means of its filename, all in lower case and without the suffix ".ef", independently of its relative position within the project tree. This filename-id is used from within other entity files when referring to the entity, such as in Sisendel link or list relationships, parent-child class relationships, or plain embedding of entities.

An additional extended entity identifier is provided as the first non-comment line of an entity file, along with a string label. This extended id allows entity designers to use compact file names as short entity identifiers, such as "dept.ef", and more self-explicative names as extended entity identifiers, such as department. It is then up to the project team conventions - implemented by the appropriate molds - to decide whether to use the latter, or the former, or both.

The entity string label associated with the entity identifier should be used whenever possible in the molds, typically in comments within generated source code files, or as a label on user interfaces.

Finally, any comment between the entity identifier and the first field is considered by Sisendel as an entity description, which can also be referred to from the molds and copied into the corresponding generated files.

6.2 - Entity Fields top

The structure of an entity is defined and described by means of its members, called fields. Fields are logical lines structured as described in the following table.

Table 5 - Entity fields syntax

Language item Description Example

index) Alphabetical index of the field, ranging from "a" to "z", followed by a right parenthesis ")" a)

type Sisendel type of the field, which may consist of one or more words, depending on whether it is a basic or user type float

identifier Field identifier, possibly followed by an array cardinality in square brackets. The optional cardinality can be constant (an integer number) or dynamic (the string "dyn") price

label Human-readable descriptive field label "Item price"

One or more comment lines may follow each field definition, and, if present, they are considered by Sisendel as a field description, in exactly the same way as for the entity description discussed before.

The field index serves as a shortcut to the field from within the other sections, in particular from the various collections, and - depending on the field type - from the DEFS section in case further details are required to completely define the field (such as function parameters and return value).

The field identifier and label play for the entity field exactly the same role played for the entity by the entity identifier and label: the field identifier should be used in the molds to generate the language-appropriate identifier at molding time.

The following two code examples show:

A fragment of entity "project.ef", containing all project fields;
The library entity "strings.ef".

Code Example 10 - Fields of "project.ef"

Lines 1-3 define three fields in terms of fields whose definition is imported from library entity strings. Lines 6 shows an example of field description comment, that can be used in molds to carry it over into the generated files. Lines 4, 7, 8 and 9 define fields as references to other entities: in this entity file it is assumed that somewhere in either the project or library tree there are three entity files respectively called "customer.ef", "employee.ef", and "department.ef".

Source code - File "proj_fields"

    1      strings.name            proj_name       "Project name"
    2      strings.id              proj_id         "Project id."
    3      strings.description     descr           "Description"
    4      link customer           customer        "Customer"
    5      float                   budget          "Budget (K$)"
    6      | Project budget unit is 1,000 dollars
    7      list employee           team_members    "Team members"
    8      link employee           manager         "Proj. manager"
    9      link department         department      "Department"
   10      bool                    internal        "Internal"
   11      thing                   plan            "Proj. plan"
   12      function                cur_status      "Current proj. status"
   13      enum                    status          "Proj. status"

Code Example 11 - Library entity "strings.ef"

This entity defines a set of string identifiers that should be standard across one or more projects involving one or more development teams. This approach can ensure consistency for example across all database tables, or middleware messages, or user interfaces, that make use of such common data items as user_id or email. It should be noted that:

strings is an abstract entity, as it defines no collections at all, apart from the list of CORE fields: strings has neither a database table, nor a logic class, nor a usage interface defined for it;

Each field has a constant cardinality, or length, as all fields are strings; for example on line 4 long_string has a cardinality of 80.

Source code - File "library/strings.ef"

    1      strings "Project-wide strings definitions"
    2      | Various types of strings, standardized across the project
    3      
    4      string  long_string[80]         "Long string"
    5      string  mid_string[40]          "Mid string"
    6      string  short_string[20]        "Short string"
    7      string  very_long_string[255]   "Very long string"
    8      string  password[40]            "Password"
    9      string  status[2]               "Status"
   10      string  id[10]                  "Identifier"
   11      string  user_id[80]             "User id."
   12      string  name[40]                "Name"
   13      string  telephone[40]           "Tel. number"
   14      string  email[60]               "Email address"
   15      string  description[200]        "Short description"
   16      string  ssn[40]                 "Social security number"
   17      string  pathname[1024]          "Pathname"
   18      
   19      DEFS
   20      DB
   21      LOGIC
   22      UI
   23      ADJUST

6.3 - Unique Collection of `CORE` top

Unlike sections DB, LOGIC and UI, section CORE does not allow - by syntax rules - to define field collections. The only collection implicitly defined for CORE is a collection with the following characteristics:

The collection identifier is the same as the entity identifier;

The collection contains all data fields of the entity in the same order as they have been defined.

Background theoretical reason for this peculiarity is that the CORE features of a Software Entity should represent the unique and complete identity of the entity itself.

[Previous chapter] [Next chapter] [Back to top]

Chapter 6 - Section CORE

6.1 - Entity Identifier top

6.2 - Entity Fields top

6.3 - Unique Collection of CORE top

Chapter 6 - Section `CORE`

6.3 - Unique Collection of `CORE` top