    "The Ceylon serialization infrastructure.

     This package provides an API for *serialization libraries* to
     provide their own serialization APIs to client code. It does not
     provide a serialization service itself.

     This API:

     * provides a way to walk the graph of instances added for serialization,
       including those reachable via non-\\\`shared\\\` attributes,
     * copes with shared references and cyclic references in object graphs,
     * prevents access to uninitialized and partially initialized instances
       during deserialization.
       (this includes instances reachable from other instances, transitively).

     The API cannot prevent serialization libraries from obtaining access to
     non-\\\`shared\\\` state of instances (loss of encapsulation is
     an inevitable part of serialization).

     A serialization library will implement some kind of
     serializer and/or deserializer (frequently both) using the facilities
     of this API.

     ## Serializers

     A *serializer* takes one or many Ceylon instances and serialize them
     (and the instances reachable from them) to
     some external representation, usually bytes or text in some specific format.

     A serializer provided by a serialization library:

     * obtains a [[SerializationContext]] by
       calling [[serialization]],
     * uses [[SerializationContext.references]] to find the references that
       an instance holds,
     * proceeds to traverse the graph of instances according to
       library-specific rules

     ## Deserializers

     A *deserializer* constructs a graph of
     Ceylon instances according to some external representation.

     A deserializer provided by a serialization library:

     * obtains a [[DeserializationContext]] by
       calling [[deserialization]]
     * progressively provides information about instances:

         * associates an instance with its
           [[class|DeserializationContext.instance]],
         * associates a member instance with its [[containing instance|DeserializationContext.memberInstance]],
         * associates a referred instance with its [[referring instance and attribute|DeserializationContext.attribute]],
         * associates a referred instance with its [[referring array index|DeserializationContext.element]],
         * associates an instance with a [[given other instance|DeserializationContext.instanceValue]].
           This is useful for instances which refer to singletons
           (on deserialization the singleton value has to be provided, since it
           cannot be instantiated by the serialization API).

     * once the context has complete information about the instance
       and every instance reachable from it
       the instance can be
       [[reconstructed|DeserializationContext.reconstruct]].

     ## Serializability

     *Serializability* is whether or not a particular serialization library can
     serialize a particular instance.

     Instances of classes which are annotated [[serializable]] are able to
     enumerate their state during serialization,
     and initialize their state during deserialization.
     However, that does not imply that every serialization library
     can necessarily serialize instances of every `serializable` class.

     The serializability of an instance can depend on:

     * the class of the instance, and its super classes,
     * the serializability of the outer instance(s), if the object is an
       instance of a member class. ,
     * the serialization library's support for serializing generic classes,
       and member classes,
     * the serialization library's support for serializing anonymous objects
       (such as `true`, `null` or `smaller`),
     * the underlying serialization format the serialization library supports

     The deserializability of an instance can depend on:

     * The runtime availability and compatibility of the class of the instances,
       and its super classes, for each instance in the object graph.
    "
    by ("Gavin", "Tom")
    tagged("Serialization")
    since("1.2.0")
    shared package ceylon.language.serialization;