csv_plus_plus 0.1.1 → 0.1.3

data/lib/csv_plus_plus/compiler.rb

@@ -0,0 +1,178 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  # Encapsulates the parsing and building of objects (+Template+ -> +Row+ -> +Cell+). Variable resolution is delegated
+  # to the +Scope+
+  #
+  # @attr_reader options [Options] The +Options+ to compile with
+  # @attr_reader runtime [Runtime] The runtime execution
+  # rubocop:disable Metrics/ClassLength
+  class Compiler
+    extend ::T::Sig
+
+    sig { returns(::CSVPlusPlus::Options) }
+    attr_reader :options
+
+    sig { returns(::CSVPlusPlus::Runtime::Runtime) }
+    attr_reader :runtime
+
+    sig do
+      params(
+        options: ::CSVPlusPlus::Options,
+        runtime: ::CSVPlusPlus::Runtime::Runtime,
+        block: ::T.proc.params(arg0: ::CSVPlusPlus::Compiler).void
+      ).void
+    end
+    # Create a compiler and make sure it gets cleaned up
+    #
+    # @param options [Options]
+    # @param runtime [Runtime] The initial +Runtime+ for the compiler
+    def self.with_compiler(options:, runtime:, &block)
+      if options.verbose
+        ::CSVPlusPlus::BenchmarkedCompiler.with_benchmarks(options:, runtime:) do |c|
+          block.call(c)
+        end
+      else
+        block.call(new(options:, runtime:))
+      end
+    ensure
+      runtime.cleanup!
+    end
+
+    sig { params(options: ::CSVPlusPlus::Options, runtime: ::CSVPlusPlus::Runtime::Runtime).void }
+    # @param options [Options]
+    # @param runtime [Runtime]
+    def initialize(options:, runtime:)
+      @options = options
+      @runtime = runtime
+
+      # TODO: infer a type
+      # allow user-supplied key/values to override anything global or from the code section
+      @runtime.def_variables(
+        options.key_values.transform_values { |v| ::CSVPlusPlus::Entities::String.new(v.to_s) }
+      )
+    end
+
+    sig { params(benchmark: ::Benchmark::Report).void }
+    # Attach a +Benchmark+ and a place to store timings to the compiler class.
+    #
+    # @param benchmark [Benchmark] A +Benchmark+ instance
+    def benchmark=(benchmark)
+      @benchmark = ::T.let(benchmark, ::T.nilable(::Benchmark::Report))
+      @timings = ::T.let([], ::T.nilable(::T::Array[::Benchmark::Tms]))
+    end
+
+    sig { returns(::CSVPlusPlus::Template) }
+    # Compile a template and return a +::CSVPlusPlus::Template+ instance ready to be written with a +Writer+
+    #
+    # @return [Template]
+    def compile_template
+      parse_code_section!
+      rows = parse_csv_section!
+
+      ::CSVPlusPlus::Template.new(rows:, runtime: @runtime).tap do |t|
+        t.validate_infinite_expands(@runtime)
+        expanding! { t.expand_rows! }
+        bind_all_vars! { t.bind_all_vars!(@runtime) }
+        resolve_all_cells!(t)
+      end
+    end
+
+    sig { params(block: ::T.proc.params(runtime: ::CSVPlusPlus::Runtime::Runtime).void).void }
+    # Write the compiled results
+    def outputting!(&block)
+      @runtime.start_at_csv! { block.call(@runtime) }
+    end
+
+    protected
+
+    sig { void }
+    # Parses the input file and sets variables on +@runtime+ as necessary
+    def parse_code_section!
+      @runtime.start! do
+        # TODO: this flow can probably be refactored, it used to have more needs back when we had to
+        # parse and save the code_section
+        parsing_code_section do |input|
+          csv_section = ::CSVPlusPlus::Parser::CodeSection.new.parse(input, @runtime)
+
+          # return the csv_section to the caller because they're gonna re-write input with it
+          next csv_section
+        end
+      end
+    end
+
+    sig { returns(::T::Array[::CSVPlusPlus::Row]) }
+    # Parse the CSV section and return an array of +Row+s
+    #
+    # @return [Array<Row>]
+    def parse_csv_section!
+      @runtime.start_at_csv! do
+        @runtime.map_lines(::CSV.new(::T.unsafe(@runtime.input))) do |csv_row|
+          parse_row(::T.cast(csv_row, ::T::Array[::String]))
+        end
+      end
+    ensure
+      # we're done with the file and everything is in memory
+      @runtime.cleanup!
+    end
+
+    sig { params(template: ::CSVPlusPlus::Template).returns(::T::Array[::T::Array[::CSVPlusPlus::Entities::Entity]]) }
+    # Iterates through each cell of each row and resolves it's variable and function references.
+    #
+    # @param template [Template]
+    #
+    # @return [Array<Entity>]
+    def resolve_all_cells!(template)
+      @runtime.start_at_csv! do
+        @runtime.map_all_cells(template.rows) do |cell|
+          cell.ast = @runtime.resolve_cell_value if cell.ast
+        end
+      end
+    end
+
+    sig { params(block: ::T.proc.void).void }
+    # Expanding rows
+    def expanding!(&block)
+      @runtime.start_at_csv! { block.call }
+    end
+
+    sig { params(block: ::T.proc.void).void }
+    # Binding all [[var=]] directives
+    def bind_all_vars!(&block)
+      @runtime.start_at_csv! { block.call }
+    end
+
+    private
+
+    sig { params(block: ::T.proc.params(arg0: ::String).returns(::String)).void }
+    def parsing_code_section(&block)
+      csv_section = block.call(::T.must(::T.must(@runtime.input).read))
+      @runtime.rewrite_input!(csv_section)
+    end
+
+    sig { params(csv_row: ::T::Array[::T.nilable(::String)]).returns(::CSVPlusPlus::Row) }
+    # Using the current +@runtime+ and the given +csv_row+ parse it into a +Row+ of +Cell+s
+    # +csv_row+ should have already been run through a CSV parser and is an array of strings
+    #
+    # @param csv_row [Array<Array<String>>]
+    #
+    # @return [Row]
+    def parse_row(csv_row)
+      row_modifier = ::CSVPlusPlus::Modifier.new(@options, row_level: true)
+
+      cells = @runtime.map_row(csv_row) { |value, _cell_index| parse_cell(value || '', row_modifier) }
+
+      ::CSVPlusPlus::Row.new(cells:, index: @runtime.row_index, modifier: row_modifier)
+    end
+
+    sig { params(value: ::String, row_modifier: ::CSVPlusPlus::Modifier::Modifier).returns(::CSVPlusPlus::Cell) }
+    def parse_cell(value, row_modifier)
+      cell_modifier = ::CSVPlusPlus::Modifier.new(@options)
+      parsed_value = ::CSVPlusPlus::Parser::Modifier.new(cell_modifier:, row_modifier:).parse(value, @runtime)
+
+      ::CSVPlusPlus::Cell.parse(parsed_value, runtime:, modifier: cell_modifier)
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/csv_plus_plus/entities/ast_builder.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Entities
+    # Some helpful functions that can be mixed into a class to help building ASTs
+    module ASTBuilder
+      extend ::T::Sig
+
+      sig do
+        params(
+          method_name: ::Symbol,
+          args: ::T.untyped,
+          kwargs: ::T.untyped,
+          block: ::T.untyped
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # Let the current class have functions which can build a given entity by calling it's type.  For example
+      # +number(1)+, +variable(:foo)+
+      #
+      # @param method_name [Symbol] The +method_name+ to respond to
+      # @param args [Array] The arguments to create the entity with
+      # @param kwargs [Hash] The arguments to create the entity with
+      #
+      # @return [Entity, #super]
+      # rubocop:disable Naming/BlockForwarding
+      def method_missing(method_name, *args, **kwargs, &block)
+        entity_class_name = method_name.to_s.split('_').map(&:capitalize).join.to_sym
+        ::CSVPlusPlus::Entities.const_get(entity_class_name).new(*args, **kwargs, &block)
+      rescue ::NameError
+        super
+      end
+      # rubocop:enable Naming/BlockForwarding
+
+      sig { params(method_name: ::Symbol, _args: ::T.untyped).returns(::T::Boolean) }
+      # Let the current class have functions which can build a given entity by calling it's type.  For example
+      # +number(1)+, +variable(:foo)+
+      #
+      # @param method_name [Symbol] The +method_name+ to respond to
+      # @param _args [::T.Untyped] The arguments to create the entity with
+      #
+      # @return [::T::Boolean, #super]
+      def respond_to_missing?(method_name, *_args)
+        !::CSVPlusPlus::Entities::Type.deserialize(method_name.to_s.gsub('_', '')).nil?
+      rescue ::KeyError
+        super
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/entities/boolean.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Entities
+    # A boolean value
+    #
+    # @attr_reader value [true, false]
+    class Boolean < Entity
+      sig { returns(::T::Boolean) }
+      attr_reader :value
+
+      sig { params(value: ::T.any(::String, ::T::Boolean)).void }
+      # @param value [::String, boolean]
+      def initialize(value)
+        super(::CSVPlusPlus::Entities::Type::Boolean)
+        # TODO: probably can do a lot better in general on type validation
+        @value = ::T.let(value.is_a?(::String) ? (value.downcase == 'true') : value, ::T::Boolean)
+      end
+
+      sig { override.params(_runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # @param _runtime [Runtime]
+      #
+      # @return [::String]
+      def evaluate(_runtime)
+        @value.to_s.upcase
+      end
+
+      sig { override.params(other: ::CSVPlusPlus::Entities::Entity).returns(::T::Boolean) }
+      # @param other [Entity]
+      #
+      # @return [::T::Boolean]
+      def ==(other)
+        return false unless super
+
+        other.is_a?(self.class) && value == other.value
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/entities/builtins.rb

@@ -0,0 +1,58 @@
+# typed: false
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Entities
+    # Provides ASTs for builtin functions and variables
+    module Builtins
+      extend ::CSVPlusPlus::Entities::ASTBuilder
+
+      VARIABLES = {
+        # The number (integer) of the current cell. Starts at 1
+        cellnum: runtime_value(->(r) { number(r.cell_index + 1) }),
+
+        # A reference to the current cell
+        cellref: runtime_value(->(r) { cell_reference(row_index: r.row_index, cell_index: r.cell_index) }),
+
+        # A reference to the row above
+        rowabove: runtime_value(->(r) { cell_reference(row_index: [0, (r.row_index - 1)].max) }),
+
+        # A reference to the row below
+        rowbelow: runtime_value(->(r) { cell_reference(row_index: r.row_index + 1) }),
+
+        # The number (integer) of the current row.  Starts at 1
+        rownum: runtime_value(->(r) { number(r.rownum) }),
+
+        # A reference to the current row
+        rowref: runtime_value(->(r) { cell_reference(row_index: r.row_index) })
+      }.freeze
+      public_constant :VARIABLES
+
+      FUNCTIONS = {
+        # TODO: A reference to a cell in a given row?
+        # A reference to a cell above the current row
+        # cellabove: runtime_value(->(r, args) { cell_reference(ref: [args[0], [1, (r.rownum - 1)].max].join) }),
+        cellabove: runtime_value(
+          lambda { |r, args|
+            cell_reference(cell_index: args[0].cell_index, row_index: [0, (r.row_index - 1)].max)
+          }
+        ),
+
+        # A reference to a cell in the current row
+        celladjacent: runtime_value(
+          lambda { |r, args|
+            cell_reference(cell_index: args[0].cell_index, row_index: r.row_index)
+          }
+        ),
+
+        # A reference to a cell below the current row
+        cellbelow: runtime_value(
+          lambda { |r, args|
+            cell_reference(cell_index: args[0].cell_index, row_index: r.row_index + 1)
+          }
+        )
+      }.freeze
+      public_constant :FUNCTIONS
+    end
+  end
+end

data/lib/csv_plus_plus/entities/cell_reference.rb

@@ -0,0 +1,231 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Entities
+    # A reference to a cell. Internally it is represented by a simple +cell_index+ and +row_index+ but there are
+    # functions for converting to and from A1-style formats.  Supported formats are:
+    #
+    # * `1` - A reference to the entire first row
+    # * `A` - A reference to the entire first column
+    # * `A1` - A reference to the first cell (top left)
+    # * `A1:D10` - The range defined between A1 and D10
+    # * `Sheet1!B2` - Cell B2 on the sheet "Sheet1"
+    #
+    # @attr sheet_name [String, nil] The name of the sheet reference
+    # @attr_reader cell_index [Integer, nil] The cell index of the cell being referenced
+    # @attr_reader row_index [Integer, nil] The row index of the cell being referenced
+    # @attr_reader scoped_to_expand [Expand, nil] If set, the expand in which this variable is scoped to. It cannot be
+    #   resolved outside of the given expand.
+    # @attr_reader upper_cell_index [Integer, nil] If set, the cell reference is a range and this is the upper cell
+    #   index of it
+    # @attr_reader upper_row_index [Integer, nil] If set, the cell reference is a range and this is the upper row index
+    #   of it
+    # rubocop:disable Metrics/ClassLength
+    class CellReference < Entity
+      extend ::T::Sig
+
+      sig { returns(::T.nilable(::String)) }
+      attr_accessor :sheet_name
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :cell_index
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :row_index
+
+      sig { returns(::T.nilable(::CSVPlusPlus::Modifier::Expand)) }
+      attr_reader :scoped_to_expand
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :upper_cell_index
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :upper_row_index
+
+      # TODO: this is getting gross, maybe define an actual parser
+      A1_NOTATION_REGEXP = /
+        ^
+          (?:
+            (?:
+              (?:'([^'\\]|\\.)*') # allow for a single-quoted sheet name
+              |
+              (\w+)               # or if it's not quoted, just allow \w+
+            )
+            !                     # if a sheet name is specified, it's always followed by a !
+          )?
+          ([a-zA-Z0-9]+)          # the only part required - something alphanumeric
+          (?: :([a-zA-Z0-9]+))?   # and they might make it a range
+        $
+      /x
+      public_constant :A1_NOTATION_REGEXP
+
+      ALPHA = ::T.let(('A'..'Z').to_a.freeze, ::T::Array[::String])
+      private_constant :ALPHA
+
+      sig { params(cell_reference_string: ::String).returns(::T::Boolean) }
+      # Does the given +cell_reference_string+ conform to a valid cell reference?
+      #
+      # {https://developers.google.com/sheets/api/guides/concepts}
+      #
+      # @param cell_reference_string [::String] The string to check if it is a valid cell reference (we assume it's in
+      #   A1 notation but maybe can support R1C1)
+      #
+      # @return [::T::Boolean]
+      def self.valid_cell_reference?(cell_reference_string)
+        !(cell_reference_string =~ ::CSVPlusPlus::Entities::CellReference::A1_NOTATION_REGEXP).nil?
+      end
+
+      sig do
+        params(
+          cell_index: ::T.nilable(::Integer),
+          ref: ::T.nilable(::String),
+          row_index: ::T.nilable(::Integer),
+          scoped_to_expand: ::T.nilable(::CSVPlusPlus::Modifier::Expand)
+        ).void
+      end
+      # Either +ref+, +cell_index+ or +row_index+ must be specified.
+      #
+      # @param cell_index [Integer, nil] The index of the cell being referenced.
+      # @param ref [Integer, nil] An A1-style cell reference (that will be parsed into it's row/cell indexes).
+      # @param row_index [Integer, nil] The index of the row being referenced.
+      # @param scoped_to_expand [Expand] The [[expand]] that this cell reference will be scoped to. In other words, it
+      #   will only be able to be resolved if the runtime is within the bounds of the expand (it can't be referenced
+      #   outside of the expand.)
+      # rubocop:disable Metrics/MethodLength
+      def initialize(cell_index: nil, ref: nil, row_index: nil, scoped_to_expand: nil)
+        raise(::ArgumentError, 'Must specify :ref, :cell_index or :row_index') unless ref || cell_index || row_index
+
+        super(::CSVPlusPlus::Entities::Type::CellReference)
+
+        if ref
+          from_a1_ref!(ref)
+        else
+          @cell_index = ::T.let(cell_index, ::T.nilable(::Integer))
+          @row_index = ::T.let(row_index, ::T.nilable(::Integer))
+
+          @upper_cell_index = ::T.let(nil, ::T.nilable(::Integer))
+          @upper_row_index = ::T.let(nil, ::T.nilable(::Integer))
+        end
+
+        @scoped_to_expand = scoped_to_expand
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      sig { override.params(other: ::CSVPlusPlus::Entities::Entity).returns(::T::Boolean) }
+      # @param other [Entity]
+      #
+      # @return [boolean]
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def ==(other)
+        return false unless super
+
+        other.is_a?(self.class) && @cell_index == other.cell_index && @row_index == other.row_index \
+          && @sheet_name == other.sheet_name && @scoped_to_expand == other.scoped_to_expand \
+          && @upper_cell_index == other.upper_cell_index && @upper_row_index == other.upper_row_index
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      sig { override.params(runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # Get the A1-style cell reference
+      #
+      # @param runtime [Runtime] The current runtime
+      #
+      # @return [::String] An A1-style reference
+      def evaluate(runtime)
+        # unless in_scope?(runtime)
+        #   runtime.raise_modifier_syntax_error(message: 'Reference is out of scope', bad_input: runtime.cell.value)
+        # end
+
+        to_a1_ref(runtime) || ''
+      end
+
+      sig { returns(::T::Boolean) }
+      # Is the cell_reference a range? - something like A1:D10
+      #
+      # @return [boolean]
+      def range?
+        !upper_row_index.nil? || !upper_cell_index.nil?
+      end
+
+      private
+
+      sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::T.nilable(::String)) }
+      # Turns index-based/X,Y coordinates into a A1 format
+      #
+      # @param runtime [Runtime]
+      #
+      # @return [::String, nil]
+      def to_a1_ref(runtime)
+        row_index = runtime_row_index(runtime)
+        return unless row_index || @cell_index
+
+        rowref = row_index ? (row_index + 1).to_s : ''
+        cellref = @cell_index ? to_a1_cell_ref : ''
+        [cellref, rowref].join
+      end
+
+      sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::T.nilable(::Integer)) }
+      def runtime_row_index(runtime)
+        @scoped_to_expand ? runtime.row_index : @row_index
+      end
+
+      sig { returns(::String) }
+      # Turns a cell index into an A1 reference (just the "A" part - for example 0 == 'A', 1 == 'B', 2 == 'C', etc.)
+      #
+      # @return [::String]
+      def to_a1_cell_ref
+        c = @cell_index.dup
+        ref = ''
+
+        while c >= 0
+          # rubocop:disable Lint/ConstantResolution
+          ref += ::T.must(ALPHA[c % 26])
+          # rubocop:enable Lint/ConstantResolution
+          c = (c / 26).floor - 1
+        end
+
+        ref.reverse
+      end
+
+      sig { params(ref: ::String).void }
+      def from_a1_ref!(ref)
+        quoted_sheet_name, unquoted_sheet_name, lower_range, upper_range = ::T.must(
+          ref.strip.match(
+            ::CSVPlusPlus::Entities::CellReference::A1_NOTATION_REGEXP
+          )
+        ).captures
+
+        @sheet_name = quoted_sheet_name || unquoted_sheet_name
+
+        parse_lower_range!(lower_range) if lower_range
+        parse_upper_range!(upper_range) if upper_range
+      end
+
+      sig { params(lower_range: ::String).void }
+      def parse_lower_range!(lower_range)
+        cell_ref, row_ref = ::T.must(lower_range.match(/^([a-zA-Z]+)?(\d+)?$/)).captures
+        @cell_index = from_a1_cell_ref!(cell_ref) if cell_ref
+        @row_index = Integer(row_ref, 10) - 1 if row_ref
+      end
+
+      sig { params(upper_range: ::String).void }
+      # TODO: make this less redundant with the above function
+      def parse_upper_range!(upper_range)
+        cell_ref, row_ref = ::T.must(upper_range.match(/^([a-zA-Z]+)?(\d+)?$/)).captures
+        @upper_cell_index = from_a1_cell_ref!(cell_ref) if cell_ref
+        @upper_row_index = Integer(row_ref, 10) - 1 if row_ref
+      end
+
+      sig { params(cell_ref: ::String).returns(::Integer) }
+      def from_a1_cell_ref!(cell_ref)
+        (cell_ref.upcase.chars.reduce(0) do |cell_index, letter|
+          # rubocop:disable Lint/ConstantResolution
+          (cell_index * 26) + ::T.must(ALPHA.find_index(letter)) + 1
+          # rubocop:enable Lint/ConstantResolution
+        end) - 1
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/csv_plus_plus/entities/date.rb

@@ -0,0 +1,63 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Entities
+    # A date value
+    #
+    # @attr_reader value [Date] The parsed date
+    class Date < Entity
+      extend ::T::Sig
+
+      sig { returns(::Date) }
+      attr_reader :value
+
+      # TODO: support time granularity?
+      DATE_STRING_REGEXP = %r{^\d{1,2}[/-]\d{1,2}[/-]\d{1,4}?$}
+      public_constant :DATE_STRING_REGEXP
+
+      sig { params(date_string: ::String).returns(::T::Boolean) }
+      # Is the given string a valid date?
+      #
+      # @param date_string [::String]
+      def self.valid_date?(date_string)
+        new(date_string)
+        true
+      rescue ::Date::Error
+        false
+      end
+
+      sig { params(value: ::String).void }
+      # @param value [::String] The user-inputted date value
+      def initialize(value)
+        super(::CSVPlusPlus::Entities::Type::Date)
+
+        parsed =
+          begin
+            ::Date.parse(value)
+          rescue ::Date::Error
+            ::Date.strptime(value, '%d/%m/%yyyy')
+          end
+        @value = ::T.let(parsed, ::Date)
+      end
+
+      sig { override.params(_runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # @param _runtime [Runtime]
+      #
+      # @return [::String]
+      def evaluate(_runtime)
+        @value.strftime('%m/%d/%y')
+      end
+
+      sig { override.params(other: ::CSVPlusPlus::Entities::Entity).returns(::T::Boolean) }
+      # @param other [Entity]
+      #
+      # @return [T::Boolean]
+      def ==(other)
+        return false unless super
+
+        other.is_a?(self.class) && other.value == @value
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/entities/entity.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Entities
+    # A basic building block of the abstract syntax tree (AST)
+    #
+    # @attr_reader id [Symbol] The identifier of the entity.  For functions this is the function name,
+    #   for variables it's the variable name
+    # @attr_reader type [Entities::Type] The type of the entity. Each type should have a corresponding class definition
+    #   in CSVPlusPlus::Entities
+    class Entity
+      extend ::T::Sig
+      extend ::T::Helpers
+
+      abstract!
+
+      sig { returns(::T.nilable(::Symbol)) }
+      attr_reader :id
+
+      sig { returns(::CSVPlusPlus::Entities::Type) }
+      attr_reader :type
+
+      sig { params(type: ::CSVPlusPlus::Entities::Type, id: ::T.nilable(::Symbol)).void }
+      # @param type [Entities::Type]
+      # @param id [Symbol, nil]
+      def initialize(type, id: nil)
+        @type = type
+        @id = ::T.let(id&.downcase&.to_sym || nil, ::T.nilable(::Symbol))
+      end
+
+      sig { overridable.params(other: ::CSVPlusPlus::Entities::Entity).returns(::T::Boolean) }
+      # Each class should define it's own version of #==
+      # @param other [Entity]
+      #
+      # @return [boolean]
+      def ==(other)
+        self.class == other.class && @type == other.type && @id == other.id
+      end
+
+      sig { abstract.params(_runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # Uses the given +runtime+ to evaluate itself in the current context
+      #
+      # @param _runtime [Runtime] The current runtime
+      #
+      # @return [::String]
+      def evaluate(_runtime); end
+    end
+  end
+end