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

import static org.apache.juneau.commons.function.Suppliers.*;
import static org.apache.juneau.commons.utils.Shorts.*;

import java.io.*;
import java.util.*;

import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.json.*;
import org.apache.juneau.marshall.json5.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.stream.*;
import org.apache.juneau.marshall.swap.spi.*;

/**
 * Session object for {@link MarkdownParser}.
 *
 * <p>
 * Parses Markdown tables and bulleted lists into Java objects.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
 * </ul>
 *
 */
@SuppressWarnings({
   "java:S110", // Inheritance depth acceptable for parser session hierarchy
   "java:S115", // Constants use UPPER_snakeCase convention
   "java:S1192", // Duplicated literals read more clearly inline than as constants.
   "java:S3740", // Raw Map needed for generic map construction from ClassMeta
   "java:S3776", // Cognitive complexity acceptable for doRead / readAnything
   "java:S6541", // Brain method acceptable for readAnything
   "rawtypes", // Raw Map is used where the map is created from ClassMeta and its key/value types are only known at runtime
   "resource", // Closeable resources are owned by the caller's parser session; Eclipse JDT @Owning warning is by design.
   "unchecked" // (T) casts of parsed cell values and (Collection<Object>) casts of eType.newInstance() match the requested ClassMeta eType
})
public class MarkdownParserSession extends ReaderParserSession implements RecordReadable {

   final String nullValue;
   private final Memoizer<JsonParser> json5Parser = memoizer(() -> {
      var b = Json5Parser.create().marshallingContext((MarshallingContext) getContext());
      if (isTrimStrings())
         b = b.trimStrings();
      return b.build();
   });

   /**
    * 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> {

      String nullValue;

      /**
       * Constructor.
       *
       * @param ctx The context creating this session.
       */
      protected Builder(MarkdownParser ctx) {
         super(ctx);
         nullValue = ctx.getNullValue();
      }

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

   }

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

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

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

   /**
    * Constructor.
    *
    * @param builder The builder for this object.
    */
   protected MarkdownParserSession(Builder<?> builder) {
      super(builder);
      nullValue = or(builder.nullValue, "*null*");
   }

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

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

   @Override /* Overridden from ParserSession */
   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException {
      try (var r = new BufferedReader(pipe.getReader())) {
         var lines = readAllLines(r);
         return readAnything(lines, type, getOuter(), null);
      }
   }

   /**
    * Main parse dispatch method.
    *
    * @param <T> The target type.
    * @param lines All input lines.
    * @param eType The expected type.
    * @param outer The outer object (for inner class instantiation).
    * @param pMeta The parent bean property meta (may be null).
    * @return The parsed object.
    * @throws IOException Thrown by underlying stream.
    * @throws ParseException If parsing fails.
    */
   protected <T> T readAnything(List<String> lines, ClassMeta<T> eType, Object outer, BeanPropertyMeta pMeta) throws IOException, ParseException {
      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;
      if (builder != null)
         sType = builder.getBuilderClassMeta(this);
      else if (swap != null)
         sType = swap.getSwapClassMeta(this);
      else
         sType = eType;

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

      // Skip blank lines and handle empty input
      var nonBlank = lines.stream().filter(l -> !l.isBlank()).toList();
      if (lines.isEmpty() || nonBlank.isEmpty())
         return sType.isString() ? (T) "" : null;

      var firstNonBlank = nonBlank.get(0).trim();

      Object o;

      if (firstNonBlank.startsWith("|")) {
         // Table input
         o = readTable(lines, sType, outer);
      } else if (firstNonBlank.startsWith("- ") || firstNonBlank.startsWith("* ") || firstNonBlank.startsWith("+ ")) {
         // Bulleted list input
         o = readBulletList(lines, sType, outer);
      } else {
         // Plain text — treat as simple value
         o = readCellValue(firstNonBlank, sType, null);
      }

      if (builder != null && o != null)
         o = builder.build(this, o, eType);

      if (swap != null && o != null)
         o = unswap(swap, o, eType);

      return (T) o;
   }

   /**
    * Parses a Markdown table (either 2-column key/value or multi-column).
    *
    * @param lines All input lines.
    * @param eType The expected type.
    * @param outer The outer object.
    * @return The parsed object.
    * @throws ParseException If parsing fails.
    */
   protected Object readTable(List<String> lines, ClassMeta<?> eType, Object outer) throws ParseException {
      // Extract table rows (lines starting with |)
      var tableLines = lines.stream().filter(l -> l.trim().startsWith("|")).toList();
      if (tableLines.isEmpty())
         return null;

      // Parse header row
      var headerLine = tableLines.get(0);
      var headers = splitTableRow(headerLine);
      if (headers.isEmpty())
         return null;

      // Skip separator row (|---|---|)
      var dataLines = tableLines.stream().skip(1).filter(l -> !isSeparatorRow(l)).toList();

      // Detect table type: if 2 columns and first header is "Property"/"Key", treat as key/value table
      var isKeyValue = headers.size() == 2
         && (eqic(headers.get(0), "Property") || eqic(headers.get(0), "Key"))
         && eqic(headers.get(1), "Value");

      if (isKeyValue)
         return readKeyValueTable(headers, dataLines, eType, outer);
      return readMultiColumnTable(headers, dataLines, eType, outer);
   }

   /**
    * Parses a 2-column key/value Markdown table.
    *
    * @param headers The header names.
    * @param dataLines The data row lines.
    * @param eType The expected type.
    * @param outer The outer object.
    * @return The parsed bean, map, or other object.
    * @throws ParseException If parsing fails.
    */
   @SuppressWarnings({
      "java:S135" // Two continue statements needed: skip short rows and skip _type row
   })
   protected Object readKeyValueTable(List<String> headers, List<String> dataLines, ClassMeta<?> eType, Object outer) throws ParseException {

      // For types with ObjectSwaps or that can't be populated via BeanMap property-setting,
      // convert the key-value table to a JSON5 object and delegate to the full JSON5 parser.
      if (needsJson5Path(eType)) {
         var json5 = keyValueTableToJson5(dataLines);
         try {
            return getJson5Parser().readWithOuter(json5, eType, outer);
         } catch (Exception e) {
            throw new ParseException(this, e, "Could not parse key-value table as '%s' via JSON5 '%s'.", eType, json5);
         }
      }

      if (eType.isBean()) {
         // First pass: look for _type to resolve concrete class for abstract/interface types
         ClassMeta<?> actualType = eType;
         for (var line : dataLines) {
            var cells = splitTableRow(line);
            if (cells.size() >= 2 && eq(cells.get(0), "_type")) {
               var typeName = cells.get(1);
               var registry = eType.getBeanRegistry();
               var resolved = registry != null ? registry.getClassMeta(typeName) : null;
               if (resolved != null)
                  actualType = resolved;
               break;
            }
         }
         var m = newBeanMap(outer, actualType.inner());
         for (var line : dataLines) {
            var cells = splitTableRow(line);
            if (cells.size() < 2)
               continue;
            var key = cells.get(0);

            // Skip _type row - it was used for type resolution above
            if (eq(key, "_type"))
               continue;

            var rawVal = cells.get(1);
            var pm = m.getPropertyMeta(key);
            if (pm != null) {
               setCurrentProperty(pm);
               var pmcm = (ClassMeta<?>) pm.getBeanInfo();
               var val = readCellValue(rawVal, pmcm, m.getBean(false));
               try {
                  setName(pmcm, val, key);
               } catch (Exception e) {
                  throw new ParseException(this, e, "Could not set @NameProperty on '%s'.", key);
               }
               pm.set(m, key, val);
               setCurrentProperty(null);
            } else {
               onUnknownProperty(key, m, rawVal);
            }
         }
         return checkRequired(m).getBean();
      }

      if (eType.isMap()) {
         Map map = eType.canCreateNewInstance(outer) ? (Map) eType.newInstance(outer) : newGenericMap();
         var keyType = eType.getKeyType() != null ? eType.getKeyType() : string();
         var valueType = eType.getValueType() != null ? eType.getValueType() : object();
         for (var line : dataLines) {
            var cells = splitTableRow(line);
            if (cells.size() < 2)
               continue;
            var rawKey = cells.get(0);
            var key = readCellValue(rawKey, keyType, null);
            // Pass the map being built as the outer when parsing values - non-static inner
            // classes whose enclosing class is the map type (e.g. H1 inside H extends LinkedHashMap)
            // need that map instance to satisfy their implicit outer-class constructor argument.
            var val = readCellValue(cells.get(1), valueType, map);
            try {
               setName(valueType, val, key);
            } catch (Exception e) {
               throw new ParseException(this, e, "Could not set @NameProperty for map key '%s'.", key);
            }
            map.put(key, val);
         }
         return map;
      }

      if (!eType.isObject()) {
         // Scalar/Number/primitive (or any other non-bean, non-map, non-Object) target: a key/value
         // table has no shape that maps onto a single scalar *value*, but this used to fall through to
         // the generic "Object or unknown" handling below regardless of eType, unconditionally building
         // a MarshalledMap and returning that instead of a T -- throwing a ClassCastException back at
         // the caller. Only the first data row's value cell (if any) is meaningful for a genuine scalar
         // target, so parse and return it directly instead of wrapping the whole table in a map.
         for (var line : dataLines) {
            var cells = splitTableRow(line);
            if (cells.size() >= 2)
               return readCellValue(cells.get(1), eType, null);
         }
         return null;
      }

      // Object or unknown: return MarshalledMap, check for _type and cast if possible
      var resultMap = newGenericMap();
      for (var line : dataLines) {
         var cells = splitTableRow(line);
         if (cells.size() < 2)
            continue;
         var key = cells.get(0);
         var val = readCellValue(cells.get(1), object(), null);
         resultMap.put(key, val);
      }
      
      // Check for _type property and cast to typed bean if found
      if (resultMap.containsKey(getBeanTypePropertyName(eType))) {
         return cast(resultMap, null, eType);
      }
      
      return resultMap;
   }

   /**
    * Parses a multi-column Markdown table (N columns).
    *
    * @param headers The column header names.
    * @param dataLines The data row lines.
    * @param eType The expected type.
    * @param outer The outer object.
    * @return The parsed list of beans, maps, or other objects.
    * @throws ParseException If parsing fails.
    */
   protected Object readMultiColumnTable(List<String> headers, List<String> dataLines, ClassMeta<?> eType, Object outer) throws ParseException {
      ClassMeta<?> elementType;
      Collection<Object> result;

      if (eType.isArray()) {
         elementType = eType.getElementType();
         result = l();
      } else if (eType.isCollection()) {
         elementType = eType.getElementType();
         result = eType.canCreateNewInstance(outer) ? (Collection<Object>) eType.newInstance() : l();
      } else if (eType.isObject()) {
         elementType = object();
         result = l();
      } else {
         // Single bean/map with multiple columns — not a standard use case, parse first row
         if (!dataLines.isEmpty()) {
            var cells = splitTableRow(dataLines.get(0));
            return readRow(headers, cells, eType, outer);
         }
         return null;
      }

      for (var line : dataLines) {
         var cells = splitTableRow(line);
         var item = readRow(headers, cells, elementType, result);
         result.add(item);
      }

      if (eType.isArray())
         return toArray(eType, result);

      return result;
   }

   /**
    * Parses a single data row into the specified element type.
    *
    * @param headers The column header names.
    * @param cells The cell values for this row.
    * @param eType The element type.
    * @param outer The outer object.
    * @return The parsed element.
    * @throws ParseException If parsing fails.
    */
   protected Object readRow(List<String> headers, List<String> cells, ClassMeta<?> eType, Object outer) throws ParseException {
      // Check if all cells are null - if so, return null for the entire row
      boolean allNull = true;
      for (var cell : cells) {
         if (cell != null && neq(cell, nullValue) && !cell.trim().isEmpty()) {
            allNull = false;
            break;
         }
      }
      if (allNull) {
         return null;
      }

      // Check if there's a _type column and resolve the actual type using the bean registry
      ClassMeta<?> actualType = eType;
      int typeColIndex = headers.indexOf("_type");
      if (typeColIndex >= 0 && typeColIndex < cells.size()) {
         var typeName = cells.get(typeColIndex);
         if (ine(typeName)) {
            var registry = eType != null ? eType.getBeanRegistry() : null;
            var resolved = registry != null ? registry.getClassMeta(typeName) : null;
            if (resolved != null)
               actualType = resolved;
         }
      }

      // For types with ObjectSwaps or that can't be populated via BeanMap property-setting,
      // convert the row to a JSON5 object and delegate to the full JSON5 parser.  This correctly
      // handles ObjectSwaps, @ParentProperty, JsonMap-constructor beans, etc.
      if (needsJson5Path(actualType)) {
         var json5 = rowToJson5(headers, cells);
            try {
            return getJson5Parser().readWithOuter(json5, actualType, outer);
         } catch (Exception e) {
            throw new ParseException(this, e, "Could not parse table row as '%s' via JSON5 '%s'.", actualType, json5);
         }
      }

      if (actualType == null || actualType.isObject()) {
         var m = newGenericMap();
         for (var i = 0; i < headers.size(); i++) {
            var header = headers.get(i);
            if (eq(header, "_type"))
               continue;
            var val = i < cells.size() ? cells.get(i) : null;
            m.put(header, readCellValue(val, object(), null));
         }
         if (typeColIndex >= 0 && m.size() > 0)
            return cast(m, null, eType);
         return m;
      }
      if (actualType.isBean()) {
         var m = newBeanMap(outer, actualType.inner());
         for (var i = 0; i < headers.size(); i++) {
            var header = headers.get(i);
            if (eq(header, "_type"))
               continue;
            var rawVal = i < cells.size() ? cells.get(i) : null;
            var pm = m.getPropertyMeta(header);
            if (pm != null) {
               setCurrentProperty(pm);
               var val = readCellValue(rawVal, (ClassMeta<?>) pm.getBeanInfo(), m.getBean(false));
               pm.set(m, header, val);
               setCurrentProperty(null);
            } else {
               onUnknownProperty(header, m, rawVal);
            }
         }
         return checkRequired(m).getBean();
      }
      if (actualType.isMap()) {
         Map map = actualType.canCreateNewInstance(outer) ? (Map) actualType.newInstance(outer) : newGenericMap();
         var keyType = actualType.getKeyType() != null ? actualType.getKeyType() : string();
         var valueType = actualType.getValueType() != null ? actualType.getValueType() : object();
         for (var i = 0; i < headers.size(); i++) {
            var header = headers.get(i);
            if (eq(header, "_type"))
               continue;
            var key = convertAttrToType(map, header, keyType);
            var rawVal = i < cells.size() ? cells.get(i) : null;
            // Pass the map being built as the outer when parsing values - mirrors the
            // key-value-table branch so non-static inner classes whose enclosing class is the
            // map type can be instantiated correctly.
            var val = readCellValue(rawVal, valueType, map);
            map.put(key, val);
         }
         return map;
      }
      // Simple type: use first cell
      return readCellValue(cells.isEmpty() ? null : cells.get(0), actualType, null);
   }

   /**
    * Parses a Markdown bulleted list into a collection or array.
    *
    * @param lines All input lines.
    * @param eType The expected type.
    * @param outer The outer object.
    * @return The parsed collection, array, or single element.
    * @throws ParseException If parsing fails.
    */
   protected Object readBulletList(List<String> lines, ClassMeta<?> eType, Object outer) throws ParseException {
      var items = new ArrayList<String>();
      for (var line : lines) {
         var trimmed = line.trim();
         if (trimmed.startsWith("- ") || trimmed.startsWith("* ") || trimmed.startsWith("+ "))
            items.add(trimmed.substring(2));
         else if (eqa(trimmed, "-", "*", "+"))
            items.add("");
      }

      ClassMeta<?> elementType;
      Collection<Object> result;

      if (eType.isArray()) {
         elementType = eType.getElementType();
         result = l();
      } else if (eType.isCollection()) {
         elementType = eType.getElementType();
         result = eType.canCreateNewInstance(outer) ? (Collection<Object>) eType.newInstance() : l();
      } else if (!eType.isMap() && !eType.isBean()) {
         // Scalar/Number/primitive target: a bullet list has no shape that maps onto a single scalar
         // *value*, but the code below always wrapped every parsed item into a List and returned that --
         // even when the caller asked for a bare T -- which threw a ClassCastException back at the
         // top-level read() cast. Only the first item (if any) is meaningful for a genuine scalar
         // target, so parse and return it directly instead of wrapping it in a list.
         if (items.isEmpty())
            return null;
         ClassMeta<?> scalarType = eType.isObject() ? object() : eType;
         return readCellValue(items.get(0), scalarType, null);
      } else {
         elementType = eType.isObject() ? object() : eType;
         result = l();
      }

      for (var item : items)
         result.add(readCellValue(item, elementType, null));

      if (eType.isArray())
         return toArray(eType, result);

      return result;
   }

   /**
    * Returns a Json5Parser that shares this session's bean context (swaps, implClasses, dictionary).
    *
    * <p>
    * Memoized via {@link Memoizer} — first call constructs the parser; subsequent calls return the cached instance.
    */
   private JsonParser getJson5Parser() {
      return json5Parser.get();
   }

   /**
    * Converts a raw Markdown table cell string to the target type.
    *
    * <p>
    * If the cell matches the configured null value, returns {@code null}.
    * If the cell is backtick-wrapped JSON5, parses via {@link Json5Parser}.
    * Otherwise, attempts numeric/boolean auto-detection when the target type is {@code Object}.
    *
    * @param <T> The target type.
    * @param val The raw cell string (already unescaped).
    * @param eType The target type.
    * @param outer The outer object (parent bean) for @ParentProperty support.
    * @return The parsed value.
    * @throws ParseException If parsing fails.
    */
   protected <T> T readCellValue(String val, ClassMeta<T> eType, Object outer) throws ParseException {
      if (val == null)
         return null;
      val = val.trim();
      if (eq(val, nullValue))
         return null;
      if (isTrimStrings())
         val = val.trim();
      // For String types, preserve empty cells as empty strings; for other types, treat as null
      if (val.isEmpty())
         return eType.isString() ? (T) "" : null;

      // Inline JSON5 wrapped in backticks — use context-aware parser with outer for full support
      // (handles ObjectSwaps, @ParentProperty, JsonMap constructors, etc.)
      if (val.startsWith("`") && val.endsWith("`") && val.length() > 1) {
         var inner = val.substring(1, val.length() - 1);
         try {
            return getJson5Parser().readWithOuter(inner, eType, outer);
         } catch (Exception e) {
            throw new ParseException(this, e, "Could not parse inline JSON5 '%s' to type '%s'.", inner, eType);
         }
      }

      // Unescape table cell escaping
      val = unescapeCell(val);

      if (eType.isObject()) {
         // Auto-detect type
         if (eq(val, "true")) return (T) Boolean.TRUE;
         if (eq(val, "false")) return (T) Boolean.FALSE;
         try { return (T) Integer.valueOf(val); } catch (@SuppressWarnings("unused") NumberFormatException ignored) { /* not int, try next */ }
         try { return (T) Long.valueOf(val); } catch (@SuppressWarnings("unused") NumberFormatException ignored) { /* not long, try next */ }
         try { return (T) Double.valueOf(val); } catch (@SuppressWarnings("unused") NumberFormatException ignored) { /* not double, treat as string */ }
         return (T) val;
      }

      // Date / time / duration cluster: route through the format-aware parsers so the configured
      // MarshallingContext.get<Format>() hint reaches the wire-form coercion.  Without this the
      // fall-through to convertToType(val, eType) below would route a bare numeric cell through a
      // generic Number → T coercion (e.g. Duration.ofMillis(long)) that drops the format hint.
      if (eType.isDate())
         return readDate(val, eType);
      if (eType.isCalendar())
         return readCalendar(val, eType);
      if (eType.isTemporal())
         return readTemporal(val, eType);
      if (eType.isDuration())
         return (T) readDuration(val);
      if (eType.isPeriod())
         return (T) readPeriod(val);

      try {
         return convertToType(val, eType);
      } catch (@SuppressWarnings("unused") Exception e) {
         throw new ParseException(this, "Could not convert Markdown cell value '%s' to type '%s'.", val, eType);
      }
   }

   /**
    * Returns true if the given ClassMeta requires the full JSON5 parsing machinery to be correctly
    * instantiated — i.e., it has an ObjectSwap, cannot be created as a standard bean, or cannot be
    * populated via direct property-setting through a BeanMap.
    *
    * <p>
    * When this returns true, table rows and key-value tables should be converted to a JSON5 string
    * and parsed via {@link Json5Parser} (using
    * {@link Parser#readWithOuter}) to correctly handle swaps,
    * {@link ParentProperty @ParentProperty}, and non-standard constructors.
    */
   private boolean needsJson5Path(ClassMeta<?> type) {
      if (type == null || type.isObject() || type.isMap() || type.isPrimitive() || type.isNumber() || type.isString())
         return false;
      // If the type has an ObjectSwap, it cannot be parsed via BeanMap property-setting
      if (type.getSwap(this) != null)
         return true;
      // If not a bean (no public properties), can't use BeanMap approach
      return !type.isBean();
   }

   /**
    * Converts a single Markdown table cell value to its JSON5 literal representation.
    *
    * <p>
    * Inline JSON5 (backtick-wrapped) is unwrapped directly. Booleans and numbers are written bare.
    * Everything else is single-quoted as a JSON5 string.
    */
   private String cellToJson5(String cell) {
      if (cell == null || eq(cell, nullValue))
         return "null";
      cell = cell.trim();
      if (cell.isEmpty())
         return "''";
      // Inline JSON5 wrapped in backticks — unwrap and embed directly
      if (cell.startsWith("`") && cell.endsWith("`") && cell.length() > 1)
         return cell.substring(1, cell.length() - 1);
      // Unescape Markdown table escaping first
      cell = unescapeCell(cell);
      // Booleans and numbers don't need quoting
      if (eqa(cell, "true", "false"))
         return cell;
      try { Integer.parseInt(cell); return cell; } catch (@SuppressWarnings("unused") NumberFormatException ignored) { /* not int, try next */ }
      try { Long.parseLong(cell); return cell; } catch (@SuppressWarnings("unused") NumberFormatException ignored) { /* not long, try next */ }
      try { Double.parseDouble(cell); return cell; } catch (@SuppressWarnings("unused") NumberFormatException ignored) { /* not double, quote as string */ }
      // String: single-quote with escaping for JSON5
      return "'" + cell.replace("\\", "\\\\").replace("'", "\\'") + "'";
   }

   /**
    * Converts a table row (headers + cells) into a JSON5 object string, suitable for parsing via
    * {@link Json5Parser}.
    *
    * <p>
    * Example: headers=["f1","f2"], cells=["a","2"] → <code>{f1:'a',f2:2}</code>
    *
    * <p>
    * The {@code _type} column, if present, is included as-is (as a quoted string) so that the JSON5
    * parser can perform type resolution via the bean dictionary.
    */
   private String rowToJson5(List<String> headers, List<String> cells) {
      var sb = new StringBuilder("{");
      var first = true;
      for (var i = 0; i < headers.size(); i++) {
         var header = headers.get(i);
         var cell = i < cells.size() ? cells.get(i) : null;
         if (!first) sb.append(",");
         first = false;
         sb.append(header).append(":");
         if (eq(header, "_type")) {
            // Keep _type as a quoted string so the JSON5 parser can resolve it
            sb.append(cell == null ? "null" : "'" + cell + "'");
         } else {
            sb.append(cellToJson5(cell));
         }
      }
      sb.append("}");
      return sb.toString();
   }

   /**
    * Converts a key-value table (list of [key, value] row lines) into a JSON5 object string.
    */
   private String keyValueTableToJson5(List<String> dataLines) {
      var sb = new StringBuilder("{");
      var first = true;
      for (var line : dataLines) {
         var cells = splitTableRow(line);
         if (cells.size() < 2)
            continue;
         var key = cells.get(0);
         var val = cells.get(1);
         if (!first) sb.append(",");
         first = false;
         sb.append(key).append(":");
         if (eq(key, "_type")) {
            sb.append(val == null ? "null" : "'" + val + "'");
         } else {
            sb.append(cellToJson5(val));
         }
      }
      sb.append("}");
      return sb.toString();
   }

   /**
    * Splits a Markdown table row into its cell values, stripping leading/trailing whitespace and pipes.
    *
    * @param line The raw table row line.
    * @return The list of trimmed cell values.
    */
   protected List<String> splitTableRow(String line) {
      var trimmed = line.trim();
      if (trimmed.startsWith("|"))
         trimmed = trimmed.substring(1);
      if (trimmed.endsWith("|") && (trimmed.length() < 2 || trimmed.charAt(trimmed.length() - 2) != '\\'))
         trimmed = trimmed.substring(0, trimmed.length() - 1);

      // Split on unescaped pipe characters
      var result = new ArrayList<String>();
      var sb = new StringBuilder();
      var i = 0;
      while (i < trimmed.length()) {
         var c = trimmed.charAt(i);
         if (c == '\\' && i + 1 < trimmed.length()) {
            var next = trimmed.charAt(i + 1);
            if (next == '|' || next == '\\') {
               sb.append('\\');
               sb.append(next);
               i += 2;
               continue;
            }
         }
         if (c == '|') {
            result.add(sb.toString().trim());
            sb.setLength(0);
         } else {
            sb.append(c);
         }
         i++;
      }
      if (!sb.isEmpty() || !result.isEmpty())
         result.add(sb.toString().trim());
      return result;
   }

   /**
    * Returns whether a table row is a separator row (e.g. {@code |---|---|}).
    *
    * @param line The table row line.
    * @return Whether it is a separator row.
    */
   protected boolean isSeparatorRow(String line) {
      var trimmed = line.trim();
      if (!trimmed.startsWith("|"))
         return false;
      // Equivalent of trimmed.replaceAll("[|\\-: ]", "").isEmpty(): true iff every char is one of | - : space.
      for (var i = 0; i < trimmed.length(); i++) {
         var c = trimmed.charAt(i);
         if (c != '|' && c != '-' && c != ':' && c != ' ')
            return false;
      }
      return true;
   }

   /**
    * Reads all lines from the given reader.
    *
    * @param r The reader.
    *    <br>Must not be <jk>null</jk>.
    * @return All lines.
    * @throws IOException Thrown by underlying stream.
    */
   protected List<String> readAllLines(BufferedReader r) throws IOException {
      var lines = new ArrayList<String>();
      String line;
      while ((line = r.readLine()) != null)
         lines.add(line);
      return lines;
   }

   /**
    * Unescapes Markdown table cell escape sequences.
    *
    * @param s The escaped cell value.
    *    <br>Can be <jk>null</jk> (returns <jk>null</jk>).
    * @return The unescaped value.  Returns <jk>null</jk> if the input was <jk>null</jk>.
    */
   protected String unescapeCell(String s) {
      if (s == null || !s.contains("\\"))
         return s;
      var sb = new StringBuilder(s.length());
      var i = 0;
      while (i < s.length()) {
         var c = s.charAt(i);
         if (c == '\\' && i + 1 < s.length()) {
            var next = s.charAt(i + 1);
            if (next == '|' || next == '\\') {
               sb.append(next);
               i += 2;
               continue;
            }
         }
         sb.append(c);
         i++;
      }
      return sb.toString();
   }
}