// Generated by Lisette bindgen
// Source: encoding/xml (Go stdlib)
// Go: 1.25.5
// Lisette: 0.1.11

import "go:io"
import "go:reflect"

pub fn CopyToken(t: Token) -> Token

/// Escape is like [EscapeText] but omits the error return value.
/// It is provided for backwards compatibility with Go 1.0.
/// Code targeting Go 1.1 or later should use [EscapeText].
pub fn Escape(w: io.Writer, s: Slice<uint8>)

/// EscapeText writes to w the properly escaped XML equivalent
/// of the plain text data s.
pub fn EscapeText(w: io.Writer, s: Slice<uint8>) -> Result<(), error>

/// Marshal returns the XML encoding of v.
/// 
/// Marshal handles an array or slice by marshaling each of the elements.
/// Marshal handles a pointer by marshaling the value it points at or, if the
/// pointer is nil, by writing nothing. Marshal handles an interface value by
/// marshaling the value it contains or, if the interface value is nil, by
/// writing nothing. Marshal handles all other data by writing one or more XML
/// elements containing the data.
/// 
/// The name for the XML elements is taken from, in order of preference:
///   - the tag on the XMLName field, if the data is a struct
///   - the value of the XMLName field of type [Name]
///   - the tag of the struct field used to obtain the data
///   - the name of the struct field used to obtain the data
///   - the name of the marshaled type
/// 
/// The XML element for a struct contains marshaled elements for each of the
/// exported fields of the struct, with these exceptions:
///   - the XMLName field, described above, is omitted.
///   - a field with tag "-" is omitted.
///   - a field with tag "name,attr" becomes an attribute with
///     the given name in the XML element.
///   - a field with tag ",attr" becomes an attribute with the
///     field name in the XML element.
///   - a field with tag ",chardata" is written as character data,
///     not as an XML element.
///   - a field with tag ",cdata" is written as character data
///     wrapped in one or more <![CDATA[ ... ]]> tags, not as an XML element.
///   - a field with tag ",innerxml" is written verbatim, not subject
///     to the usual marshaling procedure.
///   - a field with tag ",comment" is written as an XML comment, not
///     subject to the usual marshaling procedure. It must not contain
///     the "--" string within it.
///   - a field with a tag including the "omitempty" option is omitted
///     if the field value is empty. The empty values are false, 0, any
///     nil pointer or interface value, and any array, slice, map, or
///     string of length zero.
///   - an anonymous struct field is handled as if the fields of its
///     value were part of the outer struct.
///   - an anonymous struct field of interface type is treated the same as having
///     that type as its name, rather than being anonymous.
///   - a field implementing [Marshaler] is written by calling its MarshalXML
///     method.
///   - a field implementing [encoding.TextMarshaler] is written by encoding the
///     result of its MarshalText method as text.
/// 
/// If a field uses a tag "a>b>c", then the element c will be nested inside
/// parent elements a and b. Fields that appear next to each other that name
/// the same parent will be enclosed in one XML element.
/// 
/// If the XML name for a struct field is defined by both the field tag and the
/// struct's XMLName field, the names must match.
/// 
/// See [MarshalIndent] for an example.
/// 
/// Marshal will return an error if asked to marshal a channel, function, or map.
pub fn Marshal(v: Unknown) -> Result<Slice<uint8>, error>

/// MarshalIndent works like [Marshal], but each XML element begins on a new
/// indented line that starts with prefix and is followed by one or more
/// copies of indent according to the nesting depth.
pub fn MarshalIndent(v: Unknown, prefix: string, indent: string) -> Result<Slice<uint8>, error>

pub fn NewDecoder(r: io.Reader) -> Ref<Decoder>

pub fn NewEncoder(w: io.Writer) -> Ref<Encoder>

pub fn NewTokenDecoder(t: TokenReader) -> Ref<Decoder>

/// Unmarshal parses the XML-encoded data and stores the result in
/// the value pointed to by v, which must be an arbitrary struct,
/// slice, or string. Well-formed data that does not fit into v is
/// discarded.
/// 
/// Because Unmarshal uses the reflect package, it can only assign
/// to exported (upper case) fields. Unmarshal uses a case-sensitive
/// comparison to match XML element names to tag values and struct
/// field names.
/// 
/// Unmarshal maps an XML element to a struct using the following rules.
/// In the rules, the tag of a field refers to the value associated with the
/// key 'xml' in the struct field's tag (see the example above).
/// 
///   - If the struct has a field of type []byte or string with tag
///     ",innerxml", Unmarshal accumulates the raw XML nested inside the
///     element in that field. The rest of the rules still apply.
/// 
///   - If the struct has a field named XMLName of type Name,
///     Unmarshal records the element name in that field.
/// 
///   - If the XMLName field has an associated tag of the form
///     "name" or "namespace-URL name", the XML element must have
///     the given name (and, optionally, name space) or else Unmarshal
///     returns an error.
/// 
///   - If the XML element has an attribute whose name matches a
///     struct field name with an associated tag containing ",attr" or
///     the explicit name in a struct field tag of the form "name,attr",
///     Unmarshal records the attribute value in that field.
/// 
///   - If the XML element has an attribute not handled by the previous
///     rule and the struct has a field with an associated tag containing
///     ",any,attr", Unmarshal records the attribute value in the first
///     such field.
/// 
///   - If the XML element contains character data, that data is
///     accumulated in the first struct field that has tag ",chardata".
///     The struct field may have type []byte or string.
///     If there is no such field, the character data is discarded.
/// 
///   - If the XML element contains comments, they are accumulated in
///     the first struct field that has tag ",comment".  The struct
///     field may have type []byte or string. If there is no such
///     field, the comments are discarded.
/// 
///   - If the XML element contains a sub-element whose name matches
///     the prefix of a tag formatted as "a" or "a>b>c", unmarshal
///     will descend into the XML structure looking for elements with the
///     given names, and will map the innermost elements to that struct
///     field. A tag starting with ">" is equivalent to one starting
///     with the field name followed by ">".
/// 
///   - If the XML element contains a sub-element whose name matches
///     a struct field's XMLName tag and the struct field has no
///     explicit name tag as per the previous rule, unmarshal maps
///     the sub-element to that struct field.
/// 
///   - If the XML element contains a sub-element whose name matches a
///     field without any mode flags (",attr", ",chardata", etc), Unmarshal
///     maps the sub-element to that struct field.
/// 
///   - If the XML element contains a sub-element that hasn't matched any
///     of the above rules and the struct has a field with tag ",any",
///     unmarshal maps the sub-element to that struct field.
/// 
///   - An anonymous struct field is handled as if the fields of its
///     value were part of the outer struct.
/// 
///   - A struct field with tag "-" is never unmarshaled into.
/// 
/// If Unmarshal encounters a field type that implements the Unmarshaler
/// interface, Unmarshal calls its UnmarshalXML method to produce the value from
/// the XML element.  Otherwise, if the value implements
/// [encoding.TextUnmarshaler], Unmarshal calls that value's UnmarshalText method.
/// 
/// Unmarshal maps an XML element to a string or []byte by saving the
/// concatenation of that element's character data in the string or
/// []byte. The saved []byte is never nil.
/// 
/// Unmarshal maps an attribute value to a string or []byte by saving
/// the value in the string or slice.
/// 
/// Unmarshal maps an attribute value to an [Attr] by saving the attribute,
/// including its name, in the Attr.
/// 
/// Unmarshal maps an XML element or attribute value to a slice by
/// extending the length of the slice and mapping the element or attribute
/// to the newly created value.
/// 
/// Unmarshal maps an XML element or attribute value to a bool by
/// setting it to the boolean value represented by the string. Whitespace
/// is trimmed and ignored.
/// 
/// Unmarshal maps an XML element or attribute value to an integer or
/// floating-point field by setting the field to the result of
/// interpreting the string value in decimal. There is no check for
/// overflow. Whitespace is trimmed and ignored.
/// 
/// Unmarshal maps an XML element to a Name by recording the element
/// name.
/// 
/// Unmarshal maps an XML element to a pointer by setting the pointer
/// to a freshly allocated value and then mapping the element to that value.
/// 
/// A missing element or empty attribute value will be unmarshaled as a zero value.
/// If the field is a slice, a zero value will be appended to the field. Otherwise, the
/// field will be set to its zero value.
pub fn Unmarshal(data: Slice<uint8>, v: Unknown) -> Result<(), error>

/// An Attr represents an attribute in an XML element (Name=Value).
pub struct Attr {
  pub Name: Name,
  pub Value: string,
}

/// A CharData represents XML character data (raw text),
/// in which XML escape sequences have been replaced by
/// the characters they represent.
pub struct CharData(Slice<uint8>)

/// A Comment represents an XML comment of the form <!--comment-->.
/// The bytes do not include the <!-- and --> comment markers.
pub struct Comment(Slice<uint8>)

/// A Decoder represents an XML parser reading a particular input stream.
/// The parser assumes that its input is encoded in UTF-8.
pub struct Decoder {
  pub Strict: bool,
  pub AutoClose: Slice<string>,
  pub Entity: Map<string, string>,
  pub CharsetReader: fn(string, io.Reader) -> Result<io.Reader, error>,
  pub DefaultSpace: string,
}

/// A Directive represents an XML directive of the form <!text>.
/// The bytes do not include the <! and > markers.
pub struct Directive(Slice<uint8>)

/// An Encoder writes XML data to an output stream.
pub type Encoder

/// An EndElement represents an XML end element.
pub struct EndElement {
  pub Name: Name,
}

/// Marshaler is the interface implemented by objects that can marshal
/// themselves into valid XML elements.
/// 
/// MarshalXML encodes the receiver as zero or more XML elements.
/// By convention, arrays or slices are typically encoded as a sequence
/// of elements, one per entry.
/// Using start as the element tag is not required, but doing so
/// will enable [Unmarshal] to match the XML elements to the correct
/// struct field.
/// One common implementation strategy is to construct a separate
/// value with a layout corresponding to the desired XML and then
/// to encode it using e.EncodeElement.
/// Another common strategy is to use repeated calls to e.EncodeToken
/// to generate the XML output one token at a time.
/// The sequence of encoded tokens must make up zero or more valid
/// XML elements.
pub interface Marshaler {
  fn MarshalXML(e: Ref<Encoder>, start: StartElement) -> Result<(), error>
}

/// MarshalerAttr is the interface implemented by objects that can marshal
/// themselves into valid XML attributes.
/// 
/// MarshalXMLAttr returns an XML attribute with the encoded value of the receiver.
/// Using name as the attribute name is not required, but doing so
/// will enable [Unmarshal] to match the attribute to the correct
/// struct field.
/// If MarshalXMLAttr returns the zero attribute [Attr]{}, no attribute
/// will be generated in the output.
/// MarshalXMLAttr is used only for struct fields with the
/// "attr" option in the field tag.
pub interface MarshalerAttr {
  fn MarshalXMLAttr(name: Name) -> Result<Attr, error>
}

/// A Name represents an XML name (Local) annotated
/// with a name space identifier (Space).
/// In tokens returned by [Decoder.Token], the Space identifier
/// is given as a canonical URL, not the short prefix used
/// in the document being parsed.
pub struct Name {
  pub Space: string,
  pub Local: string,
}

/// A ProcInst represents an XML processing instruction of the form <?target inst?>
pub struct ProcInst {
  pub Target: string,
  pub Inst: Slice<uint8>,
}

/// A StartElement represents an XML start element.
pub struct StartElement {
  pub Name: Name,
  pub Attr: Slice<Attr>,
}

/// A SyntaxError represents a syntax error in the XML input stream.
pub struct SyntaxError {
  pub Msg: string,
  pub Line: int,
}

/// A TagPathError represents an error in the unmarshaling process
/// caused by the use of field tags with conflicting paths.
pub struct TagPathError {
  pub Struct: Option<reflect.Type>,
  pub Field1: string,
  pub Tag1: string,
  pub Field2: string,
  pub Tag2: string,
}

/// A Token is an interface holding one of the token types:
/// [StartElement], [EndElement], [CharData], [Comment], [ProcInst], or [Directive].
pub struct Token(Unknown)

/// A TokenReader is anything that can decode a stream of XML tokens, including a
/// [Decoder].
/// 
/// When Token encounters an error or end-of-file condition after successfully
/// reading a token, it returns the token. It may return the (non-nil) error from
/// the same call or return the error (and a nil token) from a subsequent call.
/// An instance of this general case is that a TokenReader returning a non-nil
/// token at the end of the token stream may return either io.EOF or a nil error.
/// The next Read should return nil, [io.EOF].
/// 
/// Implementations of Token are discouraged from returning a nil token with a
/// nil error. Callers should treat a return of nil, nil as indicating that
/// nothing happened; in particular it does not indicate EOF.
pub interface TokenReader {
  fn Token() -> Result<Token, error>
}

/// An UnmarshalError represents an error in the unmarshaling process.
pub struct UnmarshalError(string)

/// Unmarshaler is the interface implemented by objects that can unmarshal
/// an XML element description of themselves.
/// 
/// UnmarshalXML decodes a single XML element
/// beginning with the given start element.
/// If it returns an error, the outer call to Unmarshal stops and
/// returns that error.
/// UnmarshalXML must consume exactly one XML element.
/// One common implementation strategy is to unmarshal into
/// a separate value with a layout matching the expected XML
/// using d.DecodeElement, and then to copy the data from
/// that value into the receiver.
/// Another common strategy is to use d.Token to process the
/// XML object one token at a time.
/// UnmarshalXML may not use d.RawToken.
pub interface Unmarshaler {
  fn UnmarshalXML(d: Ref<Decoder>, start: StartElement) -> Result<(), error>
}

/// UnmarshalerAttr is the interface implemented by objects that can unmarshal
/// an XML attribute description of themselves.
/// 
/// UnmarshalXMLAttr decodes a single XML attribute.
/// If it returns an error, the outer call to [Unmarshal] stops and
/// returns that error.
/// UnmarshalXMLAttr is used only for struct fields with the
/// "attr" option in the field tag.
pub interface UnmarshalerAttr {
  fn UnmarshalXMLAttr(attr: Attr) -> Result<(), error>
}

/// UnsupportedTypeError is returned when [Marshal] encounters a type
/// that cannot be converted into XML.
pub struct UnsupportedTypeError {
  pub Type: Option<reflect.Type>,
}

const Header = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"

/// HTMLAutoClose is the set of HTML elements that
/// should be considered to close automatically.
/// 
/// See the [Decoder.Strict] and [Decoder.Entity] fields' documentation.
pub var HTMLAutoClose: Slice<string>

/// HTMLEntity is an entity map containing translations for the
/// standard HTML entity characters.
/// 
/// See the [Decoder.Strict] and [Decoder.Entity] fields' documentation.
pub var HTMLEntity: Map<string, string>

impl CharData {
  /// Copy creates a new copy of CharData.
  fn Copy(self) -> CharData
}

impl Comment {
  /// Copy creates a new copy of Comment.
  fn Copy(self) -> Comment
}

impl Decoder {
  /// Decode works like [Unmarshal], except it reads the decoder
  /// stream to find the start element.
  fn Decode(self: Ref<Decoder>, v: Unknown) -> Result<(), error>

  /// DecodeElement works like [Unmarshal] except that it takes
  /// a pointer to the start XML element to decode into v.
  /// It is useful when a client reads some raw XML tokens itself
  /// but also wants to defer to [Unmarshal] for some elements.
  fn DecodeElement(self: Ref<Decoder>, v: Unknown, start: Ref<StartElement>) -> Result<(), error>

  /// InputOffset returns the input stream byte offset of the current decoder position.
  /// The offset gives the location of the end of the most recently returned token
  /// and the beginning of the next token.
  fn InputOffset(self: Ref<Decoder>) -> int64

  /// InputPos returns the line of the current decoder position and the 1 based
  /// input position of the line. The position gives the location of the end of the
  /// most recently returned token.
  fn InputPos(self: Ref<Decoder>) -> (int, int)

  /// RawToken is like [Decoder.Token] but does not verify that
  /// start and end elements match and does not translate
  /// name space prefixes to their corresponding URLs.
  fn RawToken(self: Ref<Decoder>) -> Result<Token, error>

  /// Skip reads tokens until it has consumed the end element
  /// matching the most recent start element already consumed,
  /// skipping nested structures.
  /// It returns nil if it finds an end element matching the start
  /// element; otherwise it returns an error describing the problem.
  fn Skip(self: Ref<Decoder>) -> Result<(), error>

  /// Token returns the next XML token in the input stream.
  /// At the end of the input stream, Token returns nil, [io.EOF].
  /// 
  /// Slices of bytes in the returned token data refer to the
  /// parser's internal buffer and remain valid only until the next
  /// call to Token. To acquire a copy of the bytes, call [CopyToken]
  /// or the token's Copy method.
  /// 
  /// Token expands self-closing elements such as <br>
  /// into separate start and end elements returned by successive calls.
  /// 
  /// Token guarantees that the [StartElement] and [EndElement]
  /// tokens it returns are properly nested and matched:
  /// if Token encounters an unexpected end element
  /// or EOF before all expected end elements,
  /// it will return an error.
  /// 
  /// If [Decoder.CharsetReader] is called and returns an error,
  /// the error is wrapped and returned.
  /// 
  /// Token implements XML name spaces as described by
  /// https://www.w3.org/TR/REC-xml-names/. Each of the
  /// [Name] structures contained in the Token has the Space
  /// set to the URL identifying its name space when known.
  /// If Token encounters an unrecognized name space prefix,
  /// it uses the prefix as the Space rather than report an error.
  fn Token(self: Ref<Decoder>) -> Result<Token, error>
}

impl Directive {
  /// Copy creates a new copy of Directive.
  fn Copy(self) -> Directive
}

impl Encoder {
  /// Close the Encoder, indicating that no more data will be written. It flushes
  /// any buffered XML to the underlying writer and returns an error if the
  /// written XML is invalid (e.g. by containing unclosed elements).
  #[allow(unused_result)]
  fn Close(self: Ref<Encoder>) -> Result<(), error>

  /// Encode writes the XML encoding of v to the stream.
  /// 
  /// See the documentation for [Marshal] for details about the conversion
  /// of Go values to XML.
  /// 
  /// Encode calls [Encoder.Flush] before returning.
  fn Encode(self: Ref<Encoder>, v: Unknown) -> Result<(), error>

  /// EncodeElement writes the XML encoding of v to the stream,
  /// using start as the outermost tag in the encoding.
  /// 
  /// See the documentation for [Marshal] for details about the conversion
  /// of Go values to XML.
  /// 
  /// EncodeElement calls [Encoder.Flush] before returning.
  fn EncodeElement(self: Ref<Encoder>, v: Unknown, start: StartElement) -> Result<(), error>

  /// EncodeToken writes the given XML token to the stream.
  /// It returns an error if [StartElement] and [EndElement] tokens are not properly matched.
  /// 
  /// EncodeToken does not call [Encoder.Flush], because usually it is part of a larger operation
  /// such as [Encoder.Encode] or [Encoder.EncodeElement] (or a custom [Marshaler]'s MarshalXML invoked
  /// during those), and those will call Flush when finished.
  /// Callers that create an Encoder and then invoke EncodeToken directly, without
  /// using Encode or EncodeElement, need to call Flush when finished to ensure
  /// that the XML is written to the underlying writer.
  /// 
  /// EncodeToken allows writing a [ProcInst] with Target set to "xml" only as the first token
  /// in the stream.
  fn EncodeToken(self: Ref<Encoder>, t: Token) -> Result<(), error>

  /// Flush flushes any buffered XML to the underlying writer.
  /// See the [Encoder.EncodeToken] documentation for details about when it is necessary.
  #[allow(unused_result)]
  fn Flush(self: Ref<Encoder>) -> Result<(), error>

  /// Indent sets the encoder to generate XML in which each element
  /// begins on a new indented line that starts with prefix and is followed by
  /// one or more copies of indent according to the nesting depth.
  fn Indent(self: Ref<Encoder>, prefix: string, indent: string)
}

impl ProcInst {
  /// Copy creates a new copy of ProcInst.
  fn Copy(self) -> ProcInst
}

impl StartElement {
  /// Copy creates a new copy of StartElement.
  fn Copy(self) -> StartElement

  /// End returns the corresponding XML end element.
  fn End(self) -> EndElement
}

impl SyntaxError {
  fn Error(self: Ref<SyntaxError>) -> string
}

impl TagPathError {
  fn Error(self: Ref<TagPathError>) -> string
}

impl UnmarshalError {
  fn Error(self) -> string
}

impl UnsupportedTypeError {
  fn Error(self: Ref<UnsupportedTypeError>) -> string
}
