module RBS
  # Location is the range on buffer, `start_pos..end_pos`.
  # The index is based on characters.
  class Location
    # The buffer this location points on.
    attr_reader buffer: Buffer

    # The index of character the range starts from.
    attr_reader start_pos: Integer

    # The index of character the range ends at.
    attr_reader end_pos: Integer

    def initialize: (buffer: Buffer, start_pos: Integer, end_pos: Integer) -> void

    def inspect: () -> String

    # Returns the name of the buffer.
    def name: () -> untyped

    # Line of the `start_pos` (1 origin)
    def start_line: () -> Integer

    # Column of the `start_pos` (0 origin)
    def start_column: () -> Integer

    # Line of the `end_pos` (1 origin)
    def end_line: () -> Integer

    # Column of the `end_pos` (0 origin)
    def end_column: () -> Integer

    def start_loc: () -> Buffer::loc

    def end_loc: () -> Buffer::loc

    def range: () -> Range[Integer]

    # A substring of buffer associated to the location.
    def source: () -> String

    def to_s: () -> String

    # Returns a string representation suitable for terminal output.
    #
    #     Location.to_string(loc)  # => a.rb:1:0...3:4
    #     Location.to_string(nil)  # => *:*:*..*:*
    #
    def self.to_string: (Location? location, ?default: ::String default) -> String

    def ==: (untyped other) -> bool

    # Returns a new location with starting positionof `self` and ending position of `other`.
    #
    #     l1 = Location.new(buffer: buffer, start_pos: 0, end_pox: x)
    #     l2 = Location.new(buffer: buffer, start_pos: y, end_pos: 20)
    #     l1 + l2  # => Location.new(buffer: buffer, start_pos: 0, end_pos: 20)
    #
    def +: (Location other) -> Location

    # Returns true if `loc` is exact predecessor of `self`.
    #
    #     l1 = Location.new(...)    # 0..10
    #     l2 = Location.new(...)    # 10..13
    #     l3 = Location.new(...)    # 13..20
    #
    #     l1.pred?(l2)       # => true
    #     l2.pred?(l3)       # => true
    #     l1.pred?(l3)       # => false
    #
    def pred?: (Location loc) -> bool

    include _ToJson

    # `<<` locations given as argument.
    #
    def concat: (*Location?) -> Location

    # Inplace version of `+`.
    #
    def <<: (Location?) -> Location

    # Returns WithChildren instance with given children.
    #
    #     location.with_children(
    #       required: { name: name.location },
    #       optional: { args: nil }
    #     )
    #
    def with_children: [R, O](?required: Hash[R, Range[Integer] | Location], ?optional: Hash[O, Range[Integer] | Location | nil]) -> WithChildren[R, O]

    # Location::WithChildren contains _child_ locations.
    #
    #     # Array[String]
    #     # ^^^^^          <= name
    #     #      ^^^^^^^^  <= args
    #     #
    #     # @type var loc: Location::WithChildren[:name, :args]
    #     loc = Location::WithChildren.new(buffer: buffer, start_pos: 0, end_pos: 13)
    #     loc = loc.merge_required({ name: 1...5 })
    #     loc = loc.merge_optional({ args: 5...13 })
    #
    #     loc[:name]      # => Location instance for `Array`
    #     loc[:args]      # => Location instance for `[String]`
    #
    class WithChildren[RequiredChildKeys, OptionalChildKeys] < Location
      attr_reader required_children: Hash[RequiredChildKeys, Range[Integer]]

      attr_reader optional_children: Hash[OptionalChildKeys, Range[Integer]?]

      def initialize: ...

      def initialize_copy: ...

      # Returns `Location` instance for given _child_ name.
      #
      #     # @type var loc: Location::WithChildren[:name, :args]
      #     loc[:name]      # => Location
      #     loc[:args]      # => may be nil
      #
      # Note that passing unknown symbol raises an error even if the child is _optional_.
      # You need explicitly set `nil` for absent optional children.
      #
      def []: (RequiredChildKeys) -> Location
            | (OptionalChildKeys) -> Location?
            | (Symbol) -> Location?

      def merge_required: (Hash[RequiredChildKeys, Range[Integer] | Location]) -> self

      def merge_optional: (Hash[OptionalChildKeys, Range[Integer] | Location | nil]) -> self
    end
  end
end