/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.marshall.html;

import static javax.xml.stream.XMLStreamConstants.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.marshall.html.HtmlTag.*;

import java.io.*;
import java.lang.reflect.*;
import java.util.*;

import javax.xml.stream.*;

import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.lang.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.swap.spi.*;
import org.apache.juneau.marshall.xml.*;

/**
 * ContextSession object that lives for the duration of a single use of {@link HtmlParser}.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlSupport">HTML</a>

 * </ul>
 */
@SuppressWarnings({
   "java:S110", // Inheritance depth acceptable for this class hierarchy
   "java:S115", // Constants use UPPER_snakeCase naming convention
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S2177", // Private readIntoBean/readIntoCollection/readIntoMap intentionally reuse the names of XmlParserSession methods with HTML-specific logic
   "java:S3776", // readAnything, readTableIntoCollection and skipTag branch over HTML tag and element types
   "rawtypes", // Raw types necessary for generic type handling
   "unchecked" // Type erasure requires unchecked casts
})
public class HtmlParserSession extends XmlParserSession {

   /**
    * Builder class.
    */
   public static class Builder extends XmlParserSession.Builder<Builder> {

      private final HtmlParser ctx;

      /**
       * Constructor
       *
       * @param ctx The context creating this session.
       *    <br>Cannot be <jk>null</jk>.
       */
      protected Builder(HtmlParser ctx) {
         super(reqnn("ctx", ctx));
         this.ctx = ctx;
      }

      @Override
      public HtmlParserSession build() {
         return new HtmlParserSession(this);
      }

   }

   private static final Set<String> whitespaceElements = set("br", "bs", "sp", "ff");

   /**
    * Creates a new builder for this object.
    *
    * @param ctx The context creating this session.
    *    <br>Cannot be <jk>null</jk>.
    * @return A new builder.
    */
   public static Builder create(HtmlParser ctx) {
      return new Builder(reqnn("ctx", ctx));
   }

   private static String getAttribute(XmlReader r, String name, String def) {
      for (var i = 0; i < r.getAttributeCount(); i++)
         if (r.getAttributeLocalName(i).equals(name))
            return r.getAttributeValue(i);
      return def;
   }

   private static Map<String,String> getAttributes(XmlReader r) {
      var m = new TreeMap<String,String>();
      for (var i = 0; i < r.getAttributeCount(); i++)
         m.put(r.getAttributeLocalName(i), r.getAttributeValue(i));
      return m;
   }

   private static int skipWs(XmlReader r) throws XMLStreamException {
      int event = r.getEventType();
      while (event != START_ELEMENT && event != END_ELEMENT && event != END_DOCUMENT && r.isWhiteSpace())
         event = r.next();
      return event;
   }

   private final HtmlParser ctx;

   /**
    * Constructor.
    *
    * @param builder The builder for this object.
    */
   protected HtmlParserSession(Builder builder) {
      super(builder);
      ctx = builder.ctx;
   }

   /*
    * Reads the next tag.  Advances past anything that's not a start or end tag.  Throws an exception if
    *    it's not one of the expected tags.
    * Precondition:  Must be pointing before the event we want to parse.
    * Postcondition:  Pointing at the tag just parsed.
    */
   private HtmlTag nextTag(XmlReader r, HtmlTag...expected) throws ParseException, XMLStreamException {
      int et = r.next();

      while (et != START_ELEMENT && et != END_ELEMENT && et != END_DOCUMENT)
         et = r.next();

      if (et == END_DOCUMENT)
         throw new ParseException(this, "Unexpected end of document.");

      var tag = HtmlTag.forEvent(this, r);
      if (expected.length == 0)
         return tag;
      for (var t : expected)
         if (t == tag)
            return tag;

      throw new ParseException(this, "Unexpected tag: '%s'.  Expected one of the following: %s", tag, expected);
   }

   /*
    * Reads an anchor tag and converts it into a bean.
    */
   private <T> T readAnchor(XmlReader r, ClassMeta<T> beanType) throws IOException, ParseException, XMLStreamException {
      String href = r.getAttributeValue(null, "href");
      String name = getElementText(r);
      if (nn(beanType) && getAnnotationProvider().has(HtmlLink.class, beanType)) {
         var uriProperty = Holder.<String>empty();
         var nameProperty = Holder.<String>empty();
         beanType.forEachAnnotation(HtmlLink.class, x -> ine(x.uriProperty()), x -> uriProperty.set(x.uriProperty()));
         beanType.forEachAnnotation(HtmlLink.class, x -> ine(x.nameProperty()), x -> nameProperty.set(x.nameProperty()));
         BeanMap<T> m = newBeanMap(beanType.inner());
         m.put(uriProperty.orElse(""), href);
         m.put(nameProperty.orElse(""), name);
         return checkRequired(m).getBean();
      }
      return convertToType(href, beanType);
   }

   /*
    * Reads anything starting at the current event.
    * <p>
    * Precondition:  Must be pointing at outer START_ELEMENT.
    * Postcondition:  Pointing at outer END_ELEMENT.
    */
   private <T> T readAnything(ClassMeta<T> eType, XmlReader r, Object outer, boolean isRoot, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException, XMLStreamException {

      if (eType == null)
         eType = (ClassMeta<T>)object();
      var swap = (ObjectSwap<T,Object>)eType.getSwap(this);
      var builder = (BuilderSwap<T,Object>)eType.getBuilderSwap(this);
      ClassMeta<?> sType = null;
      if (nn(builder))
         sType = builder.getBuilderClassMeta(this);
      else if (nn(swap))
         sType = swap.getSwapClassMeta(this);
      else
         sType = eType;

      if (sType.isOptional())
         return (T)o(readAnything(eType.getElementType(), r, outer, isRoot, pMeta));

      setCurrentClass(sType);

      int event = r.getEventType();
      if (event != START_ELEMENT)
         throw new ParseException(this, "readAnything must be called on outer start element.");

      if (! isRoot)
         event = r.next();
      var isEmpty = (event == END_ELEMENT);

      // Skip until we find a start element, end document, or non-empty text.
      if (! isEmpty)
         event = skipWs(r);

      if (event == END_DOCUMENT)
         throw new ParseException(this, "Unexpected end of stream in readAnything for type '%s'", eType);

      // Handle @Html(asXml=true) beans.
      var hcm = getHtmlClassMeta(sType);
      if (hcm.getFormat() == HtmlFormat.XML)
         return super.readAnything(eType, null, r, outer, false, pMeta);

      Object o = null;

      var isValid = true;
      var tag = (event == CHARACTERS ? null : HtmlTag.forString(r.getName().getLocalPart(), false));

      // If it's not a known tag, then parse it as XML.
      // Allows us to parse stuff like "<div/>" into HTML5 beans.
      if (tag == null && event != CHARACTERS)
         return super.readAnything(eType, null, r, outer, false, pMeta);

      if (tag == HTML)
         tag = skipToData(r);

      if (isEmpty) {
         o = "";
      } else if (tag == null || tag.isOneOf(BR, BS, FF, SP)) {
         String text = readText(r);
         if (sType.isObject() || sType.isCharSequence())
            o = text;
         else if (sType.isChar())
            o = parseCharacter(text);
         else if (sType.isNumber())
            o = parseNumber(text, (Class<? extends Number>)eType.inner());
         else if (sType.isBoolean())
            o = Boolean.parseBoolean(text);
         else if (sType.isDate())
            o = readDate(text, sType);
         else if (sType.isCalendar())
            o = readCalendar(text, sType);
         else if (sType.isTemporal())
            o = readTemporal(text, sType);
         else if (sType.isDuration())
            o = readDuration(text);
         else if (sType.isPeriod())
            o = readPeriod(text);
         else if (sType.canCreateNewInstanceFromString(outer))
            o = sType.newInstanceFromString(outer, text);
         else
            isValid = false;

      } else if (tag == STRING || (tag == A && nn(pMeta) && nn(getHtmlBeanPropertyMeta(pMeta).getLink()))) {
         String text = getElementText(r);
         if (sType.isObject() || sType.isCharSequence())
            o = text;
         else if (sType.isChar())
            o = parseCharacter(text);
         else if (sType.isDate())
            o = readDate(text, sType);
         else if (sType.isCalendar())
            o = readCalendar(text, sType);
         else if (sType.isTemporal())
            o = readTemporal(text, sType);
         else if (sType.isDuration())
            o = readDuration(text);
         else if (sType.isPeriod())
            o = readPeriod(text);
         else if (sType.canCreateNewInstanceFromString(outer))
            o = sType.newInstanceFromString(outer, text);
         else
            isValid = false;
         skipTag(r, tag == STRING ? X_STRING : X_A);

      } else if (tag == NUMBER) {
         String text = getElementText(r);
         if (sType.isObject())
            o = parseNumber(text, Number.class);
         else if (sType.isNumber())
            o = parseNumber(text, (Class<? extends Number>)sType.inner());
         else
            isValid = false;
         skipTag(r, X_NUMBER);

      } else if (tag == BOOLEAN) {
         String text = getElementText(r);
         if (sType.isObject() || sType.isBoolean())
            o = Boolean.parseBoolean(text);
         else
            isValid = false;
         skipTag(r, X_BOOLEAN);

      } else if (tag == P) {
         String text = getElementText(r);
         if (neq(text, "No Results"))
            isValid = false;
         skipTag(r, X_P);

      } else if (tag == NULL) {
         skipTag(r, NULL);
         skipTag(r, X_NULL);

      } else if (tag == A) {
         o = readAnchor(r, swap == null ? eType : null);
         skipTag(r, X_A);

      } else if (tag == TABLE) {

         String typeName = getAttribute(r, getBeanTypePropertyName(eType), "object");
         ClassMeta cm = getClassMeta(typeName, pMeta, eType);

         if (nn(cm)) {
            sType = eType = cm;
            typeName = sType.isCollectionOrArray() ? "array" : "object";
         } else if (neq(typeName, "array")) {
            // Type name could be a subtype name.
            typeName = sType.isCollectionOrArray() ? "array" : "object";
         }

         if (typeName.equals("object")) {
            if (sType.isObject()) {
               o = readIntoMap(r, newGenericMap(sType), sType.getKeyType(), sType.getValueType(), pMeta);
            } else if (nn(builder)) {
               BeanMap m = toBeanMap(builder.create(this, eType));
               o = builder.build(this, checkRequired(readIntoBean(r, m)).getBean(), eType);
            } else if (sType.canCreateNewBean(outer)) {
               BeanMap m = newBeanMap(outer, sType.inner());
               o = checkRequired(readIntoBean(r, m)).getBean();
            } else if (sType.isMap()) {
               o = readIntoMap(r, (Map)(sType.canCreateNewInstance(outer) ? sType.newInstance(outer) : newGenericMap(sType)), sType.getKeyType(), sType.getValueType(), pMeta);
            } else if (nn(sType.getProxyInvocationHandler())) {
               BeanMap m = newBeanMap(outer, sType.inner());
               o = checkRequired(readIntoBean(r, m)).getBean();
            } else {
               isValid = false;
            }
            skipTag(r, X_TABLE);

         } else if (typeName.equals("array")) {
            if (sType.isObject())
               o = readTableIntoCollection(r, (Collection)newGenericList(), sType, pMeta);
            else if (sType.isCollection())
               o = readTableIntoCollection(r, (Collection)(sType.canCreateNewInstance(outer) ? sType.newInstance(outer) : newGenericList()), sType, pMeta);
            else if (sType.isArray() || sType.isArgs()) {
               var l = (ArrayList)readTableIntoCollection(r, list(), sType, pMeta);
               o = toArray(sType, l);
            } else
               isValid = false;
            skipTag(r, X_TABLE);

         } else {
            isValid = false;
         }

      } else if (tag == UL) {
         String typeName = getAttribute(r, getBeanTypePropertyName(eType), "array");
         ClassMeta cm = getClassMeta(typeName, pMeta, eType);
         if (nn(cm))
            sType = eType = cm;

         if (sType.isObject())
            o = readIntoCollection(r, newGenericList(), sType, pMeta);
         else if (sType.isCollection() || sType.isObject())
            o = readIntoCollection(r, (Collection)(sType.canCreateNewInstance(outer) ? sType.newInstance(outer) : newGenericList()), sType, pMeta);
         else if (sType.isArray() || sType.isArgs())
            o = toArray(sType, readIntoCollection(r, list(), sType, pMeta));
         else
            isValid = false;
         skipTag(r, X_UL);

      }

      if (! isValid)
         throw new ParseException(this, "Unexpected tag '%s' for type '%s'", tag, eType);

      if (nn(swap) && nn(o))
         o = unswap(swap, o, eType);

      if (nn(parentBean()))
         setParent(eType, o, parentBean());

      skipWs(r);
      return (T)o;
   }

   /*
    * Reads contents of <table> element.
    * Precondition:  Must be pointing at event following <table> event.
    * Postcondition:  Pointing at next START_ELEMENT or END_DOCUMENT event.
    */
   private <T> BeanMap<T> readIntoBean(XmlReader r, BeanMap<T> m) throws IOException, ParseException, ExecutableException, XMLStreamException {
      var pb = swapParentBean(m.getBean(false));
      try {
         while (true) {
            HtmlTag tag = nextTag(r, TR, X_TABLE);
            if (tag == X_TABLE)
               break;
            tag = nextTag(r, TD, TH);
            // Skip over the column headers.
            if (tag == TH) {
               skipTag(r);
               r.nextTag();
               skipTag(r);
            } else {
               String key = getElementText(r);
               nextTag(r, TD);
               var pMeta = m.getPropertyMeta(key);
               if (pMeta == null) {
                  onUnknownProperty(key, m, readAnything(object(), r, null, false, null));
               } else {
                  var cm = (ClassMeta<?>) pMeta.getBeanInfo();
                  Object value = readAnything(cm, r, m.getBean(false), false, pMeta);
                  setName(cm, value, key);
                  try {
                     pMeta.set(m, key, value);
                  } catch (BeanRuntimeException e) {
                     onBeanSetterException(pMeta, e);
                     throw e;
                  }
               }
            }
            HtmlTag t = nextTag(r, X_TD, X_TR);
            if (t == X_TD)
               nextTag(r, X_TR);
         }
         return m;
      } finally {
         swapParentBean(pb);
      }
   }

   /*
    * Reads contents of <ul> element.
    * Precondition:  Must be pointing at event following <ul> event.
    * Postcondition:  Pointing at next START_ELEMENT or END_DOCUMENT event.
    */
   private <E> Collection<E> readIntoCollection(XmlReader r, Collection<E> l, ClassMeta<?> type, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException, XMLStreamException {
      int argIndex = 0;
      while (true) {
         HtmlTag tag = nextTag(r, LI, X_UL, X_LI);
         if (tag == X_LI)
            tag = nextTag(r, LI, X_UL, X_LI);
         if (tag == X_UL)
            break;
         var elementType = type.isArgs() ? type.getArg(argIndex++) : type.getElementType();
         l.add((E)readAnything(elementType, r, l, false, pMeta));
      }
      return l;
   }

   /*
    * Reads contents of <table> element.
    * Precondition:  Must be pointing at <table> event.
    * Postcondition:  Pointing at next START_ELEMENT or END_DOCUMENT event.
    */
   private <K,V> Map<K,V> readIntoMap(XmlReader r, Map<K,V> m, ClassMeta<K> keyType, ClassMeta<V> valueType, BeanPropertyMeta pMeta)
      throws IOException, ParseException, ExecutableException, XMLStreamException {
      while (true) {
         HtmlTag tag = nextTag(r, TR, X_TABLE);
         if (tag == X_TABLE)
            break;
         tag = nextTag(r, TD, TH);
         // Skip over the column headers.
         if (tag == TH) {
            skipTag(r);
            r.nextTag();
            skipTag(r);
         } else {
            K key = readAnything(keyType, r, m, false, pMeta);
            nextTag(r, TD);
            V value = readAnything(valueType, r, m, false, pMeta);
            setName(valueType, value, key);
            m.put(key, value);
         }
         tag = nextTag(r, X_TD, X_TR);
         if (tag == X_TD)
            nextTag(r, X_TR);
      }

      return m;
   }

   /*
    * Reads contents of <ul> element.
    * Precondition:  Must be pointing at event following <ul> event.
    * Postcondition:  Pointing at next START_ELEMENT or END_DOCUMENT event.
    */
   private <E> Collection<E> readTableIntoCollection(XmlReader r, Collection<E> l, ClassMeta<E> type, BeanPropertyMeta pMeta)
      throws IOException, ParseException, ExecutableException, XMLStreamException {

      nextTag(r, TR);
      List<String> keys = list();
      HtmlTag tag;
      while (true) {
         tag = nextTag(r, TH, X_TR);
         if (tag == X_TR)
            break;
         keys.add(getElementText(r));
      }

      int argIndex = 0;

      while (true) {
         r.nextTag();
         tag = HtmlTag.forEvent(this, r);
         if (tag == X_TABLE)
            break;

         ClassMeta elementType = null;
         String beanType = getAttribute(r, getBeanTypePropertyName(type), null);
         if (nn(beanType))
            elementType = getClassMeta(beanType, pMeta, null);
         if (elementType == null)
            elementType = type.isArgs() ? type.getArg(argIndex++) : type.getElementType();
         if (elementType == null)
            elementType = object();

         BuilderSwap<E,Object> builder = elementType.getBuilderSwap(this);

         if (nn(builder) || elementType.canCreateNewBean(l)) {
            // @formatter:off
            BeanMap m =
               nn(builder)
               ? toBeanMap(builder.create(this, elementType))
               : newBeanMap(l, elementType.inner())
            ;
            // @formatter:on
            var pb = swapParentBean(m.getBean(false));
            try {
               for (var key : keys) {
                  tag = nextTag(r, X_TD, TD, NULL);
                  if (tag == X_TD)
                     tag = nextTag(r, TD, NULL);
                  if (tag == NULL) {
                     m = null;
                     nextTag(r, X_NULL);
                     break;
                  }
                  BeanMapEntry e = m.getProperty(key);
                  if (e == null) {
                     readAnything(object(), r, l, false, null);
                  } else {
                     BeanPropertyMeta bpm = e.getMeta();
                     var cm = (ClassMeta<?>) bpm.getBeanInfo();
                     Object value = readAnything(cm, r, m.getBean(false), false, bpm);
                     setName(cm, value, key);
                     bpm.set(m, key, value);
                  }
               }
            } finally {
               swapParentBean(pb);
            }
            E element;
            if (m == null) {
               element = null;
            } else if (nn(builder)) {
               element = builder.build(this, checkRequired(m).getBean(), elementType);
            } else {
               element = (E)checkRequired(m).getBean();
            }
            if (nn(parentBean()) && nn(element))
               setParent(elementType, element, parentBean());
            l.add(element);
         } else {
            String c = getAttributes(r).get(getBeanTypePropertyName(type.getElementType()));
            var m = (Map)(elementType.isMap() && elementType.canCreateNewInstance(l) ? elementType.newInstance(l) : newGenericMap(elementType));
            for (var key : keys) {
               tag = nextTag(r, TD, NULL);
               if (tag == NULL) {
                  m = null;
                  nextTag(r, X_NULL);
                  break;
               }
               if (nn(m)) {
                  var kt = elementType.getKeyType();
                  var vt = elementType.getValueType();
                  Object value = readAnything(vt, r, l, false, pMeta);
                  setName(vt, value, key);
                  m.put(convertToType(key, kt), value);
               }
            }
            if (nn(m) && nn(c)) {
               var m2 = (m instanceof MarshalledMap m3 ? m3 : new JsonMap(m).session(this));
               m2.put(getBeanTypePropertyName(type.getElementType()), c);
               l.add((E)cast(m2, pMeta, elementType));
            } else {
               if (m instanceof MarshalledMap m2)
                  l.add((E)convertToType(m2, elementType));
               else
                  l.add((E)m);
            }
         }
         nextTag(r, X_TR);
      }
      return l;
   }

   /**
    * Skips over the current element and advances to the next element.
    * <p>
    * Precondition:  Pointing to opening tag.
    * Postcondition:  Pointing to next opening tag.
    *
    * @param r The stream being read from.
    * @throws XMLStreamException
    */
   private void skipTag(XmlReader r) throws ParseException, XMLStreamException {
      int et = r.getEventType();

      if (et != START_ELEMENT)
         throw new ParseException(this, "skipToNextTag() call on invalid event '%s'.  Must only be called on START_ELEMENT events.", XmlUtils.toReadableEvent(r));

      String n = r.getLocalName();

      int depth = 0;
      while (true) {
         et = r.next();
         if (et == START_ELEMENT) {
            String n2 = r.getLocalName();
            if (n.equals(n2))
               depth++;
         } else if (et == END_ELEMENT) {
            String n2 = r.getLocalName();
            if (n.equals(n2))
               depth--;
            if (depth < 0)
               return;
         }
      }
   }

   private void skipTag(XmlReader r, HtmlTag...expected) throws ParseException, XMLStreamException {
      var tag = HtmlTag.forEvent(this, r);
      if (tag.isOneOf(expected))
         r.next();
      else
         throw new ParseException(this, "Unexpected tag: '%s'.  Expected one of the following: %s", tag, expected);
   }

   /*
    * For parsing output from HtmlDocSerializer, this skips over the head, title, and links.
    */
   private HtmlTag skipToData(XmlReader r) throws ParseException, XMLStreamException {
      while (true) {
         var event = r.next();
         if (event == START_ELEMENT && eq(r.getLocalName(), "div") && eq(r.getAttributeValue(null, "id"), "data")) {
            r.nextTag();
            event = r.getEventType();
            var isEmpty = (event == END_ELEMENT);
            // Skip until we find a start element, end document, or non-empty text.
            if (! isEmpty)
               event = skipWs(r);
            if (event == END_DOCUMENT)
               throw new ParseException(this, "Unexpected end of stream looking for data.");
            return (event == CHARACTERS ? null : HtmlTag.forString(r.getName().getLocalPart(), false));
         }
      }
   }

   @Override /* Overridden from ParserSession */
   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
      try {
         return readAnything(type, getXmlReader(pipe), getOuter(), true, null);
      } catch (XMLStreamException e) {
         throw new ParseException(e);
      }
   }

   @Override /* Overridden from ReaderParserSession */
   protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws Exception {
      return readIntoCollection(getXmlReader(pipe), c, getClassMeta(elementType), null);
   }

   @Override /* Overridden from ReaderParserSession */
   protected <K,V> Map<K,V> doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws Exception {
      return readIntoMap(getXmlReader(pipe), m, (ClassMeta<K>)getClassMeta(keyType), (ClassMeta<V>)getClassMeta(valueType), null);
   }

   /**
    * Identical to {@link #readText(XmlReader)} except assumes the current event is the opening tag.
    *
    * <p>
    * Precondition:  Pointing to opening tag.
    * Postcondition:  Pointing to closing tag.
    *
    * @param r The stream being read from.
    * @return The parsed string.
    * @throws XMLStreamException Thrown by underlying XML stream.
    * @throws ParseException Malformed input encountered.
    */
   @Override /* Overridden from XmlParserSession */
   protected String getElementText(XmlReader r) throws IOException, XMLStreamException, ParseException {
      r.next();
      return readText(r);
   }

   /**
    * Returns the language-specific metadata on the specified bean property.
    *
    * @param bpm The bean property to return the metadata on.
    * @return The metadata.
    */
   protected HtmlBeanPropertyMeta getHtmlBeanPropertyMeta(BeanPropertyMeta bpm) {
      return ctx.getHtmlBeanPropertyMeta(bpm);
   }

   /**
    * Returns the language-specific metadata on the specified class.
    *
    * @param cm The class to return the metadata on.
    * @return The metadata.
    */
   protected HtmlClassMeta getHtmlClassMeta(ClassMeta<?> cm) {
      return ctx.getHtmlClassMeta(cm);
   }

   @Override /* Overridden from XmlParserSession */
   protected boolean isWhitespaceElement(XmlReader r) {
      String s = r.getLocalName();
      return whitespaceElements.contains(s);
   }

   /**
    * Parses CHARACTERS data.
    *
    * <p>
    * Precondition:  Pointing to event immediately following opening tag.
    * Postcondition:  Pointing to closing tag.
    *
    * @param r The stream being read from.
    * @return The parsed string.
    * @throws XMLStreamException Thrown by underlying XML stream.
    */
   @Override /* Overridden from XmlParserSession */
   protected String readText(XmlReader r) throws IOException, ParseException, XMLStreamException {

      StringBuilder sb = getStringBuilder();

      int et = r.getEventType();
      if (et == END_ELEMENT)
         return "";

      int depth = 0;

      String characters = null;

      while (true) {
         if (et == START_ELEMENT) {
            if (nn(characters)) {
               if (sb.isEmpty())
                  characters = trimStart(characters);
               sb.append(characters);
               characters = null;
            }
            var tag = HtmlTag.forEvent(this, r);
            if (tag == BR) {
               sb.append('\n');
               r.nextTag();
            } else if (tag == BS) {
               sb.append('\b');
               r.nextTag();
            } else if (tag == SP) {
               et = r.next();
               if (et == CHARACTERS) {
                  String s = r.getText();
                  if (ine(s)) {
                     var c = r.getText().charAt(0);
                     if (c == '\u2003')
                        c = '\t';
                     sb.append(c);
                  }
                  r.nextTag();
               }
            } else if (tag == FF) {
               sb.append('\f');
               r.nextTag();
            } else if (tag.isOneOf(STRING, NUMBER, BOOLEAN)) {
               et = r.next();
               if (et == CHARACTERS) {
                  sb.append(r.getText());
                  r.nextTag();
               }
            } else {
               sb.append('<').append(r.getLocalName());
               for (var i = 0; i < r.getAttributeCount(); i++)
                  sb.append(' ').append(r.getAttributeName(i)).append('=').append('\'').append(r.getAttributeValue(i)).append('\'');
               sb.append('>');
               depth++;
            }
         } else if (et == END_ELEMENT) {
            if (nn(characters)) {
               if (sb.isEmpty())
                  characters = trimStart(characters);
               if (depth == 0)
                  characters = trimEnd(characters);
               sb.append(characters);
               characters = null;
            }
            if (depth == 0)
               break;
            sb.append('<').append(r.getLocalName()).append('>');
            depth--;
         } else if (et == CHARACTERS) {
            characters = r.getText();
         }
         et = r.next();
      }

      String s = trim(sb.toString());
      returnStringBuilder(sb);
      return s;
   }

   @Override /* Overridden from XmlParserSession */
   protected String readWhitespaceElement(XmlReader r) throws IOException, ParseException, XMLStreamException {

      var tag = HtmlTag.forEvent(this, r);
      int et = r.next();
      if (tag == BR) {
         return "\n";
      } else if (tag == BS) {
         return "\b";
      } else if (tag == FF) {
         return "\f";
      } else if (tag == SP) {
         if (et == CHARACTERS) {
            String s = r.getText();
            if (s.charAt(0) == '\u2003')
               s = "\t";
            r.next();
            return decodeString(s);
         }
         return "";
      } else {
         throw new ParseException(this, "Invalid tag found in readWhitespaceElement(): '%s'", tag);
      }
   }
}