[ Term I/O | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# read_exdr(+Stream, -Term)

A term in EXDR-format is read from the input stream Stream and converted to the corresponding ECLiPSe term Term.

Stream
  Integer (stream number) or Atom (symbolic stream name).
Term
  A variable.

## Description

The predicates write_exdr/2 and read_exdr/2 can be used for letting ECLiPSe programs exchange data with the host language in an embedded environment (e.g. Java, Tcl). More generally, they allow exchanging data with agents written in programming languages that define a mapping from EXDR format to the language's data structures.

EXDR defines the abstract data types Integer, Long, Double, String, List, Nil, Struct and Anonymous Variable. Their mapping to ECLiPSe data types is as follows:

            EXDR type       ECLiPSe type        e.g.
            ----------------------------------------------
            Integer         integer             123
            Long            integer             10000000000
            Double          float               12.3
            String          string              "abc"
            List            ./2                 [a,b,c]
            Nil             []/0                []
            Struct          compound or atom    foo(bar,3)
            Anon.Variable   var                 _

Not all ECLiPSe terms have an EXDR representation, e.g. integers longer than 64 bits, rationals, suspensions or attributed variables.

More information about EXDR format, including the specification of the serialised encoding, can be found in the Embedding and Interfacing Manual.

### Modes and Determinism

- read_exdr(+, -) is semidet

### Fail Conditions

Fails when reaching end of file

### Exceptions

(4) instantiation fault
  Stream is not instantiated.
(5) type error
  Stream is not an atom or an integer.
(7) string contains unexpected characters
  EXDR term corrupted.
(190) end of file reached
  End of file (default handler fails)
(192) illegal stream mode
  Stream is not an input stream.
(193) illegal stream specification
  Stream is an illegal stream specification.
(264) not an eclipse object file
  Not EXDR format.
(265) bad eclipse object file version
  Unknown EXDR format version.

## Examples

    Success:
        [eclipse 4]: open(queue(""),update,q),
                     write_exdr(q, foo(12.3,123,["hello",_])),
                     read_exdr(q, Term),
                     close(q).

        Term = foo(12.3, 123, ["hello", _131])
        yes.

    Error:
        read_exdr(S, a(b,c)).    (Error 4).
        read_exdr(input, X).     (Error 192).
        read_exdr(atom, X).      (Error 193).

## See Also

write_exdr / 2, read / 1, read / 2