/*
 * 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.uon;

import static org.apache.juneau.commons.lang.StateEnum.*;
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 java.io.*;
import java.lang.reflect.*;
import java.util.*;

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

/**
 * Session object that lives for the duration of a single use of {@link UonParser}.
 *
 * <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/UonSupport">UON</a>

 * </ul>
 */
@SuppressWarnings({
   "java:S110", // Deep inheritance inherent to the serializer/parser session hierarchy
   "java:S115", // Constants use UPPER_snakeCase convention (e.g., CONST_value)
   "java:S125", // State-machine comments are documentation, not commented-out code
   "java:S1168", // readIntoMap()/readIntoCollection()/readIntoBeanMap() return null for blank, literal null or '%00' input, which callers treat as 'no value'.
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S2583", // The post-loop state checks in readIntoCollection() look constant to static analysis but are reachable when input ends mid-entry.
   "java:S3776", // readAnything() and the readInto*() methods are state machines over the UON grammar; splitting them would obscure the parse flow.
   "java:S6541", // readAnything() is the single type-dispatch point of the parser and is long by design.
   "rawtypes", // Raw types necessary for generic type handling
   "resource", // UonReader is managed by caller
   "unchecked", // Type erasure requires unchecked casts
   "unused" // Intentionally unused; variable/parameter is required by the interface contract
})
public class UonParserSession extends ReaderParserSession implements HttpPartParserSession, RecordReadable {

   /**
    * Builder class.
    */
   @SuppressWarnings({
      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
   })
   public abstract static class Builder<SELF extends Builder<SELF>> extends ReaderParserSession.Builder<SELF> {

      private boolean decoding;
      private boolean validateEnd;

      /**
       * Constructor
       *
       * @param ctx The context creating this session.
       */
      protected Builder(UonParser ctx) {
         super(ctx);
         decoding = ctx.decoding;
         validateEnd = ctx.isValidateEnd();
      }

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

      /**
       * Overrides the decoding flag on the context for this session.
       *
       * @param value The new value for this setting.
       * @return This object.
       */
      public SELF decoding(boolean value) {
         decoding = value;
         return self();
      }

      @Override /* Overridden from Builder */
      public SELF property(String key, Object value) {
         if (key == null) { super.property(key, value); return self(); }
         switch (key) {
            case "decoding":
               return decoding(cvt(value, Boolean.class));
            case "validateEnd", "UonParserSession.validateEnd":
               return validateEnd(cvt(value, Boolean.class));
            default:
               super.property(key, value);
               return self();
         }
      }

      /**
       * Validate end.
       *
       * @param value The new value for this setting.
       * @return This object.
       */
      public SELF validateEnd(boolean value) {
         validateEnd = value;
         return self();
      }

   }

   /**
    * Concrete default builder leaf for the non-subclassed {@code create()} path (CRTP terminal).
    */
   public static final class DefaultBuilder extends Builder<DefaultBuilder> {

      DefaultBuilder(UonParser ctx) {
         super(ctx);
      }
   }

   // Characters that need to be preceded with an escape character.
   private static final AsciiSet escapedChars = AsciiSet.of("~'\u0001\u0002");

   private static final char AMP = '\u0001';  // Flags set in reader to denote & and = characters.
   private static final char EQ = '\u0002';
   private static final AsciiSet endCharsParam = AsciiSet.of("" + AMP);
   private static final AsciiSet endCharsNormal = AsciiSet.of(",)" + AMP);

   /**
    * Creates a new builder for this object.
    *
    * @param ctx The context creating this session.
    * @return A new builder.
    */
   @SuppressWarnings({
      "java:S1452" // Builder<?> wildcard return intentional; callers use it to construct session instances polymorphically
   })
   public static Builder<?> create(UonParser ctx) {
      return new DefaultBuilder(ctx);
   }

   /*
    * Returns true if the next character in the stream is preceded by an escape '~' character.
    */
   private static final boolean isInEscape(int c, ParserReader r, boolean prevIsInEscape) throws IOException {
      if (c == '~' && ! prevIsInEscape) {
         c = r.peek();
         if (escapedChars.contains(c)) {
            r.delete();
            return true;
         }
      }
      return false;
   }

   private static void skipSpace(ParserReader r) throws IOException {
      int c = 0;
      while ((c = r.read()) != -1) {
         if (c <= 2 || ! Character.isWhitespace(c)) {
            r.unread();
            return;
         }
      }
   }

   private final boolean decoding;
   private final boolean validateEnd;

   /**
    * Constructor.
    *
    * @param builder The builder for this object.
    */
   protected UonParserSession(Builder<?> builder) {
      super(builder);
      decoding = builder.decoding;
      validateEnd = builder.validateEnd;
   }

   @Override /* RecordReadable */
   public RecordReader readRecords(Object input) throws IOException {
      return RecordAdapter.reader(this, input);
   }

   @Override /* RecordReadable */
   public boolean isRecordStreaming() {
      return false;
   }

   /**
    * Creates a {@link UonReader} from the specified parser pipe.
    *
    * @param pipe The parser input.
    * @param decodeChars Whether the reader should automatically decode URL-encoded characters.
    * @return A new {@link UonReader} object.
    * @throws IOException Thrown by underlying stream.
    */
   public static final UonReader getUonReader(ParserPipe pipe, boolean decodeChars) throws IOException {
      var r = pipe.getReader();
      if (r instanceof UonReader r2)
         return r2;
      return new UonReader(pipe, decodeChars);
   }

   @Override /* Overridden from HttpPartParser */
   public <T> T read(HttpPartType partType, HttpPartSchema schema, String in, ClassMeta<T> toType) throws ParseException, SchemaValidationException {
      if (in == null)
         return null;
      if (toType.isString() && ine(in)) {
         // Shortcut - If we're returning a string and the value doesn't start with "'" or is "null", then
         // just return the string since it's a plain value.
         // This allows us to bypass the creation of a UonParserSession object.
         char x = firstNonWhitespaceChar(in);
         if (x != '\'' && x != 'n' && in.indexOf('~') == -1)
            return (T)in;
         if (x == 'n' && "null".equals(in))
            return null;
      }
      try (var pipe = createPipe(in)) {
         try (var r = getUonReader(pipe, false)) {
            return readAnything(toType, r, null, true, null);
         }
      } catch (ParseException e) {
         throw e;
      } catch (Exception e) {
         throw new ParseException(e);
      }
   }

   /**
    * Workhorse method.
    *
    * @param <T> The class type being parsed, or <jk>null</jk> if unknown.
    * @param eType The class type being parsed, or <jk>null</jk> if unknown.
    * @param r The reader being parsed.
    *    <br>Must not be <jk>null</jk>.
    * @param outer The outer object (for constructing nested inner classes).
    *    <br>Can be <jk>null</jk> if there is no enclosing (outer) object; the parsed object is then not linked to a parent.
    * @param isUrlParamValue
    *    If <jk>true</jk>, then we're parsing a top-level URL-encoded value which is treated a bit different than the
    *    default case.
    * @param pMeta The current bean property being parsed.
    *    <br>Can be <jk>null</jk> if no bean property metadata applies (e.g. the root value or an unknown property).
    * @return The parsed object.
    * @throws IOException Thrown by underlying stream.
    * @throws ParseException Malformed input encountered.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   public <T> T readAnything(ClassMeta<?> eType, UonReader r, Object outer, boolean isUrlParamValue, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {

      if (eType == null)
         eType = 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, isUrlParamValue, pMeta));

      setCurrentClass(sType);

      Object o = null;

      int c = r.peekSkipWs();

      if (c == -1 || c == AMP) {
         // If parameter is blank and it's an array or collection, return an empty list.
         if (sType.isCollectionOrArray())
            o = sType.newInstance();
         else if (sType.isString() || sType.isObject())
            o = "";
         else if (sType.isPrimitive())
            o = sType.getPrimitiveDefault();
         // Otherwise, leave null.
      } else if (sType.isVoid()) {
         var s = readString(r, isUrlParamValue);
         if (nn(s))
            throw new ParseException(this, "Expected 'null' for void value, but was '%s'.", s);
      } else if (sType.isObject()) {
         if (c == '(') {
            var m = newGenericMap();
            readIntoMap(r, m, string(), object(), pMeta);
            o = cast(m, pMeta, eType);
         } else if (c == '@') {
            Collection l = newGenericList();
            o = readIntoCollection(r, l, sType, isUrlParamValue, pMeta);
         } else {
            var s = readString(r, isUrlParamValue);
            if (c != '\'') {
               if ("true".equals(s) || "false".equals(s))
                  o = b(s);
               else {
                  if (isNumeric(s))
                     o = StringUtils.parseNumber(s, Number.class);
                  else
                     o = s;
               }
            } else {
               o = s;
            }
         }
      } else if (nn(builder)) {
         var m = toBeanMap(builder.create(this, eType));
         m = readIntoBeanMap(r, m);
         o = m == null ? null : builder.build(this, checkRequired(m).getBean(), eType);
      } else if (sType.canCreateNewBean(outer)) {
         var m = newBeanMap(outer, sType.inner());
         m = readIntoBeanMap(r, m);
         o = m == null ? null : checkRequired(m).getBean();
      } else if (sType.isMap()) {
         var m = (sType.canCreateNewInstance(outer) ? (Map)sType.newInstance(outer) : newGenericMap(sType));
         o = readIntoMap(r, m, sType.getKeyType(), sType.getValueType(), pMeta);
      } else if (sType.isCollection()) {
         if (c == '(') {
            var m = newGenericMap();
            readIntoMap(r, m, string(), object(), pMeta);
            // Handle case where it's a collection, but serialized as a map with a _type or _value key.
            if (m.containsKey(getBeanTypePropertyName(sType)))
               o = cast(m, pMeta, eType);
            // Handle case where it's a collection, but only a single value was specified.
            else {
               var l = (sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance(outer) : newGenericList());
               l.add(m.cast(sType.getElementType()));
               o = l;
            }
         } else {
            var l = (sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance(outer) : newGenericList());
            o = readIntoCollection(r, l, sType, isUrlParamValue, pMeta);
         }
      } else if (sType.isArray() || sType.isArgs()) {
         if (c == '(') {
            var m = newGenericMap();
            readIntoMap(r, m, string(), object(), pMeta);
            // Handle case where it's an array, but serialized as a map with a _type or _value key.
            if (m.containsKey(getBeanTypePropertyName(sType)))
               o = cast(m, pMeta, eType);
            // Handle case where it's an array, but only a single value was specified.
            else {
               var l = listOfSize(1);
               l.add(m.cast(sType.getElementType()));
               o = toArray(sType, l);
            }
         } else {
            var l = (ArrayList)readIntoCollection(r, list(), sType, isUrlParamValue, pMeta);
            o = toArray(sType, l);
         }
      } else if (sType.isCharSequence()) {
         o = readString(r, isUrlParamValue);
      } else if (sType.isChar()) {
         o = parseCharacter(readString(r, isUrlParamValue));
      } else if (sType.isNumber()) {
         o = readNumber(r, (Class<? extends Number>)sType.inner());
      } else if (sType.isBoolean()) {
         o = readBoolean(r);
      } else if (sType.isDate()) {
         o = readDate(readString(r, isUrlParamValue), sType);
      } else if (sType.isCalendar()) {
         o = readCalendar(readString(r, isUrlParamValue), sType);
      } else if (sType.isTemporal()) {
         o = readTemporal(readString(r, isUrlParamValue), sType);
      } else if (sType.isDuration()) {
         o = readDuration(readString(r, isUrlParamValue));
      } else if (sType.isPeriod()) {
         o = readPeriod(readString(r, isUrlParamValue));
      } else if (sType.canCreateNewInstanceFromString(outer)) {
         var s = readString(r, isUrlParamValue);
         if (nn(s))
            o = sType.newInstanceFromString(outer, s);
      } else if (c == '(') {
         // It could be a non-bean with _type attribute.
         var m = newGenericMap();
         readIntoMap(r, m, string(), object(), pMeta);
         if (m.containsKey(getBeanTypePropertyName(sType)))
            o = cast(m, pMeta, eType);
         else if (nn(sType.getProxyInvocationHandler()))
            o = checkRequired(newBeanMap(outer, sType.inner()).load(m)).getBean();
         else
            throw new ParseException(this, "Class '%s' could not be instantiated.  Reason: '%s'", cn(sType), sType.getNotABeanReason());
      } else if (c == 'n') {
         int ignored = r.read();
         readNull(r);
      } else {
         throw new ParseException(this, "Class '%s' could not be instantiated.  Reason: '%s'", cn(sType), sType.getNotABeanReason());
      }

      if (o == null && sType.isPrimitive())
         o = sType.getPrimitiveDefault();
      if (nn(swap) && nn(o))
         o = unswap(swap, o, eType);

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

      return (T)o;
   }

   @SuppressWarnings({
      "java:S2447" // null is a valid UON value distinct from true/false; Boolean (boxed) is deliberately used for this tristate
   })
   private Boolean readBoolean(UonReader r) throws IOException, ParseException {
      var s = readString(r, false);
      if (s == null || s.equals("null"))
         return null;
      if (eqic(s, "true"))
         return true;
      if (eqic(s, "false"))
         return false;
      throw new ParseException(this, "Unrecognized syntax for boolean.  '%s'.", s);
   }

   private <T> BeanMap<T> readIntoBeanMap(UonReader r, BeanMap<T> m) throws IOException, ParseException, ExecutableException {

      int c = r.readSkipWs();
      if (c == -1 || c == AMP)
         return null;
      if (c == 'n')
         return (BeanMap<T>)readNull(r);
      if (c != '(')
         throw new ParseException(this, "Expected '(' at beginning of object.");

      // S1: Looking for attrName start.
      // S2: Found attrName end, looking for =.
      // S3: Found =, looking for valStart.
      // S4: Looking for , or }

      var state = S1;
      var currAttr = "";
      var pb = swapParentBean(m.getBean(false));
      mark();
      try {
         while (true) {
            c = r.read();
            if (state == S1) {
               if (c == ')' || c == -1 || c == AMP) {
                  return m;
               }
               if (Character.isWhitespace(c))
                  skipSpace(r);
               else {
                  r.unread();
                  mark();
                  currAttr = readAttrName(r, decoding);
                  if (currAttr == null) { // Value was '%00'
                     return null;
                  }
                  state = S2;
               }
            } else if (state == S2) {
               if (c == EQ || c == '=')
                  state = S3;
               else if (c == -1 || c == ',' || c == ')' || c == AMP) {
                  m.put(currAttr, null);
                  if (c == ')' || c == -1 || c == AMP) {
                     return m;
                  }
                  state = S1;
               }
            } else if (state == S3) {
               if (c == -1 || c == ',' || c == ')' || c == AMP) {
                  if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
                     var pMeta = m.getPropertyMeta(currAttr);
                     if (pMeta == null) {
                        onUnknownProperty(currAttr, m, null);
                        unmark();
                     } else {
                        unmark();
                        var value = convertToType("", (ClassMeta<?>) pMeta.getBeanInfo());
                        try {
                           pMeta.set(m, currAttr, value);
                        } catch (BeanRuntimeException e) {
                           onBeanSetterException(pMeta, e);
                           throw e;
                        }
                     }
                  }
                  if (c == -1 || c == ')' || c == AMP)
                     return m;
                  state = S1;
               } else {
                  if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
                     var pMeta = m.getPropertyMeta(currAttr);
                     if (pMeta == null) {
                        onUnknownProperty(currAttr, m, readAnything(object(), r.unread(), m.getBean(false), false, null));
                        unmark();
                     } else {
                        unmark();
                        setCurrentProperty(pMeta);
                        var cm = (ClassMeta<?>) pMeta.getBeanInfo();
                        var value = readAnything(cm, r.unread(), m.getBean(false), false, pMeta);
                        setName(cm, value, currAttr);
                        try {
                           pMeta.set(m, currAttr, value);
                        } catch (BeanRuntimeException e) {
                           onBeanSetterException(pMeta, e);
                           throw e;
                        }
                        setCurrentProperty(null);
                     }
                  }
                  state = S4;
               }
            } else if (state == S4) {
               if (c == ',')
                  state = S1;
               else if (c == ')' || c == -1 || c == AMP) {
                  return m;
               }
            }
         }
      } finally {
         unmark();
         swapParentBean(pb);
      }
   }

   @SuppressWarnings({
      "java:S1854", // argIndex=0 is the valid starting arg index; Sonar FP on early-return paths that never read it
      "java:S2589" // Final if (state==S3) is always true given prior check; exhaustive state error-reporting pattern
   })
   private <E> Collection<E> readIntoCollection(UonReader r, Collection<E> l, ClassMeta<E> type, boolean isUrlParamValue, BeanPropertyMeta pMeta)
      throws IOException, ParseException, ExecutableException {

      int c = r.readSkipWs();
      if (c == -1 || c == AMP)
         return null;
      if (c == 'n')
         return (Collection<E>)readNull(r);

      int argIndex = 0;

      // If we're parsing a top-level parameter, we're allowed to have comma-delimited lists outside parenthesis (e.g. "&foo=1,2,3&bar=a,b,c")
      // This is not allowed at lower levels since we use comma's as end delimiters.
      boolean isInParens = (c == '@');
      if (! isInParens) {
         if (isUrlParamValue)
            r.unread();
         else
            throw new ParseException(this, "Could not find '(' marking beginning of collection.");
      } else {
         int ignored = r.read();
      }

      if (isInParens) {
         // S1: Looking for starting of first entry.
         // S2: Looking for starting of subsequent entries.
         // S3: Looking for , or ) after first entry.

         var state = S1;
         while (c != -1 && c != AMP) {
            c = r.read();
            if (state == S1 || state == S2) {
               if (c == ')') {
                  if (state == S2) {
                     l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, false, pMeta));
                     int ignored = r.read();
                  }
                  return l;
               } else if (Character.isWhitespace(c)) {
                  skipSpace(r);
               } else {
                  l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, false, pMeta));
                  state = S3;
               }
            } else if (state == S3) {
               if (c == ',') {
                  state = S2;
               } else if (c == ')') {
                  return l;
               }
            }
         }
         if (state == S1 || state == S2)
            throw new ParseException(this, "Could not find start of entry in array.");
         if (state == S3)
            throw new ParseException(this, "Could not find end of entry in array.");

      } else {
         // S1: Looking for starting of entry.
         // S2: Looking for , or & or END after first entry.

         var state = S1;
         while (c != -1 && c != AMP) {
            c = r.read();
            if (state == S1) {
               if (Character.isWhitespace(c)) {
                  skipSpace(r);
               } else {
                  l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, false, pMeta));
                  state = S2;
               }
            } else if (state == S2) {
               if (c == ',') {
                  state = S1;
               } else if (Character.isWhitespace(c)) {
                  skipSpace(r);
               } else if (c == AMP || c == -1) {
                  r.unread();
                  return l;
               }
            }
         }
      }

      return null;  // Unreachable.
   }

   private <K,V> Map<K,V> readIntoMap(UonReader r, Map<K,V> m, ClassMeta<K> keyType, ClassMeta<V> valueType, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {

      if (keyType == null)
         keyType = (ClassMeta<K>)string();

      int c = r.read();
      if (c == -1 || c == AMP)
         return null;
      if (c == 'n')
         return (Map<K,V>)readNull(r);
      if (c != '(')
         throw new ParseException(this, "Expected '(' at beginning of object.");

      // S1: Looking for attrName start.
      // S2: Found attrName end, looking for =.
      // S3: Found =, looking for valStart.
      // S4: Looking for , or )

      var state = S1;
      K currAttr = null;
      while (c != -1 && c != AMP) {
         c = r.read();
         if (state == S1) {
            if (c == ')')
               return m;
            if (Character.isWhitespace(c))
               skipSpace(r);
            else {
               r.unread();
               var attr = readAttr(r, decoding);
               currAttr = attr == null ? null : convertAttrToType(m, trim(attr.toString()), keyType);
               state = S2;
            }
         } else if (state == S2) {
            if (c == EQ || c == '=')
               state = S3;
            else if (c == -1 || c == ',' || c == ')' || c == AMP) {
               if (currAttr == null) {
                  // Value was '%00'
                  r.unread();
                  return null;
               }
               m.put(currAttr, null);
               if (c == ')' || c == -1 || c == AMP)
                  return m;
               state = S1;
            }
         } else if (state == S3) {
            if (c == -1 || c == ',' || c == ')' || c == AMP) {
               V value = convertAttrToType(m, "", valueType);
               m.put(currAttr, value);
               if (c == -1 || c == ')' || c == AMP)
                  return m;
               state = S1;
            } else {
               V value = readAnything(valueType, r.unread(), m, false, pMeta);
               setName(valueType, value, currAttr);
               m.put(currAttr, value);
               state = S4;
            }
         } else if (state == S4) {
            if (c == ',')
               state = S1;
            else if (c == ')' || c == -1 || c == AMP) {
               return m;
            }
         }
      }

      return null; // Reachable via trailing comma at EOF (lenient parse of e.g. "(a=1,").
   }

   private Object readNull(UonReader r) throws IOException, ParseException {
      var s = readString(r, false);
      if ("ull".equals(s))
         return null;
      throw new ParseException(this, "Unexpected character sequence: '%s'", s);
   }

   private Number readNumber(UonReader r, Class<? extends Number> c) throws IOException, ParseException {
      var s = readString(r, false);
      if (s == null)
         return null;
      return StringUtils.parseNumber(s, c);
   }

   /*
    * Parses a string of the form "'foo'"
    * All whitespace within parenthesis are preserved.
    */
   private String readPString(UonReader r) throws IOException, ParseException {

      int ignored = r.read();
      r.mark();
      int c = 0;

      boolean isInEscape = false;
      while (c != -1) {
         c = r.read();
         if (! isInEscape && c == '\'')
            return trim(r.getMarked(0, -1));
         if (c == EQ)
            r.replace('=');
         isInEscape = isInEscape(c, r, isInEscape);
      }
      throw new ParseException(this, "Unmatched parenthesis");
   }

   /*
    * Call this method after you've finished a parsing a string to make sure that if there's any
    * remainder in the input, that it consists only of whitespace and comments.
    */
   private void validateEnd(UonReader r) throws IOException, ParseException {
      if (! isValidateEnd())
         return;
      while (true) {
         var c = r.read();
         if (c == -1)
            return;
         if (! Character.isWhitespace(c))
            throw new ParseException(this, "Remainder after parse: '%s'.", (char)c);
      }
   }

   @Override /* Overridden from ParserSession */
   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
      try (var r = getUonReader(pipe, decoding)) {
         T o = readAnything(type, r, getOuter(), true, null);
         validateEnd(r);
         return o;
      }
   }

   @Override /* Overridden from ReaderParserSession */
   protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws Exception {
      try (var r = getUonReader(pipe, decoding)) {
         c = readIntoCollection(r, c, (ClassMeta<E>)getClassMeta(elementType), false, null);
         validateEnd(r);
         return c;
      }
   }

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

   /**
    * Decode <js>"%xx"</js> sequences.
    *
    * @see UonParser.Builder#decoding()
    * @return
    *    <jk>true</jk> if URI encoded characters should be decoded, <jk>false</jk> if they've already been decoded
    *    before being passed to this parser.
    */
   protected final boolean isDecoding() { return decoding; }

   /**
    * Validate end.
    *
    * @see UonParser.Builder#validateEnd()
    * @return
    *    <jk>true</jk> if after parsing a POJO from the input, verifies that the remaining input in
    *    the stream consists of only comments or whitespace.
    */
   protected final boolean isValidateEnd() { return validateEnd; }

   /**
    * Convenience method for parsing an attribute from the specified parser.
    *
    * @param r The reader.
    *    <br>Must not be <jk>null</jk>.
    * @param encoded Whether the attribute is encoded.
    * @return The parsed object, or <jk>null</jk> if the attribute was the literal <js>"null"</js>.
    * @throws IOException Exception thrown by underlying stream.
    * @throws ParseException Attribute was malformed.
    */
   protected final Object readAttr(UonReader r, boolean encoded) throws IOException, ParseException {
      return readAttrName(r, encoded);
   }

   /**
    * Parses an attribute name from the specified reader.
    *
    * @param r The reader.
    *    <br>Must not be <jk>null</jk>.
    * @param encoded Whether the attribute is encoded.
    * @return The parsed attribute name, or <jk>null</jk> if the attribute name was the literal <js>"null"</js>.
    * @throws IOException Exception thrown by underlying stream.
    * @throws ParseException Attribute name was malformed.
    */
   protected final String readAttrName(UonReader r, boolean encoded) throws IOException, ParseException {

      // If string is of form 'xxx', we're looking for ' at the end.
      // Otherwise, we're looking for '&' or '=' or WS or -1 denoting the end of this string.

      int c = r.peekSkipWs();
      if (c == '\'')
         return readPString(r);

      r.mark();
      boolean isInEscape = false;
      if (encoded) {
         while (true) {
            c = r.read();
            if (! isInEscape) {
               if (c == AMP || c == EQ || c == -1 || Character.isWhitespace(c)) {
                  if (c != -1)
                     r.unread();
                  var s = r.getMarked();
                  return ("null".equals(s) ? null : s);
               }
            } else if (c == AMP)
               r.replace('&');
            else if (c == EQ)
               r.replace('=');
            isInEscape = isInEscape(c, r, isInEscape);
         }
      } else {
         while (true) {
            c = r.read();
            if (! isInEscape && (c == '=' || c == -1 || Character.isWhitespace(c))) {
               if (c != -1)
                  r.unread();
               var s = r.getMarked();
               return ("null".equals(s) ? null : trim(s));
            }
            isInEscape = isInEscape(c, r, isInEscape);
         }
      }
   }

   /**
    * Parses a string value from the specified reader.
    *
    * @param r The input reader.
    *    <br>Must not be <jk>null</jk>.
    * @param isUrlParamValue Whether this is a URL parameter.
    * @return The parsed string, or <jk>null</jk> if the value was the literal <js>"null"</js>.
    * @throws IOException Exception thrown by underlying stream.
    * @throws ParseException Malformed input found.
    */
   protected final String readString(UonReader r, boolean isUrlParamValue) throws IOException, ParseException {

      // If string is of form 'xxx', we're looking for ' at the end.
      // Otherwise, we're looking for ',' or ')' or -1 denoting the end of this string.

      int c = r.peekSkipWs();
      if (c == '\'')
         return readPString(r);

      r.mark();
      boolean isInEscape = false;
      String s = null;
      var endChars = (isUrlParamValue ? endCharsParam : endCharsNormal);
      while (c != -1) {
         c = r.read();
         if (! isInEscape && endChars.contains(c)) {
            // If this is a URL parameter value, we're looking for:  &
            // If not, we're looking for:  &,)
            r.unread();
            c = -1;
         }
         if (c == -1)
            s = r.getMarked();
         else if (c == EQ)
            r.replace('=');
         else if (Character.isWhitespace(c) && ! isUrlParamValue) {
            s = r.getMarked(0, -1);
            skipSpace(r);
            c = -1;
         }
         isInEscape = isInEscape(c, r, isInEscape);
      }

      if (isUrlParamValue)
         s = StringUtils.trim(s);

      return ("null".equals(s) ? null : trim(s));
   }

   @Override /* Overridden from ReaderParserSession */
   protected FluentMap<String,Object> properties() {
      return super.properties()
         .a("decoding", decoding)
         .a("validateEnd", validateEnd);
   }
}