package atd

A location in the source code.

Exception raised by functions of the atd library and indicating errors.

An annotation, consisting of a sequence of sections. Annot provides utilities for handling annotations.

represents a single annotation within edgy brackets. <"foo" bar baz="123"> in ATD syntax translates to:

("foo", (loc1, [ ("bar", (loc2, None));
                 ("baz", (loc3, Some "123")) ] ))

An annotation field, i.e. a key with an optional value within an annotation.

Contents of an ATD file.

The head of an ATD file is just a list of annotations.

The body of an ATD file is a list of type definitions. Type definitions are implicitely mutually recursive. They can be sorted based on dependencies using Atd.Util.tsort.

There is currently only one kind of module items, that is single type definitions.

A type definition.

List of type variables without the tick.

A type expression is one of the following:

• `Sum: a sum type (within square brackets)
• `Record: a record type (within curly braces)
• `Tuple: a tuple (within parentheses)
• `List: a list type written list with its parameter e.g. int list
• `Option: an option type written option with its parameter e.g. string option
• `Nullable: adds a null value to a type. `Option should be preferred over `Nullable since it makes it possible to distinguish Some None from None.
• `Shared: values for which sharing must be preserved. Such type expressions may not be parametrized. Values may only be shared if the source location of the type expression is the same.
• `Wrap: optional wrapping of a type. For example, a timestamp represented as a string can be wrapped within a proper time type. In that case, the wrapper would parse the timestamp and convert it into the internal representation of its choice. Unwrapping would consist in converting it back to a string.
• `Name: a type name other than list or option, including the predefined types unit, bool, int, float, string and abstract.
• `Tvar: a type variable identifier without the tick

A type name and its arguments

A single variant or an inherit statement. `Inherit statements can be expanded into variants using Atd_inherit or at loading time using the inherit_variant option offered by the Atd.Util functions.

Tuple cell. Note that annotations placed before the type expression are supported and represented here, such as the third cell in (float * float * <ocaml default="0.0"> float).

Different kinds of record fields based on the

• `Required: required field, e.g. id : string
• `Optional: optional field without a default value, e.g. ?name : string option. The ATD type of the field value must be an option type.
• `With_default: optional field with a default value, e.g. ~websites : string list. The default value may be implicit or specified explicitely using annotations. Each target language that cannot omit fields may have to specify the default in its own syntax.

Sample ATD file:

type level = [ Beginner | Advanced | Expert ]

type user = \{
  id : string;

  ?name : string option;
    (* Field may be omitted when no value is set, if permitted
       by the target language. *)

  ~websites : string list;
    (* Implicit default: empty list.
       Field may be omitted if the field value is
       equal to the default value and the
       target language permits it. *)

  ~level <ocaml default="`Beginner"> : level;
    (* Explicit default for `ocaml'.
       For instance there is no `json' annotation because
       the default for undefined `JSON' fields would be to omit them. *)
}

A single record field or an inherit statement. `Inherit statements can be expanded into fields using Atd_inherit or at loading time using the inherit_fields option offered by the Atd.Util functions.

Extract the source location of any type expression.

Replace the location of the given expression. This is a shallow substitution. Sub-expressions are not affected.

Convert a location into a human-readable string such as File "foo.atd", line 123, characters 40-45.

error s is a shorthand for raise (Atd_error s).

error_at loc s raises Atd_error s' where s' is the location followed by s.

Dummy value for predefined constructs that are not associated with a useful source location. Should not show up in error messages.

Return the annotations associated with a type expression. Note that there can be annotations in a variety of places, not just after type expressions.

Replacement of the annotations associated with a type expression. This is a shallow transformation. Sub-expressions are not affected.

Replacement of all annotations occurring in an ATD module.

Iteration and accumulation over each type_expr node within a given type_expr.

Extract all the type names occurring in a type expression under `Name, without duplicates.

• parameter ignorable

  specifies a list of type names to exclude from the result

Test whether a type expression contains type variables (`Tvar).