[ Type Testing | Reference Manual | Alphabetic Index ]

is_handle(?Term, -Kind)

Succeeds if Term is an object handle of kind Kind
Term
Prolog term.
Kind
Atom or variable

Description

Used to test whether Term is an object handle, and of what kind. Handles are references to anonymous ECLiPSe objects or to external data created via the foreign language interfaces. Handles are anonymous and are distinct from from the regular Prolog-style data types (number, atom, compound). They support only a limited number of operations, and are mostly used in relation to ECLiPSe's non-logical features.

The following kinds of object are defined by ECLiPSe itself:

bag
A bag object, as created by bag_create/1.
engine
An engine object, as created by engine_create/2.
record
A record object, as created by record_create/1.
shelf
A shelf object, as created by shelf_create/2,3.
store
A store object, as created by store_create/1.
stream
A stream object, as created by open/3,4, socket/3, etc.
[]
A stale handle, no longer referring to any object, e.g. after handle_close/1, close/1, bag_dissolve/1.

Handles can be also be created by external predicates using the ECLiPSe C or C++ API. The kind of such a handle is determined by the atomic name returned by the user-defined kind() method.

Modes and Determinism

Fail Conditions

Fails if Term is not an external data handle

Examples


    ?- bag_create(B), is_handle(B, Kind).
    B = $&(bag,"371bnb")
    Kind = bag
    Yes (0.00s cpu)

    ?- engine_self(E), is_handle(E, Kind).
    E = $&(engine,"cg51thx4p")
    Kind = engine
    No (0.00s cpu)

    ?- get_stream(output, S), is_handle(S, Kind).
    S = $&(stream,1)
    Kind = stream
    No (0.00s cpu)

    ?- is_handle(42, Kind).
    No (0.00s cpu)

    ?- is_handle(output, Kind).
    No (0.00s cpu)

See Also

is_handle / 1, handle_close / 1, type_of / 2, xget / 3, xset / 3