# Module Pxp_dtd.Entity

    module Entity: sig .. end

Useful properties of entities: The following submodule exports all stable properties of the entity classes. Please use this module, and not `Pxp_entity` to access entities.

Note that the types `entity` and `entity_id` are also exported by `Pxp_types`.

    val get_name : Pxp_entity.entity -> string

Return the name of the entity.

    val get_full_name : Pxp_entity.entity -> string

The full name includes the ID, too (for diagnostics messages)

    val get_encoding : Pxp_entity.entity -> Pxp_core_types.I.rep_encoding

Return the encoding of the internal representation of the entity

    val get_type : Pxp_entity.entity -> [ `External | `Internal | `NDATA ]

Returns the type of the entity.

    val replacement_text : Pxp_entity.entity -> string

Return the replacement text of the entity. Works for both internal and external entities. The replacement text is the "right side" of the entity definition.

    val get_xid : Pxp_entity.entity -> Pxp_core_types.I.ext_id option

Returns the external ID for external and NDATA entities, and None for internal entities

TRAP: The external ID may be a relative SYSTEM ID, and it is not known to which base ID the relative ID must be resolved. So the external ID may be meaningless.

    val get_resolver_id : Pxp_entity.entity -> Pxp_core_types.I.resolver_id option

Returns the resolver ID for external entities, and None for other entities. This is the version as returned by the `active_id` method by the resolver. The resolver ID contains more information than the external ID, for example the base URL relative to which SYSTEM IDs should be interpreted.

    val get_notation : Pxp_entity.entity -> string option

Returns the notation of NDATA entities, and None for the other entity types

    val create_internal_entity : name:string -> value:string -> Pxp_dtd.dtd -> Pxp_entity.entity

Creates an internal entity. The name and the value must be encoded in the same encoding as the DTD. Note that if the entity is to be used as parameter entity, the first and the last characters of the value should be spaces.

    val create_ndata_entity : name:string ->
           xid:Pxp_core_types.I.ext_id ->
           notation:string -> Pxp_dtd.dtd -> Pxp_entity.entity

Creates an NDATA entity. The name and the notation must be encoded in the same encoding as the DTD. The external ID must be encoded as UTF-8 string (like all external IDs).

    val create_external_entity : ?doc_entity:bool ->
           ?system_base:string ->
           name:string ->
           xid:Pxp_core_types.I.ext_id ->
           resolver:Pxp_reader.resolver -> Pxp_dtd.dtd -> Pxp_entity.entity

Creates a reference to an external entity. The name must be encoded in the same encoding as the DTD. The external ID must be encoded as UTF-8 string (like all external IDs).

- `doc_entity`: If true, the entity is a document entity. XML requires some additional restrictions for document entities. The default for the argument is false.
- `system_base`: The base URL if SYSTEM identifiers are passed as `xid`

    val from_external_source : ?doc_entity:bool ->
           name:string -> Pxp_dtd.dtd -> Pxp_dtd.source -> Pxp_entity.entity

Creates an external entity that reads from the passed `Pxp_types.source`

    val entity_id : Pxp_entity.entity -> Pxp_lexer_types.entity_id

Returns the abstract entity ID

    val lookup : Pxp_lexer_types.entity_id -> Pxp_entity.entity

Looks the entity up for an entitiy ID

    val create_entity_id : unit -> Pxp_lexer_types.entity_id

Create a new abstract entity ID. This ID can be used whereever an `entity_id` is expected but no entity is available, except that the back coercion `lookup` is not supported, and will raise `Invalid_argument`.