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.
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
Alphabetical index of the field, ranging from "a" to "z", followed by a right parenthesis ")"
Sisendel type of the field, which may consist of one or more words, depending on whether it is a basic or user type
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")
Human-readable descriptive field label
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
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
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
4 string long_string "Long string"
5 string mid_string "Mid string"
6 string short_string "Short string"
7 string very_long_string "Very long string"
8 string password "Password"
9 string status "Status"
10 string id "Identifier"
11 string user_id "User id."
12 string name "Name"
13 string telephone "Tel. number"
14 string email "Email address"
15 string description "Short description"
16 string ssn "Social security number"
17 string pathname "Pathname"
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.
[Back to top]