JSONPath.swift

//
//  JSONPath.swift
//  DynamicJSON
//
//  Created by Matthias Zenger on 13/02/2024.
//  Copyright © 2024 Matthias Zenger. All rights reserved.
//
//  Licensed 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.
//

import Foundation

///
/// Enumeration `JSONPath` represents JSONPath queries based on RFC 9535
/// (JSONPath: Query Expressions for JSON). JSONPath defines a syntax
/// for selecting and extracting JSON (RFC 8259) values from within a given
/// JSON value.
///
public indirect enum JSONPath: Codable,
                               Hashable,
                               CustomStringConvertible {
  case `self`
  case current
  case select(JSONPath, Segment)
  
  /// Syntactic sugar for appending a single selector to the JSONPath query `path`.
  public static func children(_ path: JSONPath, _ selector: Selector) -> JSONPath {
    return .select(path, .children([selector]))
  }
  
  /// Syntactic sugar for appending a single descendant to the JSONPath query `path`.
  public static func descendants(_ path: JSONPath, _ selector: Selector) -> JSONPath {
    return .select(path, .descendants([selector]))
  }
  
  /// Creates a `JSONPath` representation of the JSONPath query represented
  /// using the syntax as specified by RFC 9535. An error is thrown if `query`
  /// is not compliant with JSONPath syntax. If parameter `strict` is set to
  /// false, the syntax and semantics of JSONPath are slighly relaxed. For
  /// instance, non-singular queries are supported in query filters.
  public init(query: String, strict: Bool = true) throws {
    var parser = JSONPathParser(string: query, strict: strict)
    self = try parser.parse()
  }
  
  /// Initialize a `JSONPath` reference using a decoder.
  public init(from decoder: Decoder) throws {
    let container = try decoder.singleValueContainer()
    try self.init(query: try container.decode(String.self))
  }
  
  /// Encode a `JSONPath` reference using the given encoder.
  public func encode(to encoder: Encoder) throws {
    var container = encoder.singleValueContainer()
    try container.encode(self.description)
  }
  
  /// Returns true if this JSONPath value represents a singular query.
  public var isSingular: Bool {
    switch self {
      case .self:
        return true
      case .current:
        return true
      case .select(let path, let segment):
        return path.isSingular && segment.isSingular
    }
  }
  
  /// Returns true if this query is a relative JSONPath query, i.e. it does not start
  /// with "$'.
  public var isRelative: Bool {
    switch self {
      case .self:
        return false
      case .current:
        return true
      case .select(let path, _):
        return path.isRelative
    }
  }
  
  /// Returns the sequence of segments of this JSONPath query.
  public var segments: [Segment] {
    var res: [Segment] = []
    self.insert(into: &res)
    return res
  }
  
  private func insert(into segments: inout [Segment]) {
    switch self {
      case .self, .current:
        break
      case .select(let path, let segment):
        path.insert(into: &segments)
        segments.append(segment)
    }
  }
  
  /// Returns a `JSONLocation` value matching this JSONPath query. Non-singular queries
  /// cannot be represented as a `JSONLocation` value and thus `nil` gets returned.
  public var location: JSONLocation? {
    switch self {
      case .self:
        return .root
      case .select(let path, .children(let selectors)):
        if let parentLocation = path.location, selectors.count == 1 {
          switch selectors[0] {
            case .member(let member):
              return .member(parentLocation, member)
            case .index(let index):
              return .index(parentLocation, index)
            default:
              return nil
          }
        }
        fallthrough
      default:
        return nil
    }
  }
  
  /// Returns the JSONPath query as a string.
  public var description: String {
    switch self {
      case .self:
        return "$"
      case .current:
        return "@"
      case .select(let path, let segment):
        return "\(path)\(segment)"
    }
  }
  
  /// Representation of JSONPath query segments. There are two different segment types:
  /// children and descendants.
  public enum Segment: Hashable, CustomStringConvertible {
    case children([Selector])
    case descendants([Selector])
    
    /// Returns true if this segment is a descendant segment.
    public var isDescendant: Bool {
      switch self {
        case .children(_):
          return false
        case .descendants(_):
          return true
      }
    }
    
    /// Returns true if this segment is singular, i.e. it refers to at most one value.
    public var isSingular: Bool {
      switch self {
        case .children(let selectors):
          return selectors.count == 1 && selectors[0].isSingular
        case .descendants(_):
          return false
      }
    }
    
    /// Returns the selectors encapsulated by this segment.
    public var selectors: [Selector] {
      switch self {
        case .children(let selectors):
          return selectors
        case .descendants(let selectors):
          return selectors
      }
    }
    
    /// Returns true if this segment can be represented using a shorthand form avoiding
    /// the usage of brackets.
    private func canUseShorthand(for member: String) -> Bool {
      var first = true
      for ch in member {
        let scalars = ch.unicodeScalars
        guard ch.isLetter
              || !first && ch.isHexDigit
              || ch == "_"
              || !first && ch == "-"
              || scalars.allSatisfy({ c in c.value >= 0x80 && c.value <= 0xD7FF })
              || scalars.allSatisfy({ c in c.value >= 0xE000 && c.value <= 0x10FFFF }) else {
          return false
        }
        first = false
      }
      return true
    }
    
    /// Returns a string representation of this segment.
    public var description: String {
      var res = ""
      var selectors: [Selector]
      switch self {
        case .children(let sel):
          selectors = sel
        case .descendants(let sel):
          selectors = sel
          res.append(".")
      }
      if selectors.count == 0 {
        return "\(res)[]"
      } else if selectors.count == 1 {
        switch selectors[0] {
          case .wildcard:
            return "\(res).*"
          case .member(let member):
            if self.canUseShorthand(for: member) {
              return "\(res).\(member)"
            } else if res.isEmpty {
              return "['\(JSONLocation.escapeMember(member))']"
            } else {
              return "..['\(JSONLocation.escapeMember(member))']"
            }
          default:
            if res.isEmpty {
              return "[\(selectors[0])]"
            } else {
              return "..[\(selectors[0])]"
            }
        }
      } else {
        if res.isEmpty {
          return "[\(selectors.map { x in x.description }.joined(separator: ", "))]"
        } else {
          return "..[\(selectors.map { x in x.description }.joined(separator: ", "))]"
        }
      }
    }
  }
  
  /// Representation of JSONPath query path selectors. Selectors are either child or
  /// descendant selectors. Supported are:
  ///   - wildcard selectors,
  ///   - member selectors,
  ///   - index selectors,
  ///   - slice selectors, and
  ///   - filter selectors.
  public enum Selector: Hashable, CustomStringConvertible {
    case wildcard
    case member(String)
    case index(Int)
    case slice(Int?, Int?, Int?)
    case filter(Expression)
    
    /// Returns true if this selector is singular, i.e. it refers to at most one value.
    public var isSingular: Bool {
      switch self {
        case .wildcard:
          return false
        case .member(_):
          return true
        case .index(_):
          return true
        case .slice(_, _, _):
          return false
        case .filter(_):
          return false
      }
    }
    
    /// Returns a string representation of this selector when used within a segment
    /// delimited by brackets.
    public var description: String {
      switch self {
        case .wildcard:
          return "*"
        case .member(let member):
          return "'\(JSONLocation.escapeMember(member))'"
        case .index(let n):
          return String(n)
        case .slice(nil, nil, nil):
          return ":"
        case .slice(.some(let start), nil, nil):
          return "\(start):"
        case .slice(nil, .some(let end), nil):
          return ":\(end)"
        case .slice(nil, nil, .some(let step)):
          return "::\(step)"
        case .slice(.some(let start), .some(let end), nil):
          return "\(start):\(end)"
        case .slice(.some(let start), nil, .some(let step)):
          return "\(start)::\(step)"
        case .slice(nil, .some(let end), .some(let step)):
          return ":\(end):\(step)"
        case .slice(.some(let start), .some(let end), .some(let step)):
          return "\(start):\(end):\(step)"
        case .filter(let condition):
          return "? \(condition)"
      }
    }
  }
  
  /// Representation of JSONPath query filter expressions.
  public indirect enum Expression: Hashable, CustomStringConvertible {
    case `null`
    case `true`
    case `false`
    case integer(Int64)
    case float(Double)
    case string(String)
    case variable(String)
    case query(JSONPath)
    case singularQuery(JSONPath)
    case call(String, [Expression])
    case prefix(UnaryOperator, Expression)
    case operation(Expression, BinaryOperator, Expression)
    
    /// Return a string representation of this expression if nested within another expression.
    public func description(within context: Expression) -> String {
      switch (self, context) {
        case (.null, _), (.true, _), (.false, _),
             (.integer(_), _), (.float(_), _), (.string(_), _),
             (.variable(_), _), (.query(_), _), (.call(_, _), _):
          return self.description
        case (.operation(_, _, _), .prefix(_, _)):
          return "(\(self))"
        case (.operation(_, let op, _), .operation(_, let cop, _)):
          if cop.precedence > op.precedence {
            return "(\(self))"
          }
          fallthrough
        default:
          return self.description
      }
    }
    
    /// Returns a string representation of this expression assuming it is not
    /// embedded in another expression.
    public var description: String {
      switch self {
        case .null:
          return "null"
        case .true:
          return "true"
        case .false:
          return "false"
        case .integer(let x):
          return String(x)
        case .float(let x):
          return String(x)
        case .string(let str):
          return "'\(str)'"
        case .variable(let ident):
          return ident
        case .query(let path):
          return path.description
        case .singularQuery(let path):
          return path.description
        case .call(let ident, let args):
          return "\(ident)(\(args.map { x in x.description }.joined(separator: ", ")))"
        case .prefix(let op, let oper):
          return "\(op)\(oper.description(within: self))"
        case .operation(let lhs, let op, let rhs):
          return "\(lhs.description(within: self)) \(op) \(rhs.description(within: self))"
      }
    }
  }
  
  /// Representation of a unary operator. Supported are currently "-" and "!".
  public enum UnaryOperator: Hashable, CustomStringConvertible {
    case not
    case negate
    
    public var description: String {
      switch self {
        case .not:
          return "!"
        case .negate:
          return "-"
      }
    }
  }
  
  /// Representation of a binary operator. Supported are currently "==", "!=", "<",
  /// ">", "<=", ">=", "||", "&&", "+", "-", "*", and "/".
  public enum BinaryOperator: Hashable, CustomStringConvertible {
    case equals
    case notEquals
    case lessThan
    case lessThanEquals
    case greaterThan
    case greaterThanEquals
    case or
    case and
    case plus
    case minus
    case mult
    case divide
    
    var precedence: Int {
      switch self {
        case .or:
          return 0
        case .and:
          return 1
        case .equals:
          return 2
        case .notEquals:
          return 2
        case .lessThan:
          return 2
        case .lessThanEquals:
          return 2
        case .greaterThan:
          return 2
        case .greaterThanEquals:
          return 2
        case .plus:
          return 3
        case .minus:
          return 3
        case .mult:
          return 4
        case .divide:
          return 4
      }
    }
    
    public var description: String {
      switch self {
        case .equals:
          return "=="
        case .notEquals:
          return "!="
        case .lessThan:
          return "<"
        case .lessThanEquals:
          return "<="
        case .greaterThan:
          return ">"
        case .greaterThanEquals:
          return ">="
        case .or:
          return "||"
        case .and:
          return "&&"
        case .plus:
          return "+"
        case .minus:
          return "-"
        case .mult:
          return "*"
        case .divide:
          return "/"
      }
    }
  }
}