Somusar/Sisendel[tm]

Reference Guide

Francesco Aliverti-Piuri

Copyright © 2003-2012 Somusar

Updated on: January 2, 2004

      
      
      
      
      
      
      
      
      
      
      
      
      
      

Copyright © 2003-2012 so.mus.ar. s.a.s.
Via Sangallo 30 - 20133 Milan - Italy
All rights reserved.

Unix is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

Linux is a registered trademark of Linus Torvalds in the United States and other countries.

Sun, Sun Microsystems, the Sun logo, Solaris, Java, and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

Symbian and all Symbian-based marks and logos are trademarks of Symbian Software Limited.

Apple and Mac OS are registered trademarks of Apple Computer, Inc. in the United States and other countries.

Intel is a registered trademark of Intel Corporation in the United States and other countries.

PowerPC and CICS are registered trademarks of International Business Machines Corporation in the United States and other countries.

Microsoft, Windows, Visual Basic are either trademarks or registered trademarks of Microsoft Corp. in the United States and/or other countries.

Oracle is a registered trademark, and PL/SQL is a trademark of Oracle Corporation.

SAP and ABAP/4 are registered trademarks of SAP AG in Germany and several other countries.

PostScript is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries.

So.mus.ar, the Somusar logo, Somusar/Software Production Technique, Somusar/Software Production Machine, Somusar/Sisendel, Somusar/Tefigel, Somusar/SoProTech, Somusar/SoProMach, Somusar/Software Entity, Somusar/Software Mold, Somusar/Software Mold Kit, Somusar/Software Mold Building, Somusar/Code Generator Building, Somusar/Generator Building, and Somusar/File Generation Scheme are trademarks of so.mus.ar. s.a.s. in Italy, in the European Union, in the United States of America and other countries.

Other trademarks or service marks referenced herein are property of their respective owners.


Contents
Chapter 1 - Introduction
1.1 - Syntax Notation
Chapter 2 - Entity Files
2.1 - Purpose
2.2 - Usage
2.3 - Description
Chapter 3 - Comment Lines
3.1 - Purpose
3.2 - Usage
3.3 - Description
Chapter 4 - Section CORE
4.1 - Purpose
4.2 - Usage
4.3 - Description
Chapter 5 - Entity Identifier
5.1 - Purpose
5.2 - Usage
5.3 - Description
Chapter 6 - Field List
6.1 - Purpose
6.2 - Usage
6.3 - Description
Chapter 7 - Basic Types
7.1 - Purpose
7.2 - Usage
7.3 - Description
Chapter 8 - User Types
8.1 - Purpose
8.2 - Usage
8.3 - Description
Chapter 9 - Section DEFS
9.1 - Purpose
9.2 - Usage
9.3 - Description
9.3.1 - Range Definition
9.3.2 - Enumeration Definition
9.3.3 - Function Definition
Chapter 10 - Section DB
10.1 - Purpose
10.2 - Usage
10.3 - Description
Chapter 11 - Section LOGIC
11.1 - Purpose
11.2 - Usage
11.3 - Description
Chapter 12 - Section UI
12.1 - Purpose
12.2 - Usage
12.3 - Description
Chapter 13 - Section ADJUST
13.1 - Purpose
13.2 - Usage
13.3 - Description
Chapter 14 - Further Reading

Tables
Table 1 - Basic types in Sisendel

Chapter 1 - Introduction

This document defines and describes the syntax and semantics of the Somusar/Sisendel[tm] language. Each chapter defines purpose and usage of a set of Somusar/Sisendel[tm] constructs, and describes them concisely.

1.1 - Syntax Notation

In the syntax convention used in this document literal words and characters are indicated by text in bold fixed-font type, as in process. Non-terminal symbols are indicated by text between < and > in italic type, as in <this-is-a-symbol> (when defined) or as in <this-is-a-symbol> (when referred to).

Chapter 2 - Entity Files

2.1 - Purpose

Define all internal structural components and all layer-dependent features of a Somusar/Software Entity[tm].

2.2 - Usage

Entity files are text files with a name ending in ".ef".
An <entity-reference> is defined as the base name of an entity file, without any leading file path specifier and without the trailing suffix ".ef". User-defined Sisendel types are by definition <entity-reference>'s.
An entity file consists of a sequence of <logical-line> blocks, called <section>'s, structured as follows:

   <core-section>
   <definitions-section>
   <database-section>
   <logic-section>
   <usage-interface-section>
   <adjusting-section>

2.3 - Description

A <logical-line> consists of one or more physical lines of text; a backslash \ as the last character of a physical line indicates that the logical line continues on the next physical line.

Four types of <logical-line> are defined:

  1. Empty lines;

  2. Blank lines;

  3. Comment lines;

  4. Content lines.

Blank lines are lines containing only white spaces (blank, tab).
Comment lines are defined in the next chapter.
Content lines are lines structured according to the Sisendel syntax definitions described by this guide.

Empty lines, blank lines, and comment lines can be freely intermixed with content lines.

As described later in the guide, an <entity-reference> can be used as a new Sisendel user type within other entity files.

Chapter 3 - Comment Lines

3.1 - Purpose

Describe in textual form the characteristics of an entity, as defined by content lines.

3.2 - Usage

   | comment text
or
   # comment text

3.3 - Description

Comment lines are logical lines whose first character is a vertical bar (pipe) | or a sharp sign #. Unlike comments in most computer languages, Sisendel comments are not ignored: the comment text is passed on by the Sisendel translator to the molding stage of the Somusar/Software Production Technique[tm], to enable the embedding of the comment text in the resulting software files.

Chapter 4 - Section CORE

4.1 - Purpose

Provide all core characteristics of a Software Entity.

4.2 - Usage

A <core-section> is defined as follows:

   <entity-id>
   <field-list>

4.3 - Description

The core characteristics of a Software Entity are its identification block <entity-id> and the complete list of its data and function fields <field-list>.

All other sections of an entity file are described and defined based upon the field list of section CORE.

Chapter 5 - Entity Identifier

5.1 - Purpose

Provide an identification block for a Software Entity, including an identifier, a description label, and an optional description comment.

5.2 - Usage

An <entity-id> is defined as follows:

   <identifier> <label>
   <entity-comment>

5.3 - Description

An <identifier> in Sisendel consists of a string of characters containing lower-case letters, decimal digits, and underscores _. The first character of an identifier must be a lower-case character.

A <label> in Sisendel is a string of characters enclosed between double quotes ". Labels may contain any character, including white spaces (blank and tab), except double quotes.

The optional <entity-comment> is a comment possibly containing a textual description of the main features of the Software Entity, such as purpose, function, etc.

Note:

Conversion of Sisendel lower-case identifiers to upper-case or mixed-case identifiers, traditionally considered more appropriate for most computer languages, depends on the computer language of the software files that constitute the target of the Somusar/Software Production Technique[tm]; therefore, such conversion is submitted by Sisendel to the molding stage of the SoProTech[tm].

   
   

Chapter 6 - Field List

6.1 - Purpose

List all data and function fields of a Software Entity.

6.2 - Usage

A <field-list> is a sequence of one or more field descriptors structured as follows:

   <field-definition>
   <field-comment>
A <field-definition> is a logical line structured as follows:
   <type> <field-identifier><optional-cardinality> <label>

6.3 - Description

The field list of a Software Entity summarizes all data and function fields that concur to build the layer-specific facets of the entity.

A <type> declaration can be either a <basic-type> declaration or a <user-type> declaration, as described in the following chapters.

The <field-identifier> and <label>, as well as the <field-comment>, obey the same rules and serve the same purpose described earlier in this guide for entity <identifier>'s, labels and comments respectively.

The <optional-cardinality>, if present, specifies that the field is an array of items, each of type <type>, whose size in terms of number of items is defined as follows:

   [<size-specifier>]
where <size-specifier> must be one of the following:
  1. A positive integer decimal number, specifying the number of items in the array;

  2. The word dyn, specifying that the array size is dynamic.

Chapter 7 - Basic Types

7.1 - Purpose

Provide basic building blocks to construct new, more complex user types in the form of Software Entities stored in entity files.

7.2 - Usage

A <basic-type> can be specified in one of two ways:

  1. <plain-basic-type>

  2. <imported-type>

An <imported-type> is defined as follows:
   <entity-reference>.<field-identifier>

7.3 - Description

A <plain-basic-type> is one of the type identifiers defined in the following table.

Table 1 - Basic types in Sisendel

Type id Description Notes
bool Boolean value -
enum Enumerated value Enumeration values must be defined in section DEFS
float Floating point number Lower and upper bound of validity range may optionally be defined in section DEFS
function Computational object Function parameters and return value(s) must be defined in section DEFS
int8 Signed 8-bit integer number -
int16 Signed 16-bit integer number -
int32 Signed 32-bit integer number -
int64 Signed 64-bit integer number -
range Range of integer values Lower and upper bound of range must be defined in section DEFS
string String of characters Length of string must be specified, may be dynamic
thing Generic object Can be used as a placeholder for complex or multimedia objects, such as documents, sound files, and videoclips (or smell, taste and tactile files in the future).
time Time value -
uint8 Unsigned 8-bit integer number -
uint16 Unsigned 16-bit integer number -
uint32 Unsigned 32-bit integer number -
uint64 Unsigned 64-bit integer number -
unique_id Unique identifier -

Fields whose type is an <imported-type> allow to centralize and share common field type definitions across two or more Software Entities.

The field identifier of the <imported-type> is the <field-identifier> of a field defined by the entity referred to by the <entity-reference>.

An <optional-cardinality> may be specified for fields of any basic type, except for fields of type function.

Chapter 8 - User Types

8.1 - Purpose

Provide a mechanism to:

8.2 - Usage

A <user-type> in a <field-definition> is syntactically defined according to one of the three rules stated below. To embed the structure of another Software Entity:

   <entity-reference>
To define a simple (one-to-one) relationship with another Software Entity:
   link <entity-reference>
To define a multiple (one-to-many) relationship with another Software Entity:
   list <entity-reference>

8.3 - Description

The syntactic mechanism provided by Sisendel to create different types of logical connections between Software Entities does not impose any particular predefined semantic constraint on the type of connection applicable by the software production target of the SoProTech[tm]. Actual mapping of Software Entity connections onto connections in the target software language, or languages, significantly depends on the target software language, and is for this reason submitted by Sisendel to the molding stage of the SoProTech.

Chapter 9 - Section DEFS

9.1 - Purpose

Define specific characteristics of entity fields, according to their <type>.

9.2 - Usage

A <definitions-section> is structured as follows:

   <optional-section-delimiter>DEFS
   <field-specifier-list>
The <optional-section-delimiter> is a string of blanks, tabs, and dashes -, and can be used to improve readability of entity files.

The <field-specifier-list> consists of zero or more <field-specifier>'s, each defined as follows:

   <field-identifier>:
   <specifier-definition>
A <specifier-definition> can be one of the following:

9.3 - Description

A <specifier-definition> depends on the type of the entity field that it refers to by means of the <field-identifier> in the <field-specifier>.

9.3.1 - Range Definition

A <range-definition> must be specified for a field of type range and may optionally be specified for a field of type float, according to the following rule:

   <lower-bound>/<upper-bound>
Numeric values for <lower-bound> and <upper-bound> must be expressed in decimal notation, can be positive or negative values, and must be integer if they refer to a field of type range. The value of <lower-bound> must be smaller than the value of <upper-bound>.

9.3.2 - Enumeration Definition

An <enumeration-definition> must be specified for a field of type enum, and consists of one or more logical lines, each defining one <enumeration-value> as follows:

   <identifier> <optional-value-specifier> <label>
An <optional-value-specifier> can be either an integer number or a single character enclosed in single quotes '.
If the <optional-value-specifier> is omitted, Sisendel automatically defines incremental positive numeric enumeration values starting from zero.
An <enumeration-definition> must contain <enumeration-value>'s of only one type, that is, all <enumeration-value>'s must either have, or not have, <optional-value-specifier>'s.

9.3.3 - Function Definition

A <function-definition> must be specified for a field of type function, and consists of one or more logical lines, each defining one <function-signature> as follows:

   <parameter-list> -> <return-value-type>
The <parameter-list> consists of a comma-separated list of one or more <field-identifier>'s; alternatively, a void parameter list can be specified using the digit 0 (zero).
The <return-value-type> consists of exactly one <field-identifier>; alternatively, a void return value can be specified using the digit 0 (zero).
At least one <function-signature> must be defined for each entity field of type function; it is possible to define more than one <function-signature> per function, independent of one another.

Chapter 10 - Section DB

10.1 - Purpose

Design the database facet of a Software Entity.

10.2 - Usage

A <database-section> is structured as follows:

   <optional-section-delimiter>DB
   <field-collection-list>
The <field-collection-list> consists of zero or more <collection-specifier>'s, each defined as follows:
   <collection-id>:
   <collection-members>

10.3 - Description

A <collection-id> is a user-defined <identifier> associated with the fields collection.

The <collection-members> must be represented by a list of one or more <field-identifier>'s of entity fields, optionally separated by commas.

In abstract terms, collections of fields are the basic syntactic construct provided by Sisendel to define which group, or groups, of entity fields represent the facet of a Software Entity with respect to a given software system layer: database tables or primary or foreign keys, logic object-oriented classes, usage interfaces - such as screen forms or messaging interfaces - can all be defined in Sisendel as collections of fields.

The actual production of each facet depends, among other things, on the target software language, or languages, used for each software system layer; therefore, that production process is submitted by Sisendel to the molding stage of the SoProTech[tm].

The relative textual position of <collection-members> in terms of row and column offset with respect to the <collection-id> provide a simple mechanism to define - when applicable - the layout of an entity facet. The row-column position is recorded by Sisendel and can be used in the molding stage of the SoProTech. This feature can be particularly useful for the usage interface layer.

Chapter 11 - Section LOGIC

11.1 - Purpose

Design the logic facet of a Software Entity.

11.2 - Usage

A <logic-section> is structured as follows:

   <optional-section-delimiter>LOGIC
   <field-collection-list>

11.3 - Description

The same description provided for section DB applies also for section LOGIC.

Chapter 12 - Section UI

12.1 - Purpose

Design the usage interface facet of a Software Entity.

12.2 - Usage

A <usage-interface-section> is structured as follows:

   <optional-section-delimiter>UI
   <field-collection-list>

12.3 - Description

The same description provided for section DB applies also for section UI.

Chapter 13 - Section ADJUST

13.1 - Purpose

Define adjusting parameters to fine-tune the production of software derived from a Software Entity.

13.2 - Usage

An <adjusting-section> is structured as follows:

   <optional-section-delimiter>ADJUST
   <adjusting-list>
The <adjusting-list> consists of zero or more <adjusting-specifier>'s, each defined as follows:
   <adjusting-parameter> = <adjusting-value>

13.3 - Description

An <adjusting-value> can be either a numeric value or a string of characters enclosed in double quotes ".

An <adjusting-parameter> specifies an <adjusting-value> at one of three possible levels, according to the following rules:

  1. Section level adjusting parameter:
    <section-id>.<parameter-id>

  2. Collection level adjusting parameter:
    <section-id>.<collection-id>.<parameter-id>

  3. Field level adjusting parameter:
    <section-id>.<collection-id>.<field-identifier>.<parameter-id>

The <section-id> must be one of the following:
   CORE
   DB
   LOGIC
   UI
The collection identified by <collection-id> must be defined within the section referred to by <section-id>. For section CORE the only valid <collection-id> is the term entity.

The entity field referred to by its <field-identifier> must be a member of the collection referred to by <collection-id>.

The <parameter-id> can be any valid <identifier>.

Adjusting parameters provide a flexible tolerance mechanism for the SoProTech[tm]. As Sisendel does not impose any semantics to the name-value association of <adjusting-parameter> and <adjusting-value>, the software production actions related to, and depending by, the value of adjusting parameters are totally submitted by Sisendel to the molding stage of the SoProTech.

Chapter 14 - Further Reading

Additional information on the different aspects of the Somusar/Software Production Technique[tm] can be found in the other volumes of the Somusar/SoProTech[tm] Booklet Series, listed below.

Vol. I - somusar/SoProTech: An Introduction

An introduction to the Somusar/Software Production Technique[tm], a new, fast, and efficient technology to make high-quality multifacet software.

Vol. II - somusar/SoProTech: A Sample Project

Description of a sample project, serving as a proof-of-concept for the Somusar/Software Production Technique[tm], and the Somusar/Sisendel[tm] and Somusar/Tefigel[tm] languages. A few code examples are provided and demonstrate the practical applicability of the technique.

Vol. III - somusar/Sisendel: A Tutorial Introduction

A tutorial introduction to Somusar/Sisendel[tm], describing all features of the simple software entity design language. Several code examples practically demonstrate the conciseness and flexibility of the language.

Vol. IV - somusar/Tefigel: A Tutorial Introduction

An introduction to the syntax, semantics, and usage of Somusar/Tefigel[tm], including a vast set of code examples, illustrating the powerful features of the text file generation language.

Vol. VI - somusar/Tefigel: Reference Guide

Tefigel reference guide: official definition of syntax and semantics of the Somusar/Tefigel[tm] language.

Vol. VII - somusar/SoProMach: User's Guide

The Somusar/Software Production Machine[tm] User's Guide. How to install and operate SoProMach.

Vol. VIII - somusar/tjpp: User's Guide

The Somusar/tjpp[tm] User's Guide. How to install and operate the Java[tm] preprocessor.

Vol. IX - Code Generation Somusar Style

Proof-of-concept samples of what you can generate with Somusar/SoProMach[tm].