built-in predicate

# `create_object/4`

## Description

    create_object(Identifier, Relations, Directives, Clauses)

Creates a new, dynamic object. The word object is used here as a generic term. This predicate can be used to create new prototypes, instances, and classes. This predicate is often used as a primitive to implement high-level object creation methods.

Note that, when opting for runtime generated object identifiers, it’s possible to run out of identifiers when using a backend Prolog compiler with bounded integer support. The portable solution, when creating a large number of dynamic objects in long-running applications, is to recycle, whenever possible, the identifiers.

When creating a new dynamic parametric object, access to the object parameters must use the parameter/2 built-in execution context method.

Declared predicates (using scope clauses in the `Directives` argument) are implicitly declared also as dynamic.

When using Logtalk multi-threading features, predicates calling this built-in predicate may need to be declared synchronized in order to avoid race conditions.

## Modes and number of proofs

    create_object(?object_identifier, @list(object_relation), @list(object_directive), @list(clause)) - one

## Errors

`Relations`, `Directives`, or `Clauses` is a variable:
`instantiation_error`
`Identifier` is neither a variable nor a valid object identifier:
`type_error(object_identifier, Identifier)`
`Identifier` is already in use:
`permission_error(modify, category, Identifier)`
`permission_error(modify, object, Identifier)`
`permission_error(modify, protocol, Identifier)`
`Relations` is neither a variable nor a proper list:
`type_error(list, Relations)`
Repeated entity relation clause:
`permission_error(repeat, entity_relation, implements/1)`
`permission_error(repeat, entity_relation, imports/1)`
`permission_error(repeat, entity_relation, extends/1)`
`permission_error(repeat, entity_relation, instantiates/1)`
`permission_error(repeat, entity_relation, specializes/1)`
`Directives` is neither a variable nor a proper list:
`type_error(list, Directives)`
`Clauses` is neither a variable nor a proper list:
`type_error(list, Clauses)`

## Examples

    % create a stand-alone object (a prototype):
    | ?- create_object(
             translator,
             [],
             [public(int/2)],
             [int(0, zero)]
         ).

    % create a prototype derived from a parent prototype:
    | ?- create_object(
             mickey,
             [extends(mouse)],
             [public(alias/1)],
             [alias(mortimer)]
         ).

    % create a class instance:
    | ?- create_object(
             p1,
             [instantiates(person)],
             [],
             [name('Paulo Moura'), age(42)]
         ).

    % create a subclass:
    | ?- create_object(
             hovercraft,
             [specializes(vehicle)],
             [public([propeller/2, fan/2])],
             []
         ).

    % create an object with an initialization goal:
    | ?- create_object(
             runner,
             [instantiates(runners)],
             [initialization(::start)],
             [length(22), time(60)]
         ).

    % create an object supporting dynamic predicate declarations:
    | ?- create_object(
             database,
             [],
             [set_logtalk_flag(dynamic_declarations, allow)],
             []
         ).

See also

abolish_object/1, current_object/1, object_property/2, extends_object/2-3, instantiates_class/2-3, specializes_class/2-3, complements_object/2