entity - Dbquity model BETA

Identifiable and retrievable information about something or someone

We declare an entity to capture some information about something or someone that is of interest to the site or library that we are working on.

Unit of storage in the area-rooted site hierarchy

An entity is the smallest possible piece of information that may be stored and later retrieved and updated.

In a Dbquity site, entities are organised in areas that each store their own hierarchy, which is defined by the indentation and order of the entity declarations "under" that area in the .dbquity source file.

The place in this hierarchy, in which the entity is declared, also defines the place, in which its runtime instances will be saved.

In database "lingo", you might say that

• declaring an entity declares both a table and the structure of each record in that table, and
• that the identity property declares the field of the primary key.

Further, the entity declaration also drives the user interface for viewing and updating as well as any future programmatic interface that Dbquity may support.

Declaration

entity <name>
    description: ...
    modelconstraint: <expression>   # evaluated when parsed by the CLI
                                    # and (often) refers property values
    constraint: <expression>        # evaluated at runtime
    <primitive>|<class-name>|<enumeration-name> <name>
    identity: <field-name>
    ...
    ...

or; for an entity that derives from a <base-entity>

entity <name>
    base: <base-entity-name>
    ...

or (in short-hand)

<base-entity-name> <name>
    ...

When declaring an entity, the first line captures the name and potentially the base of the entity, and the following, indented lines are used to further declare the characteristics of the entity using nested fields and these modifiers and properties:

Modifiers

abstract

...

sealed

...

defaulted

...

Properties

base

...

identity

The identity property names the field of the entity that stores its identity. Two different entities cannot share the same identity. This uniquess guarantees that entities can be identified and retrieved later, once they have been saved by Dbquity. If a user creates a new entity of a certain type and gives it the same identity as an already saved entity of the same type, the new entity cannot be saved.

If identity is not declared, each entity will get a unique (within the site) number assigned when it is first saved.

guard

In cases where the uniqueness of the identity is not the only thing required for making it possible to save the entity, an expression for the guard property can be declared to guard the user from accidentally saving ill-defined entities.

Note, that in most (nearly all) cases it is preferable to use constraint rather than guard, because it is a much better experience for a user to be able to save information that can later be corrected, instead of being blocked from saving by too rigourous validation.

constraint

A not-true constraint, will still allow the entity to be saved and retrieved, but the UI will list a warning about the violated constraint, and the function issues() will include that warning.

invariant

...

alias

...

Notes

An entity can not declare static function members, because in expressions, the name of the entity denotes the collection of entity instances defined by that entity or derived.