001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.uon;
018
019import static org.apache.juneau.commons.lang.StateEnum.*;
020import static org.apache.juneau.commons.utils.CollectionUtils.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022import static org.apache.juneau.commons.utils.StringUtils.*;
023
024import java.io.*;
025import java.lang.reflect.*;
026import java.util.*;
027
028import org.apache.juneau.commons.bean.*;
029import org.apache.juneau.commons.collections.*;
030import org.apache.juneau.commons.httppart.*;
031import org.apache.juneau.commons.lang.*;
032import org.apache.juneau.commons.reflect.*;
033import org.apache.juneau.commons.utils.*;
034import org.apache.juneau.marshall.*;
035import org.apache.juneau.marshall.httppart.*;
036import org.apache.juneau.marshall.parser.*;
037import org.apache.juneau.marshall.stream.*;
038import org.apache.juneau.marshall.swap.spi.*;
039
040/**
041 * Session object that lives for the duration of a single use of {@link UonParser}.
042 *
043 * <h2 class='section'>Notes:</h2><ul>
044 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
045 * </ul>
046 *
047 * <h2 class='section'>See Also:</h2><ul>
048 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/UonSupport">UON</a>
049
050 * </ul>
051 */
052@SuppressWarnings({
053   "java:S110", // Deep inheritance inherent to the serializer/parser session hierarchy
054   "java:S115", // Constants use UPPER_snakeCase convention (e.g., CONST_value)
055   "java:S125", // State-machine comments are documentation, not commented-out code
056   "java:S1168", // readIntoMap()/readIntoCollection()/readIntoBeanMap() return null for blank, literal null or '%00' input, which callers treat as 'no value'.
057   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
058   "java:S2583", // The post-loop state checks in readIntoCollection() look constant to static analysis but are reachable when input ends mid-entry.
059   "java:S3776", // readAnything() and the readInto*() methods are state machines over the UON grammar; splitting them would obscure the parse flow.
060   "java:S6541", // readAnything() is the single type-dispatch point of the parser and is long by design.
061   "rawtypes", // Raw types necessary for generic type handling
062   "resource", // UonReader is managed by caller
063   "unchecked", // Type erasure requires unchecked casts
064   "unused" // Intentionally unused; variable/parameter is required by the interface contract
065})
066public class UonParserSession extends ReaderParserSession implements HttpPartParserSession, RecordReadable {
067
068   /**
069    * Builder class.
070    */
071   @SuppressWarnings({
072      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
073   })
074   public abstract static class Builder<SELF extends Builder<SELF>> extends ReaderParserSession.Builder<SELF> {
075
076      private boolean decoding;
077      private boolean validateEnd;
078
079      /**
080       * Constructor
081       *
082       * @param ctx The context creating this session.
083       */
084      protected Builder(UonParser ctx) {
085         super(ctx);
086         decoding = ctx.decoding;
087         validateEnd = ctx.isValidateEnd();
088      }
089
090      @Override
091      public UonParserSession build() {
092         return new UonParserSession(this);
093      }
094
095      /**
096       * Overrides the decoding flag on the context for this session.
097       *
098       * @param value The new value for this setting.
099       * @return This object.
100       */
101      public SELF decoding(boolean value) {
102         decoding = value;
103         return self();
104      }
105
106      @Override /* Overridden from Builder */
107      public SELF property(String key, Object value) {
108         if (key == null) { super.property(key, value); return self(); }
109         switch (key) {
110            case "decoding":
111               return decoding(cvt(value, Boolean.class));
112            case "validateEnd", "UonParserSession.validateEnd":
113               return validateEnd(cvt(value, Boolean.class));
114            default:
115               super.property(key, value);
116               return self();
117         }
118      }
119
120      /**
121       * Validate end.
122       *
123       * @param value The new value for this setting.
124       * @return This object.
125       */
126      public SELF validateEnd(boolean value) {
127         validateEnd = value;
128         return self();
129      }
130
131   }
132
133   /**
134    * Concrete default builder leaf for the non-subclassed {@code create()} path (CRTP terminal).
135    */
136   public static final class DefaultBuilder extends Builder<DefaultBuilder> {
137
138      DefaultBuilder(UonParser ctx) {
139         super(ctx);
140      }
141   }
142
143   // Characters that need to be preceded with an escape character.
144   private static final AsciiSet escapedChars = AsciiSet.of("~'\u0001\u0002");
145
146   private static final char AMP = '\u0001';  // Flags set in reader to denote & and = characters.
147   private static final char EQ = '\u0002';
148   private static final AsciiSet endCharsParam = AsciiSet.of("" + AMP);
149   private static final AsciiSet endCharsNormal = AsciiSet.of(",)" + AMP);
150
151   /**
152    * Creates a new builder for this object.
153    *
154    * @param ctx The context creating this session.
155    * @return A new builder.
156    */
157   @SuppressWarnings({
158      "java:S1452" // Builder<?> wildcard return intentional; callers use it to construct session instances polymorphically
159   })
160   public static Builder<?> create(UonParser ctx) {
161      return new DefaultBuilder(ctx);
162   }
163
164   /*
165    * Returns true if the next character in the stream is preceded by an escape '~' character.
166    */
167   private static final boolean isInEscape(int c, ParserReader r, boolean prevIsInEscape) throws IOException {
168      if (c == '~' && ! prevIsInEscape) {
169         c = r.peek();
170         if (escapedChars.contains(c)) {
171            r.delete();
172            return true;
173         }
174      }
175      return false;
176   }
177
178   private static void skipSpace(ParserReader r) throws IOException {
179      int c = 0;
180      while ((c = r.read()) != -1) {
181         if (c <= 2 || ! Character.isWhitespace(c)) {
182            r.unread();
183            return;
184         }
185      }
186   }
187
188   private final boolean decoding;
189   private final boolean validateEnd;
190
191   /**
192    * Constructor.
193    *
194    * @param builder The builder for this object.
195    */
196   protected UonParserSession(Builder<?> builder) {
197      super(builder);
198      decoding = builder.decoding;
199      validateEnd = builder.validateEnd;
200   }
201
202   @Override /* RecordReadable */
203   public RecordReader readRecords(Object input) throws IOException {
204      return RecordAdapter.reader(this, input);
205   }
206
207   @Override /* RecordReadable */
208   public boolean isRecordStreaming() {
209      return false;
210   }
211
212   /**
213    * Creates a {@link UonReader} from the specified parser pipe.
214    *
215    * @param pipe The parser input.
216    * @param decodeChars Whether the reader should automatically decode URL-encoded characters.
217    * @return A new {@link UonReader} object.
218    * @throws IOException Thrown by underlying stream.
219    */
220   public static final UonReader getUonReader(ParserPipe pipe, boolean decodeChars) throws IOException {
221      var r = pipe.getReader();
222      if (r instanceof UonReader r2)
223         return r2;
224      return new UonReader(pipe, decodeChars);
225   }
226
227   @Override /* Overridden from HttpPartParser */
228   public <T> T read(HttpPartType partType, HttpPartSchema schema, String in, ClassMeta<T> toType) throws ParseException, SchemaValidationException {
229      if (in == null)
230         return null;
231      if (toType.isString() && ine(in)) {
232         // Shortcut - If we're returning a string and the value doesn't start with "'" or is "null", then
233         // just return the string since it's a plain value.
234         // This allows us to bypass the creation of a UonParserSession object.
235         char x = firstNonWhitespaceChar(in);
236         if (x != '\'' && x != 'n' && in.indexOf('~') == -1)
237            return (T)in;
238         if (x == 'n' && "null".equals(in))
239            return null;
240      }
241      try (var pipe = createPipe(in)) {
242         try (var r = getUonReader(pipe, false)) {
243            return readAnything(toType, r, null, true, null);
244         }
245      } catch (ParseException e) {
246         throw e;
247      } catch (Exception e) {
248         throw new ParseException(e);
249      }
250   }
251
252   /**
253    * Workhorse method.
254    *
255    * @param <T> The class type being parsed, or <jk>null</jk> if unknown.
256    * @param eType The class type being parsed, or <jk>null</jk> if unknown.
257    * @param r The reader being parsed.
258    *    <br>Must not be <jk>null</jk>.
259    * @param outer The outer object (for constructing nested inner classes).
260    *    <br>Can be <jk>null</jk> if there is no enclosing (outer) object; the parsed object is then not linked to a parent.
261    * @param isUrlParamValue
262    *    If <jk>true</jk>, then we're parsing a top-level URL-encoded value which is treated a bit different than the
263    *    default case.
264    * @param pMeta The current bean property being parsed.
265    *    <br>Can be <jk>null</jk> if no bean property metadata applies (e.g. the root value or an unknown property).
266    * @return The parsed object.
267    * @throws IOException Thrown by underlying stream.
268    * @throws ParseException Malformed input encountered.
269    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
270    */
271   public <T> T readAnything(ClassMeta<?> eType, UonReader r, Object outer, boolean isUrlParamValue, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {
272      enterParseDepth();
273      try {
274         return readAnything0(eType, r, outer, isUrlParamValue, pMeta);
275      } finally {
276         exitParseDepth();
277      }
278   }
279
280   // Workhorse method, wrapped by readAnything() with the recursion-depth guard.
281   private <T> T readAnything0(ClassMeta<?> eType, UonReader r, Object outer, boolean isUrlParamValue, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {
282
283      if (eType == null)
284         eType = object();
285      var swap = (ObjectSwap<T,Object>)eType.getSwap(this);
286      var builder = (BuilderSwap<T,Object>)eType.getBuilderSwap(this);
287      ClassMeta<?> sType = null;
288      if (nn(builder))
289         sType = builder.getBuilderClassMeta(this);
290      else if (nn(swap))
291         sType = swap.getSwapClassMeta(this);
292      else
293         sType = eType;
294
295      if (sType.isOptional())
296         return (T)o(readAnything(eType.getElementType(), r, outer, isUrlParamValue, pMeta));
297
298      setCurrentClass(sType);
299
300      Object o = null;
301
302      int c = r.peekSkipWs();
303
304      if (c == -1 || c == AMP) {
305         // If parameter is blank and it's an array or collection, return an empty list.
306         if (sType.isCollectionOrArray())
307            o = sType.newInstance();
308         else if (sType.isString() || sType.isObject())
309            o = "";
310         else if (sType.isPrimitive())
311            o = sType.getPrimitiveDefault();
312         // Otherwise, leave null.
313      } else if (sType.isVoid()) {
314         var s = readString(r, isUrlParamValue);
315         if (nn(s))
316            throw new ParseException(this, "Expected 'null' for void value, but was '%s'.", s);
317      } else if (sType.isObject()) {
318         if (c == '(') {
319            var m = newGenericMap();
320            readIntoMap(r, m, string(), object(), pMeta);
321            o = cast(m, pMeta, eType);
322         } else if (c == '@') {
323            Collection l = newGenericList();
324            o = readIntoCollection(r, l, sType, isUrlParamValue, pMeta);
325         } else {
326            var s = readString(r, isUrlParamValue);
327            if (c != '\'') {
328               if ("true".equals(s) || "false".equals(s))
329                  o = b(s);
330               else {
331                  if (isNumeric(s))
332                     o = StringUtils.parseNumber(s, Number.class);
333                  else
334                     o = s;
335               }
336            } else {
337               o = s;
338            }
339         }
340      } else if (nn(builder)) {
341         var m = toBeanMap(builder.create(this, eType));
342         m = readIntoBeanMap(r, m);
343         o = m == null ? null : builder.build(this, checkRequired(m).getBean(), eType);
344      } else if (sType.canCreateNewBean(outer)) {
345         var m = newBeanMap(outer, sType.inner());
346         m = readIntoBeanMap(r, m);
347         o = m == null ? null : checkRequired(m).getBean();
348      } else if (sType.isMap()) {
349         var m = (sType.canCreateNewInstance(outer) ? (Map)sType.newInstance(outer) : newGenericMap(sType));
350         o = readIntoMap(r, m, sType.getKeyType(), sType.getValueType(), pMeta);
351      } else if (sType.isCollection()) {
352         if (c == '(') {
353            var m = newGenericMap();
354            readIntoMap(r, m, string(), object(), pMeta);
355            // Handle case where it's a collection, but serialized as a map with a _type or _value key.
356            if (m.containsKey(getBeanTypePropertyName(sType)))
357               o = cast(m, pMeta, eType);
358            // Handle case where it's a collection, but only a single value was specified.
359            else {
360               var l = (sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance(outer) : newGenericList());
361               l.add(m.cast(sType.getElementType()));
362               o = l;
363            }
364         } else {
365            var l = (sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance(outer) : newGenericList());
366            o = readIntoCollection(r, l, sType, isUrlParamValue, pMeta);
367         }
368      } else if (sType.isArray() || sType.isArgs()) {
369         if (c == '(') {
370            var m = newGenericMap();
371            readIntoMap(r, m, string(), object(), pMeta);
372            // Handle case where it's an array, but serialized as a map with a _type or _value key.
373            if (m.containsKey(getBeanTypePropertyName(sType)))
374               o = cast(m, pMeta, eType);
375            // Handle case where it's an array, but only a single value was specified.
376            else {
377               var l = listOfSize(1);
378               l.add(m.cast(sType.getElementType()));
379               o = toArray(sType, l);
380            }
381         } else {
382            var l = (ArrayList)readIntoCollection(r, list(), sType, isUrlParamValue, pMeta);
383            o = toArray(sType, l);
384         }
385      } else if (sType.isCharSequence()) {
386         o = readString(r, isUrlParamValue);
387      } else if (sType.isChar()) {
388         o = parseCharacter(readString(r, isUrlParamValue));
389      } else if (sType.isNumber()) {
390         o = readNumber(r, (Class<? extends Number>)sType.inner());
391      } else if (sType.isBoolean()) {
392         o = readBoolean(r);
393      } else if (sType.isDate()) {
394         o = readDate(readString(r, isUrlParamValue), sType);
395      } else if (sType.isCalendar()) {
396         o = readCalendar(readString(r, isUrlParamValue), sType);
397      } else if (sType.isTemporal()) {
398         o = readTemporal(readString(r, isUrlParamValue), sType);
399      } else if (sType.isDuration()) {
400         o = readDuration(readString(r, isUrlParamValue));
401      } else if (sType.isPeriod()) {
402         o = readPeriod(readString(r, isUrlParamValue));
403      } else if (sType.canCreateNewInstanceFromString(outer)) {
404         var s = readString(r, isUrlParamValue);
405         if (nn(s))
406            o = sType.newInstanceFromString(outer, s);
407      } else if (c == '(') {
408         // It could be a non-bean with _type attribute.
409         var m = newGenericMap();
410         readIntoMap(r, m, string(), object(), pMeta);
411         if (m.containsKey(getBeanTypePropertyName(sType)))
412            o = cast(m, pMeta, eType);
413         else if (nn(sType.getProxyInvocationHandler()))
414            o = checkRequired(newBeanMap(outer, sType.inner()).load(m)).getBean();
415         else
416            throw new ParseException(this, "Class '%s' could not be instantiated.  Reason: '%s'", cn(sType), sType.getNotABeanReason());
417      } else if (c == 'n') {
418         int ignored = r.read();
419         readNull(r);
420      } else {
421         throw new ParseException(this, "Class '%s' could not be instantiated.  Reason: '%s'", cn(sType), sType.getNotABeanReason());
422      }
423
424      if (o == null && sType.isPrimitive())
425         o = sType.getPrimitiveDefault();
426      if (nn(swap) && nn(o))
427         o = unswap(swap, o, eType);
428
429      if (nn(parentBean()))
430         setParent(eType, o, parentBean());
431
432      return (T)o;
433   }
434
435   @SuppressWarnings({
436      "java:S2447" // null is a valid UON value distinct from true/false; Boolean (boxed) is deliberately used for this tristate
437   })
438   private Boolean readBoolean(UonReader r) throws IOException, ParseException {
439      var s = readString(r, false);
440      if (s == null || s.equals("null"))
441         return null;
442      if (eqic(s, "true"))
443         return true;
444      if (eqic(s, "false"))
445         return false;
446      throw new ParseException(this, "Unrecognized syntax for boolean.  '%s'.", s);
447   }
448
449   private <T> BeanMap<T> readIntoBeanMap(UonReader r, BeanMap<T> m) throws IOException, ParseException, ExecutableException {
450
451      int c = r.readSkipWs();
452      if (c == -1 || c == AMP)
453         return null;
454      if (c == 'n')
455         return (BeanMap<T>)readNull(r);
456      if (c != '(')
457         throw new ParseException(this, "Expected '(' at beginning of object.");
458
459      // S1: Looking for attrName start.
460      // S2: Found attrName end, looking for =.
461      // S3: Found =, looking for valStart.
462      // S4: Looking for , or }
463
464      var state = S1;
465      var currAttr = "";
466      var pb = swapParentBean(m.getBean(false));
467      mark();
468      try {
469         while (true) {
470            c = r.read();
471            if (state == S1) {
472               if (c == ')' || c == -1 || c == AMP) {
473                  return m;
474               }
475               if (Character.isWhitespace(c))
476                  skipSpace(r);
477               else {
478                  r.unread();
479                  mark();
480                  currAttr = readAttrName(r, decoding);
481                  if (currAttr == null) { // Value was '%00'
482                     return null;
483                  }
484                  state = S2;
485               }
486            } else if (state == S2) {
487               if (c == EQ || c == '=')
488                  state = S3;
489               else if (c == -1 || c == ',' || c == ')' || c == AMP) {
490                  m.put(currAttr, null);
491                  if (c == ')' || c == -1 || c == AMP) {
492                     return m;
493                  }
494                  state = S1;
495               }
496            } else if (state == S3) {
497               if (c == -1 || c == ',' || c == ')' || c == AMP) {
498                  if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
499                     var pMeta = m.getPropertyMeta(currAttr);
500                     if (pMeta == null) {
501                        onUnknownProperty(currAttr, m, null);
502                        unmark();
503                     } else {
504                        unmark();
505                        var value = convertToType("", (ClassMeta<?>) pMeta.getBeanInfo());
506                        try {
507                           pMeta.set(m, currAttr, value);
508                        } catch (BeanRuntimeException e) {
509                           onBeanSetterException(pMeta, e);
510                           throw e;
511                        }
512                     }
513                  }
514                  if (c == -1 || c == ')' || c == AMP)
515                     return m;
516                  state = S1;
517               } else {
518                  if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
519                     var pMeta = m.getPropertyMeta(currAttr);
520                     if (pMeta == null) {
521                        onUnknownProperty(currAttr, m, readAnything(object(), r.unread(), m.getBean(false), false, null));
522                        unmark();
523                     } else {
524                        unmark();
525                        setCurrentProperty(pMeta);
526                        var cm = (ClassMeta<?>) pMeta.getBeanInfo();
527                        var value = readAnything(cm, r.unread(), m.getBean(false), false, pMeta);
528                        setName(cm, value, currAttr);
529                        try {
530                           pMeta.set(m, currAttr, value);
531                        } catch (BeanRuntimeException e) {
532                           onBeanSetterException(pMeta, e);
533                           throw e;
534                        }
535                        setCurrentProperty(null);
536                     }
537                  }
538                  state = S4;
539               }
540            } else if (state == S4) {
541               if (c == ',')
542                  state = S1;
543               else if (c == ')' || c == -1 || c == AMP) {
544                  return m;
545               }
546            }
547         }
548      } finally {
549         unmark();
550         swapParentBean(pb);
551      }
552   }
553
554   @SuppressWarnings({
555      "java:S1854", // argIndex=0 is the valid starting arg index; Sonar FP on early-return paths that never read it
556      "java:S2589" // Final if (state==S3) is always true given prior check; exhaustive state error-reporting pattern
557   })
558   private <E> Collection<E> readIntoCollection(UonReader r, Collection<E> l, ClassMeta<E> type, boolean isUrlParamValue, BeanPropertyMeta pMeta)
559      throws IOException, ParseException, ExecutableException {
560
561      int c = r.readSkipWs();
562      if (c == -1 || c == AMP)
563         return null;
564      if (c == 'n')
565         return (Collection<E>)readNull(r);
566
567      int argIndex = 0;
568
569      // 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")
570      // This is not allowed at lower levels since we use comma's as end delimiters.
571      boolean isInParens = (c == '@');
572      if (! isInParens) {
573         if (isUrlParamValue)
574            r.unread();
575         else
576            throw new ParseException(this, "Could not find '(' marking beginning of collection.");
577      } else {
578         int ignored = r.read();
579      }
580
581      if (isInParens) {
582         // S1: Looking for starting of first entry.
583         // S2: Looking for starting of subsequent entries.
584         // S3: Looking for , or ) after first entry.
585
586         var state = S1;
587         while (c != -1 && c != AMP) {
588            c = r.read();
589            if (state == S1 || state == S2) {
590               if (c == ')') {
591                  if (state == S2) {
592                     l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, false, pMeta));
593                     int ignored = r.read();
594                  }
595                  return l;
596               } else if (Character.isWhitespace(c)) {
597                  skipSpace(r);
598               } else {
599                  l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, false, pMeta));
600                  state = S3;
601               }
602            } else if (state == S3) {
603               if (c == ',') {
604                  state = S2;
605               } else if (c == ')') {
606                  return l;
607               }
608            }
609         }
610         if (state == S1 || state == S2)
611            throw new ParseException(this, "Could not find start of entry in array.");
612         if (state == S3)
613            throw new ParseException(this, "Could not find end of entry in array.");
614
615      } else {
616         // S1: Looking for starting of entry.
617         // S2: Looking for , or & or END after first entry.
618
619         var state = S1;
620         while (c != -1 && c != AMP) {
621            c = r.read();
622            if (state == S1) {
623               if (Character.isWhitespace(c)) {
624                  skipSpace(r);
625               } else {
626                  l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, false, pMeta));
627                  state = S2;
628               }
629            } else if (state == S2) {
630               if (c == ',') {
631                  state = S1;
632               } else if (Character.isWhitespace(c)) {
633                  skipSpace(r);
634               } else if (c == AMP || c == -1) {
635                  r.unread();
636                  return l;
637               }
638            }
639         }
640      }
641
642      return null;  // Unreachable.
643   }
644
645   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 {
646
647      if (keyType == null)
648         keyType = (ClassMeta<K>)string();
649
650      int c = r.read();
651      if (c == -1 || c == AMP)
652         return null;
653      if (c == 'n')
654         return (Map<K,V>)readNull(r);
655      if (c != '(')
656         throw new ParseException(this, "Expected '(' at beginning of object.");
657
658      // S1: Looking for attrName start.
659      // S2: Found attrName end, looking for =.
660      // S3: Found =, looking for valStart.
661      // S4: Looking for , or )
662
663      var state = S1;
664      K currAttr = null;
665      while (c != -1 && c != AMP) {
666         c = r.read();
667         if (state == S1) {
668            if (c == ')')
669               return m;
670            if (Character.isWhitespace(c))
671               skipSpace(r);
672            else {
673               r.unread();
674               var attr = readAttr(r, decoding);
675               currAttr = attr == null ? null : convertAttrToType(m, trim(attr.toString()), keyType);
676               state = S2;
677            }
678         } else if (state == S2) {
679            if (c == EQ || c == '=')
680               state = S3;
681            else if (c == -1 || c == ',' || c == ')' || c == AMP) {
682               if (currAttr == null) {
683                  // Value was '%00'
684                  r.unread();
685                  return null;
686               }
687               m.put(currAttr, null);
688               if (c == ')' || c == -1 || c == AMP)
689                  return m;
690               state = S1;
691            }
692         } else if (state == S3) {
693            if (c == -1 || c == ',' || c == ')' || c == AMP) {
694               V value = convertAttrToType(m, "", valueType);
695               m.put(currAttr, value);
696               if (c == -1 || c == ')' || c == AMP)
697                  return m;
698               state = S1;
699            } else {
700               V value = readAnything(valueType, r.unread(), m, false, pMeta);
701               setName(valueType, value, currAttr);
702               m.put(currAttr, value);
703               state = S4;
704            }
705         } else if (state == S4) {
706            if (c == ',')
707               state = S1;
708            else if (c == ')' || c == -1 || c == AMP) {
709               return m;
710            }
711         }
712      }
713
714      return null; // Reachable via trailing comma at EOF (lenient parse of e.g. "(a=1,").
715   }
716
717   private Object readNull(UonReader r) throws IOException, ParseException {
718      var s = readString(r, false);
719      if ("ull".equals(s))
720         return null;
721      throw new ParseException(this, "Unexpected character sequence: '%s'", s);
722   }
723
724   private Number readNumber(UonReader r, Class<? extends Number> c) throws IOException, ParseException {
725      var s = readString(r, false);
726      if (s == null)
727         return null;
728      return StringUtils.parseNumber(s, c);
729   }
730
731   /*
732    * Parses a string of the form "'foo'"
733    * All whitespace within parenthesis are preserved.
734    */
735   private String readPString(UonReader r) throws IOException, ParseException {
736
737      int ignored = r.read();
738      r.mark();
739      int c = 0;
740
741      boolean isInEscape = false;
742      while (c != -1) {
743         c = r.read();
744         if (! isInEscape && c == '\'')
745            return trim(r.getMarked(0, -1));
746         if (c == EQ)
747            r.replace('=');
748         isInEscape = isInEscape(c, r, isInEscape);
749      }
750      throw new ParseException(this, "Unmatched parenthesis");
751   }
752
753   /*
754    * Call this method after you've finished a parsing a string to make sure that if there's any
755    * remainder in the input, that it consists only of whitespace and comments.
756    */
757   private void validateEnd(UonReader r) throws IOException, ParseException {
758      if (! isValidateEnd())
759         return;
760      while (true) {
761         var c = r.read();
762         if (c == -1)
763            return;
764         if (! Character.isWhitespace(c))
765            throw new ParseException(this, "Remainder after parse: '%s'.", (char)c);
766      }
767   }
768
769   @Override /* Overridden from ParserSession */
770   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
771      try (var r = getUonReader(pipe, decoding)) {
772         T o = readAnything(type, r, getOuter(), true, null);
773         validateEnd(r);
774         return o;
775      }
776   }
777
778   @Override /* Overridden from ReaderParserSession */
779   protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws Exception {
780      try (var r = getUonReader(pipe, decoding)) {
781         c = readIntoCollection(r, c, (ClassMeta<E>)getClassMeta(elementType), false, null);
782         validateEnd(r);
783         return c;
784      }
785   }
786
787   @Override /* Overridden from ReaderParserSession */
788   protected <K,V> Map<K,V> doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws Exception {
789      try (var r = getUonReader(pipe, decoding)) {
790         m = readIntoMap(r, m, (ClassMeta<K>)getClassMeta(keyType), (ClassMeta<V>)getClassMeta(valueType), null);
791         validateEnd(r);
792         return m;
793      }
794   }
795
796   /**
797    * Decode <js>"%xx"</js> sequences.
798    *
799    * @see UonParser.Builder#decoding()
800    * @return
801    *    <jk>true</jk> if URI encoded characters should be decoded, <jk>false</jk> if they've already been decoded
802    *    before being passed to this parser.
803    */
804   protected final boolean isDecoding() { return decoding; }
805
806   /**
807    * Validate end.
808    *
809    * @see UonParser.Builder#validateEnd()
810    * @return
811    *    <jk>true</jk> if after parsing a POJO from the input, verifies that the remaining input in
812    *    the stream consists of only comments or whitespace.
813    */
814   protected final boolean isValidateEnd() { return validateEnd; }
815
816   /**
817    * Convenience method for parsing an attribute from the specified parser.
818    *
819    * @param r The reader.
820    *    <br>Must not be <jk>null</jk>.
821    * @param encoded Whether the attribute is encoded.
822    * @return The parsed object, or <jk>null</jk> if the attribute was the literal <js>"null"</js>.
823    * @throws IOException Exception thrown by underlying stream.
824    * @throws ParseException Attribute was malformed.
825    */
826   protected final Object readAttr(UonReader r, boolean encoded) throws IOException, ParseException {
827      return readAttrName(r, encoded);
828   }
829
830   /**
831    * Parses an attribute name from the specified reader.
832    *
833    * @param r The reader.
834    *    <br>Must not be <jk>null</jk>.
835    * @param encoded Whether the attribute is encoded.
836    * @return The parsed attribute name, or <jk>null</jk> if the attribute name was the literal <js>"null"</js>.
837    * @throws IOException Exception thrown by underlying stream.
838    * @throws ParseException Attribute name was malformed.
839    */
840   protected final String readAttrName(UonReader r, boolean encoded) throws IOException, ParseException {
841
842      // If string is of form 'xxx', we're looking for ' at the end.
843      // Otherwise, we're looking for '&' or '=' or WS or -1 denoting the end of this string.
844
845      int c = r.peekSkipWs();
846      if (c == '\'')
847         return readPString(r);
848
849      r.mark();
850      boolean isInEscape = false;
851      if (encoded) {
852         while (true) {
853            c = r.read();
854            if (! isInEscape) {
855               if (c == AMP || c == EQ || c == -1 || Character.isWhitespace(c)) {
856                  if (c != -1)
857                     r.unread();
858                  var s = r.getMarked();
859                  return ("null".equals(s) ? null : s);
860               }
861            } else if (c == AMP)
862               r.replace('&');
863            else if (c == EQ)
864               r.replace('=');
865            isInEscape = isInEscape(c, r, isInEscape);
866         }
867      } else {
868         while (true) {
869            c = r.read();
870            if (! isInEscape && (c == '=' || c == -1 || Character.isWhitespace(c))) {
871               if (c != -1)
872                  r.unread();
873               var s = r.getMarked();
874               return ("null".equals(s) ? null : trim(s));
875            }
876            isInEscape = isInEscape(c, r, isInEscape);
877         }
878      }
879   }
880
881   /**
882    * Parses a string value from the specified reader.
883    *
884    * @param r The input reader.
885    *    <br>Must not be <jk>null</jk>.
886    * @param isUrlParamValue Whether this is a URL parameter.
887    * @return The parsed string, or <jk>null</jk> if the value was the literal <js>"null"</js>.
888    * @throws IOException Exception thrown by underlying stream.
889    * @throws ParseException Malformed input found.
890    */
891   protected final String readString(UonReader r, boolean isUrlParamValue) throws IOException, ParseException {
892
893      // If string is of form 'xxx', we're looking for ' at the end.
894      // Otherwise, we're looking for ',' or ')' or -1 denoting the end of this string.
895
896      int c = r.peekSkipWs();
897      if (c == '\'')
898         return readPString(r);
899
900      r.mark();
901      boolean isInEscape = false;
902      String s = null;
903      var endChars = (isUrlParamValue ? endCharsParam : endCharsNormal);
904      while (c != -1) {
905         c = r.read();
906         if (! isInEscape && endChars.contains(c)) {
907            // If this is a URL parameter value, we're looking for:  &
908            // If not, we're looking for:  &,)
909            r.unread();
910            c = -1;
911         }
912         if (c == -1)
913            s = r.getMarked();
914         else if (c == EQ)
915            r.replace('=');
916         else if (Character.isWhitespace(c) && ! isUrlParamValue) {
917            s = r.getMarked(0, -1);
918            skipSpace(r);
919            c = -1;
920         }
921         isInEscape = isInEscape(c, r, isInEscape);
922      }
923
924      if (isUrlParamValue)
925         s = StringUtils.trim(s);
926
927      return ("null".equals(s) ? null : trim(s));
928   }
929
930   @Override /* Overridden from ReaderParserSession */
931   protected FluentMap<String,Object> properties() {
932      return super.properties()
933         .a("decoding", decoding)
934         .a("validateEnd", validateEnd);
935   }
936}