lib/sax/attributes.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # This file is free software, which comes along with NIT. This software is
   4 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
   5 # without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
   6 # PARTICULAR PURPOSE. You can modify it is you want, provided this header
   7 # is kept unaltered, and a notification of the changes is added.
   8 # You are allowed to redistribute it and sell it, alone or is a part of
   9 # another product.
  10
  11 # Interface for a list of XML attributes.
  12 module sax::attributes
  13
  14 # Interface for a list of XML attributes.
  15 #
  16 # This interface allows access to a list of attributes in
  17 # three different ways:
  18 #
  19 # * by attribute index;
  20 # * by Namespace-qualified name; or
  21 # * by qualified (prefixed) name.
  22 #
  23 # The list will not contain attributes that were declared
  24 # `#IMPLIED` but not specified in the start tag. It will also not
  25 # contain attributes used as Namespace declarations (`xmlns*`) unless
  26 # the `http://xml.org/sax/features/namespace-prefixes`
  27 # feature is set to `true` (it is `false` by default).
  28 # Because SAX2 conforms to the "Namespaces in XML" specification,
  29 # it does not give namespace declaration attributes a namespace URI.
  30 # Some other W3C specifications are in conflict with that, expecting
  31 # these declarations to be in a namespace.
  32 # Handler code may need to resolve that conflict.
  33 #
  34 # If the namespace-prefixes feature (see above) is `false`,
  35 # access by qualified name may not be available; if the
  36 # `http://xml.org/sax/features/namespaces`
  37 # feature is `false`, access by Namespace-qualified names
  38 # may not be available.
  39 #
  40 # The order of attributes in the list is unspecified, and will
  41 # vary from implementation to implementation.
  42 #
  43 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
  44 #
  45 # SEE: `sax::helpers::AttributesImpl`
  46 #
  47 # SEE: `sax::ext::DeclHandler.attribute_decl`
  48 interface Attributes
  49
  50         # Return the number of attributes in the list.
  51         fun length: Int is abstract
  52
  53         # Look up an attribute's Namespace URI by index.
  54         #
  55         # Parameters:
  56         #
  57         # * `index`: attribute index.
  58         #
  59         # Returns:
  60         #
  61         # The Namespace URI, or the empty string if none
  62         # is available, or `null` if the index is out of
  63         # range.
  64         #
  65         # SEE: `length`
  66         fun uri(index: Int): nullable String is abstract
  67
  68         # Look up an attribute's local name by index.
  69         #
  70         # Parameters:
  71         #
  72         # * `index`: attribute index.
  73         #
  74         # Returns:
  75         #
  76         # The local name, or the empty string if Namespace
  77         # processing is not being performed, or `null`
  78         # if the index is out of range.
  79         #
  80         # SEE: `length`
  81         fun local_name(index: Int): nullable String is abstract
  82
  83         # Look up an attribute's XML 1.0 qualified name by index.
  84         #
  85         # Parameters:
  86         #
  87         # * `index`: attribute index.
  88         #
  89         # Returns:
  90         #
  91         # The XML 1.0 qualified name, or the empty string
  92         # if none is available, or `null` if the index
  93         # is out of range.
  94         #
  95         # SEE: `length`
  96         fun qname(index: Int): nullable String is abstract
  97
  98         # Look up an attribute's type by index.
  99         #
 100         # The attribute type is one of the strings `CDATA`, `ID`,
 101         # `IDREF`, `IDREFS`, `NMTOKEN`, `NMTOKENS`, `ENTITY`, `ENTITIES`,
 102         # or `NOTATION` (always in upper case).
 103         #
 104         # If the parser has not read a declaration for the attribute,
 105         # or if the parser does not report attribute types, then it must
 106         # return the value `CDATA` as stated in the XML 1.0 Recommentation
 107         # (clause 3.3.3, "Attribute-Value Normalization").
 108         #
 109         # For an enumerated attribute that is not a notation, the
 110         # parser will report the type as `NMTOKEN`.
 111         #
 112         # Parameters:
 113         #
 114         # * `index: Int`: attribute index.
 115         # * `index: String`: XML 1.0 qualified (prefixed) name.
 116         #
 117         # Returns:
 118         #
 119         # The attribute's type as a string, or `null` if the specified
 120         # attribute is not in the list or if qualified names
 121         # are not available.
 122         #
 123         # SEE: `length`
 124         fun type_of(index: Object): nullable String is abstract
 125
 126         # Look up an attribute's value by index.
 127         #
 128         # If the attribute value is a list of tokens (`IDREFS`,
 129         # `ENTITIES`, or `NMTOKENS`), the tokens will be concatenated
 130         # into a single string with each token separated by a
 131         # single space.
 132         #
 133         # Parameters:
 134         #
 135         # * `index: Int`: attribute index.
 136         # * `index: String`: XML 1.0 qualified (prefixed) name.
 137         #
 138         # Returns:
 139         #
 140         # The attribute's value as a string, or `null` if the specified
 141         # attribute is not in the list or if qualified names
 142         # are not available.
 143         #
 144         # SEE: `length`
 145         fun value_of(index: Object): nullable String is abstract
 146
 147         # Look up the index of an attribute by Namespace name.
 148         #
 149         # Parameters:
 150         #
 151         # * `uri`: Namespace URI, or the empty string if
 152         # the name has no Namespace URI.
 153         # * `local_name`: attribute's local name.
 154         #
 155         # Returns:
 156         #
 157         # The index of the attribute, or -1 if it does not
 158         # appear in the list.
 159         fun index_ns(uri: String, local_name: String): Int is abstract
 160
 161         # Look up the index of an attribute by XML 1.0 qualified name.
 162         #
 163         # Parameters:
 164         #
 165         # * `qname`: XML 1.0 qualified (prefixed) name.
 166         #
 167         # Returns:
 168         #
 169         # The index of the attribute, or -1 if it does not
 170         # appear in the list.
 171         fun index_of(qname: String): Int is abstract
 172
 173         # Look up an attribute's type by Namespace name.
 174         #
 175         # See `type_of` for a description
 176         # of the possible types.
 177         #
 178         # Parameters:
 179         #
 180         # * `uri`: Namespace URI, or the empty string if
 181         # the name has no Namespace URI.
 182         #
 183         # * `local_name`: attribute's local name.
 184         #
 185         # Returns:
 186         #
 187         # The attribute type as a string, or `null` if the
 188         # attribute is not in the list or if Namespace
 189         # processing is not being performed.
 190         fun type_ns(uri: String, local_name: String): nullable String is abstract
 191
 192         # Look up an attribute's value by Namespace name.
 193         #
 194         # See `value_of` for a description
 195         # of the possible values.
 196         #
 197         # Parameters:
 198         #
 199         # * `uri`: Namespace URI, or the empty string if
 200         # the name has no Namespace URI.
 201         #
 202         # * `local_name`: attribute's local name.
 203         #
 204         # Returns:
 205         #
 206         # The attribute value as a string, or `null` if the
 207         # attribute is not in the list or if Namespace
 208         # processing is not being performed.
 209         fun value_ns(uri: String, local_name: String): nullable String is abstract
 210 end