Class: Parlour::TypeParser

Inherits:

Object

• Object
• Parlour::TypeParser

Extended by:

T::Sig

Defined in:

lib/parlour/type_parser.rb

Overview

Parses Ruby source to find Sorbet type signatures.

Defined Under Namespace

Classes: IntermediateSig, NodePath

Instance Attribute Summary

• #ast ⇒ Parser::AST::Node

  The AST which this type parser should use.

• #generator ⇒ RbiGenerator

  The RbiGenerator to load the source into.

• #unknown_node_errors ⇒ Boolean readonly

  Whether to raise an error if a node of an unknown kind is encountered.

Class Method Summary

• .from_source(filename, source, generator: nil) ⇒ TypeParser

  Creates a new TypeParser from a source file and its filename.

Instance Method Summary

• #initialize(ast, unknown_node_errors: false, generator: nil) ⇒ TypeParser constructor

  Creates a new TypeParser from whitequark/parser AST.

• #parse_all ⇒ Object
• #parse_method_into_methods(path, is_within_eigenclass: false) ⇒ <RbiGenerator::Method>

  Given a path to a method in the AST, finds the associated definition and parses them into methods.

• #parse_path_to_object(path, is_within_eigenclass: false) ⇒ Object
• #parse_sig_into_methods(path, is_within_eigenclass: false) ⇒ <RbiGenerator::Method>

  Given a path to a sig in the AST, finds the associated definition and parses them into methods.

• #parse_sig_into_sig(path) ⇒ IntermediateSig

  Given a path to a sig in the AST, parses that sig into an intermediate sig object.

Constructor Details

#initialize(ast, unknown_node_errors: false, generator: nil) ⇒ TypeParser

Creates a new Parlour::TypeParser from whitequark/parser AST.

# File 'lib/parlour/type_parser.rb', line 95

def initialize(ast, unknown_node_errors: false, generator: nil)
  @ast = ast
  @unknown_node_errors = unknown_node_errors
  @generator = generator || DetachedRbiGenerator.new
end

Instance Attribute Details

#ast ⇒ Parser::AST::Node

# File 'lib/parlour/type_parser.rb', line 119

def ast
  @ast
end

#generator ⇒ RbiGenerator

# File 'lib/parlour/type_parser.rb', line 128

def generator
  @generator
end

#unknown_node_errors ⇒ Boolean (readonly)

# File 'lib/parlour/type_parser.rb', line 124

def unknown_node_errors
  @unknown_node_errors
end

Class Method Details

.from_source(filename, source, generator: nil) ⇒ TypeParser

Creates a new Parlour::TypeParser from a source file and its filename.

# File 'lib/parlour/type_parser.rb', line 108

def self.from_source(filename, source, generator: nil)
  buffer = Parser::Source::Buffer.new(filename)
  buffer.source = source

  # || special case handles parser returning nil on an empty file
  parsed = Parser::CurrentRuby.new.parse(buffer) || Parser::AST::Node.new(:body)
  TypeParser.new(parsed, generator: generator)
end

Instance Method Details

#parse_all ⇒ Object

# File 'lib/parlour/type_parser.rb', line 134

def parse_all
  root = generator.root
  root.children.concat(parse_path_to_object(NodePath.new([])))
  root
end

#parse_method_into_methods(path, is_within_eigenclass: false) ⇒ <RbiGenerator::Method>

Given a path to a method in the AST, finds the associated definition and parses them into methods. Usually this will return one method; the only exception currently is for attributes, where multiple can be declared in one call, e.g. attr_reader :x, :y, :z.

# File 'lib/parlour/type_parser.rb', line 609

def parse_method_into_methods(path, is_within_eigenclass: false)
  # A :def node represents a definition like "def x; end"
  # A :defs node represents a definition like "def self.x; end"
  def_node = path.traverse(ast)
  case def_node.type
  when :def
    class_method = false
    def_names = [def_node.to_a[0].to_s]
    def_params = def_node.to_a[1].to_a
    kind = :def
  when :defs
    parse_err 'targeted definitions on a non-self target are not supported', def_node \
      unless def_node.to_a[0].type == :self
    class_method = true
    def_names = [def_node.to_a[1].to_s]
    def_params = def_node.to_a[2].to_a
    kind = :def
  when :send
    target, method_name, *parameters = *def_node

    parse_err 'node after a sig must be a method definition', def_node \
      unless [:attr_reader, :attr_writer, :attr_accessor].include?(method_name) \
        || target != nil

    parse_err 'typed attribute should have at least one name', def_node if parameters&.length == 0

    kind = :attr
    attr_direction = method_name.to_s.gsub('attr_', '').to_sym
    def_names = T.must(parameters).map { |param| param.to_a[0].to_s }
    class_method = false
  else
    parse_err 'node after a sig must be a method definition', def_node
  end

  if is_within_eigenclass
    parse_err 'cannot represent multiple levels of eigenclassing', def_node if class_method
    class_method = true
  end

  return_type = "T.untyped"

  if kind == :def
    parameters = def_params.map do |def_param|
      arg_name = def_param.to_a[0]

      # TODO: anonymous restarg
      full_name = arg_name.to_s
      full_name = "*#{arg_name}"  if def_param.type == :restarg
      full_name = "**#{arg_name}" if def_param.type == :kwrestarg
      full_name = "#{arg_name}:"  if def_param.type == :kwarg || def_param.type == :kwoptarg
      full_name = "&#{arg_name}"  if def_param.type == :blockarg

      default = def_param.to_a[1] ? node_to_s(def_param.to_a[1]) : nil
      type = nil

      RbiGenerator::Parameter.new(full_name, type: type, default: default)
    end

    # There should only be one ever here, but future-proofing anyway
    def_names.map do |def_name|
      RbiGenerator::Method.new(
        generator,
        def_name,
        parameters,
        return_type,
        class_method: class_method
      )
    end
  elsif kind == :attr
    case attr_direction
    when :reader, :accessor, :writer
      attr_type = return_type
    else
      raise "unknown attribute direction #{attr_direction}"
    end

    def_names.map do |def_name|
      RbiGenerator::Attribute.new(
        generator,
        def_name,
        attr_direction,
        attr_type,
        class_attribute: class_method
      )
    end
  else
    raise "unknown definition kind #{kind}"
  end
end

#parse_path_to_object(path, is_within_eigenclass: false) ⇒ Object

# File 'lib/parlour/type_parser.rb', line 152

def parse_path_to_object(path, is_within_eigenclass: false)
  node = path.traverse(ast)

  case node.type
  when :class
    parse_err 'cannot declare classes in an eigenclass', node if is_within_eigenclass

    name, superclass, body = *node
    final = body_has_modifier?(body, :final!)
    abstract = body_has_modifier?(body, :abstract!)
    includes, extends = body ? body_includes_and_extends(body) : [[], []]

    # Create all classes, if we're given a definition like "class A::B"
    *parent_names, this_name = constant_names(name)
    target = T.let(nil, T.nilable(RbiGenerator::Namespace))
    top_level = T.let(nil, T.nilable(RbiGenerator::Namespace))
    parent_names.each do |n|
      new_obj = RbiGenerator::Namespace.new(
        generator,
        n.to_s,
        false,
      )
      target.children << new_obj if target
      target = new_obj
      top_level ||= new_obj
    end if parent_names

    # Instantiate the correct kind of class
    if ['T::Struct', '::T::Struct'].include?(node_to_s(superclass))
      # Find all of this struct's props and consts
      # The body is typically a `begin` element but when there's only
      # one node there's no wrapping block and instead it would directly
      # be the node.
      prop_nodes = body.nil? ? [] :
        (body.type == :begin ? body.to_a : [body]).select { |x| x.type == :send && [:prop, :const].include?(x.to_a[1]) }

      props = prop_nodes.map do |prop_node|
        _, prop_type, name_node, type_node, extras_hash_node = *prop_node

        # "const" is just "prop ..., immutable: true"
        extras_hash = extras_hash_node.to_a.map do |pair_node|
          key_node, value_node = *pair_node
          parse_err 'prop/const key must be a symbol', prop_node unless key_node.type == :sym
          key = key_node.to_a.first

          value =
            if key == :default
              T.must(node_to_s(value_node))
            else
              case value_node.type
              when :true
                true
              when :false
                false
              when :sym
                value_node.to_a.first
              else
                T.must(node_to_s(value_node))
              end
            end

          [key, value]
        end.to_h

        if prop_type == :const
          parse_err 'const cannot use immutable key', prop_node unless extras_hash[:immutable].nil?
          extras_hash[:immutable] = true
        end

        # Get prop/const name
        parse_err 'prop/const name must be a symbol or string', prop_node unless [:sym, :str].include?(name_node.type)
        name = name_node.to_a.first.to_s

        RbiGenerator::StructProp.new(
          name,
          T.must(node_to_s(type_node)),
          **T.unsafe(extras_hash)
        )
      end

      final_obj = RbiGenerator::StructClassNamespace.new(
        generator,
        this_name.to_s,
        final,
        props,
        abstract,
      )
    elsif ['T::Enum', '::T::Enum'].include?(node_to_s(superclass))
      # Look for (block (send nil :enums) ...) structure
      enums_node = body.nil? ? nil :
        (body.type == :begin ? body.to_a : [body]).find { |x| x.type == :block && x.to_a[0].type == :send && x.to_a[0].to_a[1] == :enums }

      # Find the constant assigments within this block
      constant_nodes = enums_node.to_a[2].to_a

      # Convert this to an array to enums as EnumClassNamespace expects
      enums = constant_nodes.map do |constant_node|
        _, name, new_node = *constant_node
        serialize_value = node_to_s(new_node.to_a[2])

        serialize_value ? [name.to_s, serialize_value] : name.to_s
      end

      final_obj = RbiGenerator::EnumClassNamespace.new(
        generator,
        this_name.to_s,
        final,
        enums,
        abstract,
      )
    else
      final_obj = RbiGenerator::ClassNamespace.new(
        generator,
        this_name.to_s,
        final,
        node_to_s(superclass),
        abstract,
      )
    end

    final_obj.children.concat(parse_path_to_object(path.child(2))) if body
    final_obj.create_includes(includes)
    final_obj.create_extends(extends)

    if target
      target.children << final_obj
      [top_level]
    else
      [final_obj]
    end
  when :module
    parse_err 'cannot declare modules in an eigenclass', node if is_within_eigenclass

    name, body = *node
    final = body_has_modifier?(body, :final!)
    interface = body_has_modifier?(body, :interface!)
    includes, extends = body ? body_includes_and_extends(body) : [[], []]

    # Create all modules, if we're given a definition like "module A::B"
    *parent_names, this_name = constant_names(name)
    target = T.let(nil, T.nilable(RbiGenerator::Namespace))
    top_level = T.let(nil, T.nilable(RbiGenerator::Namespace))
    parent_names.each do |n|
      new_obj = RbiGenerator::Namespace.new(
        generator,
        n.to_s,
        false,
      )
      target.children << new_obj if target
      target = new_obj
      top_level ||= new_obj
    end if parent_names

    final_obj = RbiGenerator::ModuleNamespace.new(
      generator,
      this_name.to_s,
      final,
      interface,
    ) do |m|
      m.children.concat(parse_path_to_object(path.child(1))) if body
      m.create_includes(includes)
      m.create_extends(extends)
    end

    if target
      target.children << final_obj
      [top_level]
    else
      [final_obj]
    end
  when :send, :block
    if sig_node?(node)
      parse_sig_into_methods(path, is_within_eigenclass: is_within_eigenclass)
    elsif node.type == :send &&
        [:attr_reader, :attr_writer, :attr_accessor].include?(node.to_a[1]) &&
        !previous_sibling_sig_node?(path)
      parse_method_into_methods(path, is_within_eigenclass: is_within_eigenclass)
    else
      []
    end
  when :def, :defs
    if previous_sibling_sig_node?(path)
      []
    else
      parse_method_into_methods(path, is_within_eigenclass: is_within_eigenclass)
    end
  when :sclass
    parse_err 'cannot access eigen of non-self object', node unless node.to_a[0].type == :self
    parse_path_to_object(path.child(1), is_within_eigenclass: true)
  when :begin
    # Just map over all the things
    node.to_a.length.times.map do |c|
      parse_path_to_object(path.child(c), is_within_eigenclass: is_within_eigenclass)
    end.flatten
  when :casgn
    _, name, body = *node
    [Parlour::RbiGenerator::Constant.new(
      generator,
      name: T.must(name).to_s,
      value: T.must(node_to_s(body)),
    )]
  else
    if unknown_node_errors
      parse_err "don't understand node type #{node.type}", node
    else
      []
    end
  end
end

#parse_sig_into_methods(path, is_within_eigenclass: false) ⇒ <RbiGenerator::Method>

Given a path to a sig in the AST, finds the associated definition and parses them into methods. This will raise an exception if the sig is invalid. Usually this will return one method; the only exception currently is for attributes, where multiple can be declared in one call, e.g. attr_reader :x, :y, :z.

# File 'lib/parlour/type_parser.rb', line 460

def parse_sig_into_methods(path, is_within_eigenclass: false)
  sig_block_node = path.traverse(ast)

  # A :def node represents a definition like "def x; end"
  # A :defs node represents a definition like "def self.x; end"
  def_node = path.sibling(1).traverse(ast)
  case def_node.type
  when :def
    class_method = false
    def_names = [def_node.to_a[0].to_s]
    def_params = def_node.to_a[1].to_a
    kind = :def
  when :defs
    parse_err 'targeted definitions on a non-self target are not supported', def_node \
      unless def_node.to_a[0].type == :self
    class_method = true
    def_names = [def_node.to_a[1].to_s]
    def_params = def_node.to_a[2].to_a
    kind = :def
  when :send
    target, method_name, *parameters = *def_node

    parse_err 'node after a sig must be a method definition', def_node \
      unless [:attr_reader, :attr_writer, :attr_accessor].include?(method_name) \
        || target != nil

    parse_err 'typed attribute should have at least one name', def_node if parameters&.length == 0

    kind = :attr
    attr_direction = method_name.to_s.gsub('attr_', '').to_sym
    def_names = T.must(parameters).map { |param| param.to_a[0].to_s }
    class_method = false
  else
    parse_err 'node after a sig must be a method definition', def_node
  end

  if is_within_eigenclass
    parse_err 'cannot represent multiple levels of eigenclassing', def_node if class_method
    class_method = true
  end

  this_sig = parse_sig_into_sig(path)
  params = this_sig.params
  return_type = this_sig.return_type

  if kind == :def
    # Sorbet allows a trailing blockarg that's not in the sig
    if params &&
       def_params.length == params.length + 1 &&
       def_params[-1].type == :blockarg
      def_params = def_params[0...-1]
    end

    parse_err 'mismatching number of arguments in sig and def', sig_block_node \
      if params && def_params.length != params.length

    # sig_args will look like:
    #   [(pair (sym :x) <type>), (pair (sym :y) <type>), ...]
    # def_params will look like:
    #   [(arg :x), (arg :y), ...]
    parameters = params \
      ? zip_by(params, ->x{ x.to_a[0].to_a[0] }, def_params, ->x{ x.to_a[0] })
        .map do |sig_arg, def_param|

          arg_name = def_param.to_a[0]

          # TODO: anonymous restarg
          full_name = arg_name.to_s
          full_name = "*#{arg_name}"  if def_param.type == :restarg
          full_name = "**#{arg_name}" if def_param.type == :kwrestarg
          full_name = "#{arg_name}:"  if def_param.type == :kwarg || def_param.type == :kwoptarg
          full_name = "&#{arg_name}"  if def_param.type == :blockarg

          default = def_param.to_a[1] ? node_to_s(def_param.to_a[1]) : nil
          type = node_to_s(sig_arg.to_a[1])

          RbiGenerator::Parameter.new(full_name, type: type, default: default)
        end
      : []

    # There should only be one ever here, but future-proofing anyway
    def_names.map do |def_name|
      RbiGenerator::Method.new(
        generator,
        def_name,
        parameters,
        return_type,
        type_parameters: this_sig.type_parameters,
        override: this_sig.override,
        overridable: this_sig.overridable,
        abstract: this_sig.abstract,
        final: this_sig.final,
        class_method: class_method
      )
    end
  elsif kind == :attr
    case attr_direction
    when :reader, :accessor
      parse_err "attr_#{attr_direction} sig should have no parameters", sig_block_node \
        if params && params.length > 0

      parse_err "attr_#{attr_direction} sig should have non-void return", sig_block_node \
        unless return_type

      attr_type = return_type
    when :writer
      # These are special and can only have one name
      raise 'typed attr_writer can only have one name' if def_names.length > 1

      def_name = def_names[0]
      parse_err "attr_writer sig should take one argument with the property's name", sig_block_node \
        if !params || params.length != 1 || params[0].to_a[0].to_a[0].to_s != def_name

      parse_err "attr_writer sig should have non-void return", sig_block_node \
        if return_type.nil?

      attr_type = T.must(node_to_s(params[0].to_a[1]))
    else
      raise "unknown attribute direction #{attr_direction}"
    end

    def_names.map do |def_name|
      RbiGenerator::Attribute.new(
        generator,
        def_name,
        attr_direction,
        attr_type,
        class_attribute: class_method
      )
    end
  else
    raise "unknown definition kind #{kind}"
  end
end

#parse_sig_into_sig(path) ⇒ IntermediateSig

Given a path to a sig in the AST, parses that sig into an intermediate sig object. This will raise an exception if the sig is invalid. This is intended to be called by #parse_sig_into_methods, and shouldn’t be called manually unless you’re doing something hacky.

# File 'lib/parlour/type_parser.rb', line 382

def parse_sig_into_sig(path)
  sig_block_node = path.traverse(ast)

  # A sig's AST uses lots of nested nodes due to a deep call chain, so let's
  # flatten it out to make it easier to work with
  sig_chain = []
  current_sig_chain_node = sig_block_node.to_a[2]
  while current_sig_chain_node
    name = current_sig_chain_node.to_a[1]
    arguments = current_sig_chain_node.to_a[2..-1]

    sig_chain << [name, arguments]
    current_sig_chain_node = current_sig_chain_node.to_a[0]
  end

  # Get basic boolean flags
  override =    !!sig_chain.find { |(n, a)| n == :override    && a.empty? }
  overridable = !!sig_chain.find { |(n, a)| n == :overridable && a.empty? }
  abstract =    !!sig_chain.find { |(n, a)| n == :abstract    && a.empty? }

  # Determine whether this method is final (i.e. sig(:final))
  _, _, *sig_arguments = *sig_block_node.to_a[0]
  final = sig_arguments.any? { |a| a.type == :sym && a.to_a[0] == :final }

  # Find the return type by looking for a "returns" call
  return_type = sig_chain
    .find { |(n, _)| n == :returns }
    &.then do |(_, a)|
      parse_err 'wrong number of arguments in "returns" for sig', sig_block_node if a.length != 1
      node_to_s(a[0])
    end

  # Find the arguments specified in the "params" call in the sig
  sig_args = sig_chain
    .find { |(n, _)| n == :params }
    &.then do |(_, a)|
      parse_err 'wrong number of arguments in "params" for sig', sig_block_node if a.length != 1
      arg = a[0]
      parse_err 'argument to "params" should be a hash', arg unless arg.type == :hash
      arg.to_a
    end

  # Find type parameters if they were used
  type_parameters = sig_chain
    .find { |(n, _)| n == :type_parameters }
    &.then do |(_, a)|
      a.map do |arg|
        parse_err 'type parameter must be a symbol', arg if arg.type != :sym
        arg.to_a[0]
      end
    end

  IntermediateSig.new(
    type_parameters: type_parameters,
    overridable: overridable,
    override: override,
    abstract: abstract,
    final: final,
    params: sig_args,
    return_type: return_type
  )
end