Type

Use a Type to create typed things.

A typed thing is a thing with predefined properties and/or methods with are defined by a Type. When creating a typed thing, all defined properties of the type are guaranteed to exist with a value matching the type definition.

Definable properties

Each definition can be made optional by adding a question-mark ? to the definition and can be prefixed with additional flags. If a property is made optional, then the value nil is allowed instead of the given type and nil will also be the default if the property is missing.

For example

// Create a new type `User` with an optional property `name`.
set_type('User', {name: 'str?'});

// Create a typed thing of type `User` without a name
unknown = User{};

// ..or explicitly set name to `nil`
user_nil = User{name: nil};

// ..a `str` is also ok
iris = User{name: 'Iris'};

// ..but another type than `str` or `nil` is not allowed
assert(is_err(try(User{name: 0})));

// Return the results
[unknown, user_nil, iris];

Return value in JSON format

[
    {
        "name": null
    },
    {
        "name": null
    },
    {
        "name": "Iris"
    }
]

Prefix flags

All definitions can be pre-fixed with additional flags which are applied when a thing is being wrapped.

Same deep level

Any definable property can be pre-fixed with a & character which is only used after the type is used to wrap and tells to use the same deep level for this property. Although the character is allowed everywhere, it only has effect when the value is or contains thing(s). Only a thing honors deep thus this makes sense.

For example

new_type('User');
set_type('User', {
    name: 'str',
    friend: '&User?'
});

iris = User{
    name: 'Iris',
    friend: User{
        name: 'Cato'
    }
};

iris.wrap();

Return value in JSON format

{
    "friend": {
        "friend": null,
        "name": "Cato"
    },
    "name": "Iris"
}

Named Id

ThingsDB returns the Id of a thing as property #. Thus, as an example you might get a result like this:

set_type('Person', {name: 'str'});
.alice = Person{name: 'Alice'};

Returns with something like:

{
    "#": 123,
    "name": "Alice"
}

If we want something else than #, what we can do is define some property, for example id with the # definition:

set_type('Person', {id: '#', name: 'str'});
.alice = Person{name: 'Alice'};

Returns with something like:

{
    "id": 123,
    "name": "Alice"
}

Restrict items

When using a list '[]' or set '{}' definition, it is also possible to make the list or set restricted to a certain type. In this case only items of the given definition are allowed as members. For example '[int]' requires the members of a list to be integers and '{User}' is a restricted set which only allows things of type User.

Both the list and/or the members can be made optional. For example, this '[str?]?' is a valid declaration. Since a set does not allow for nil values, it is not possible to make members of a set optional.

This is an example using a restricted list:

// Very simple `Note` type
set_type('Note', {
    text: 'str',
    timestamp: 'uint'
});

// Book type with `notes` of type `Note`
set_type('Book', {
    title: 'str',
    notes: '[Note]'
});

// Create a new book
book = Book{
    title: "hitchhiker's guide to the galaxy",
};

// Add a note to the book
book.notes.push(Note{
    text: 'the answer is 42',
    timestamp: int(now())
});

// It *must* be a `Note`, something else is not allowed
assert(is_err(try(book.notes.push({test: 'not a Note'}))));

// Return the book, 2 levels deep to see the note
return book, 2;

Return value in JSON format

{
    "notes": [
        {
            "text": "the answer is 42",
            "timestamp": 1573894579
        }
    ],
    "title": "hitchhiker's guide to the galaxy"
}

Length condition

A length condition may be added to a str or utf8 type definition using the following syntax:

str<min:max:default>

For example:

set_type('Person', {
    name: 'str<1:10>',
    email: 'str<3:50:info@thingsdb.io>'
});

/*
 *  Each Person instance will contain a name with at least 1 character
 *  and at most 10 characters and an email property with a string of at
 *  least 3 and at most 50 characters.
 */

Person{};  // return a Person with default values

Return value in JSON format

{
    "name": "-",
    "email": "info@thingsdb.io"
}

Pattern condition

A pattern condition applies to type str and may be used using the following syntax:

/pattern/i

The i is optional and tells the pattern to be case insensitive. If left away, the pattern will thus be case sensitive.

The definition must be either nillable by adding a ? to the definition or an empty string must match with the given pattern. If this is not the case, then a default value must be given using the syntax below:

/pattern/i<default>

Here is an example using some pattern conditions:

set_type('Words', {
    example1: '/^(e|h|l|o)*$/',
    example2: '/thingsdb/i<ThingsDB>',
    example3: '/^[0-9]{4}[A-Z]{2}$/?',
    example4: '/^[0-9]{4}[A-Z]{2}$/<1234AB>?',
});

/*
 *  example1 - matches an empty string so a default value is not required
 *  example2 - case insensitive and requires a default value
 *  example3 - nillable and thus no default value is required
 *  example4 - exactly the same as example3 but with a default value
 */

Words{};  // return a Person with default values

Return value in JSON format

{
    "example1": "",
    "example2": "ThingsDB",
    "example3": null,
    "example4": "1234AB"
}

Range condition

A range condition may be added to a int or float type definition using the following syntax:

int<min:max:default>

Or

float<min:max:default>

For example:

set_type('Values', {
    a: 'int<10:20>',
    b: 'int<0:10:5>',
    c: 'float<-1:1>',
    d: 'float<0:1:0.5>',
});


Values{};  // return a `Values` instance with default values

Return value in JSON format

{
    "a": 10,
    "b": 5,
    "c": 0,
    "d": 0.5
}

Use condition to set a default value

Both the min and max of a range and length condition are optional. For this reason you can use the “condition” syntax to configure a default value for a property on a Type.

(You may want to combine a default value with a minimum and/or maximum limit and that is fine; This example is just to make it clear that setting a min and/or max value is not required.)

For example:

set_type('TestDefault', {
    f: 'float<::3.14>',
    i: 'int<::42>',
    s: 'str<::ThingsDB>',
});

TestDefault{};  // return a `TestDefault` instance with default values

Return value in JSON format

{
    "f": 3.14,
    "i": 42,
    "s": "ThingsDB"
}

For email, url and tel, you can also set a default value, for example:

set_type('TestDefault', {
    e: 'email<info@thingsdb.io>',
    u: 'url<https://thingsdb.io>',
    t: 'tel<(0031) 6 1279 8880>',
});

TestDefault{};  // return a `TestDefault` instance with default values

Return value in JSON format

{
    "e": "info@thingsdb.io",
    "t": "(0031) 6 1279 8880",
    "u": "https://thingsdb.io"
}

Get instance of a type

The thing(..) function may be used to get an instance of a given Id. This does not guarantee that the thing is truly of the type you expect. Instead of adding a type_assert(..) on the thing, it is also possible to call the type as a function with the Id as it’s first argument.

For example:

// Suppose we have a user_id and want to get the user
user = User(user_id);

Possible errors:

• A lookup_err() will be raised if no thing with the given user_id exists.
• A type_err() will be raised if a thing is found, but the thing is not of the User type,

Methods

A method is a closure attached to a type. Methods are defined when creating a type by attaching a closure instead of a definition. When a method is used on an instance of a type, the first argument will be the instance itself. It is therefore common to name the first argument this.

For example:

set_type('Person', {
    name: 'str',
    age: 'int',
    whoami: |this| `My name is {this.name} and I am {this.age} years old.`
});

.iris = Person{
    name: 'Iris',
    age: 7
};

.iris.whoami();

Return value in JSON format

"My name is Iris and I am 7 years old."

Related functions