parlour 4.0.0 → 5.0.0.beta.4

data/lib/parlour/rbs_generator/parameter.rb

@@ -0,0 +1,146 @@
+# typed: true
+module Parlour
+  class RbsGenerator < Generator
+    # Represents a method parameter with a Sorbet type signature.
+    class Parameter
+      extend T::Sig
+
+      sig do
+        params(
+          name: String,
+          type: T.nilable(Types::TypeLike),
+          required: T::Boolean,
+        ).void
+      end
+      # Create a new method parameter.
+      # Note that, in RBS, blocks are not parameters. Use a {Block} instead.
+      #
+      # @example Create a simple Integer parameter named +num+.
+      #   Parlour::RbsGenerator::Parameter.new('num', type: 'Integer')
+      # @example Create a nilable array parameter.
+      #   Parlour::RbsGenerator::Parameter.new('array_of_strings_or_symbols', type:
+      #     Parlour::Types::Nilable.new(
+      #       Parlour::Types::Array.new(
+      #         Parlour::Types::Union.new('String', 'Symbol')
+      #       )
+      #     )
+      #   )
+      # @example Create an optional parameter.
+      #   Parlour::RbsGenerator::Parameter.new('name', type: 'String', default: 'Parlour')
+      #
+      # @param name [String] The name of this parameter. This may start with +*+ or +**+,
+      #   ,or end with +:+, which will infer the {kind} of this
+      #   parameter. (If it contains none of those, {kind} will be +:normal+.)
+      # @param type [Types::TypeLike, nil] This type of this parameter.
+      # @param required [Boolean] Whether this parameter is required.
+      # @return [void]
+      def initialize(name, type: nil, required: true)
+        name = T.must(name)
+        @name = name
+
+        prefix = /^(\*\*|\*|\&)?/.match(name)&.captures&.first || ''
+        @kind = PREFIXES.rassoc(prefix).first
+
+        @kind = :keyword if kind == :normal && name.end_with?(':')
+
+        @type = type || Parlour::Types::Untyped.new
+        @required = required
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      # Returns true if this instance is equal to another method.
+      #
+      # @param other [Object] The other instance. If this is not a {Parameter} (or a
+      #   subclass of it), this will always return false.
+      # @return [Boolean]
+      def ==(other)
+        Parameter === other &&
+          name    == other.name &&
+          kind    == other.kind &&
+          type    == other.type &&
+          required == other.required
+      end
+
+      sig { returns(String) }
+      # The name of this parameter, including any prefixes or suffixes such as
+      # +*+.
+      # @return [String]
+      attr_reader :name
+
+      sig { returns(String) }
+      # The name of this parameter, stripped of any prefixes or suffixes. For
+      # example, +*rest+ would become +rest+, or +foo:+ would become +foo+.
+      #
+      # @return [String]
+      def name_without_kind
+        return T.must(name[0..-2]) if kind == :keyword
+
+        prefix_match = /^(\*\*|\*|\&)?[a-zA-Z_]/.match(name)
+        raise 'unknown prefix' unless prefix_match
+        prefix = prefix_match.captures.first || ''
+        T.must(name[prefix.length..-1])
+      end
+
+      sig { returns(Types::TypeLike) }
+      # This parameter's type.
+      # @return [String]
+      attr_reader :type
+
+      sig { returns(T::Boolean) }
+      # Whether this parameter is required.
+      # @return [Boolean]
+      attr_reader :required
+
+      sig { returns(Symbol) }
+      # The kind of parameter that this is. This will be one of +:normal+, 
+      # +:splat+, +:double_splat+, or +:keyword+.
+      # @return [Symbol]
+      attr_reader :kind
+
+      # An array of reserved keywords in RBS which may be used as parameter
+      # names in standard Ruby.
+      # TODO: probably incomplete
+      RBS_KEYWORDS = [
+        'type', 'interface', 'out', 'in', 'instance', 'extension', 'top', 'bot',
+        'self', 'nil', 'void'
+      ]
+
+      # A mapping of {kind} values to the characteristic prefixes each kind has.
+      PREFIXES = {
+        normal: '',
+        splat: '*',
+        double_splat: '**',
+      }.freeze      
+
+      sig { returns(String) }
+      # A string of how this parameter should be defined in an RBS signature.
+      #
+      # @return [String]
+      def to_rbs_param
+        raise 'blocks are not parameters in RBS' if kind == :block
+
+        t = String === @type ? @type : @type.generate_rbs
+        t = "^#{t}" if Types::Proc === @type
+
+        if RBS_KEYWORDS.include? name_without_kind
+          unless $VERBOSE.nil?
+            print Rainbow("Parlour warning: ").yellow.dark.bold
+            print Rainbow("RBS generation: ").magenta.bright.bold
+            puts "'#{name_without_kind}' is a keyword in RBS, renaming method parameter to '_#{name_without_kind}'"
+          end
+          
+          n = "_#{name_without_kind}"
+        else
+          n = name_without_kind
+        end
+
+        # Extra check because "?*something" is invalid
+        ((required || (kind != :normal && kind != :keyword)) ? '' : '?') + if kind == :keyword
+          "#{n}: #{t}"
+        else
+          "#{PREFIXES[kind]}#{t} #{n}"
+        end
+      end
+    end
+  end
+end

data/lib/parlour/rbs_generator/rbs_object.rb

@@ -0,0 +1,78 @@
+# typed: true
+module Parlour
+  class RbsGenerator < Generator
+    # An abstract class which is subclassed by any classes which can generate
+    # entire lines of an RBS, such as {Namespace} and {Method}. (As an example,
+    # {Parameter} is _not_ a subclass because it does not generate lines, only
+    # segments of definition lines.)
+    # @abstract
+    class RbsObject < TypedObject
+      abstract!
+      
+      sig { params(generator: Generator, name: String).void }
+      # Creates a new RBS object.
+      # @note Don't call this directly.
+      #
+      # @param generator [RbsGenerator] The current RbsGenerator.
+      # @param name [String] The name of this module.
+      # @return [void]
+      def initialize(generator, name)
+        super(name)
+        @generator = generator
+        @generated_by = RbsGenerator === generator ? generator.current_plugin : nil
+      end
+
+      sig { returns(Generator) }
+      # The generator which this object belongs to.
+      # @return [Generator]
+      attr_reader :generator
+
+      sig do
+        abstract.params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      # Generates the RBS lines for this object.
+      #
+      # @abstract
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBS lines, formatted as specified.
+      def generate_rbs(indent_level, options); end
+
+      sig do
+        abstract.params(
+          others: T::Array[RbsGenerator::RbsObject]
+        ).returns(T::Boolean)
+      end
+      # Given an array of other objects, returns true if they may be merged
+      # into this instance using {merge_into_self}. Each subclass will have its
+      # own criteria on what allows objects to be mergeable.
+      #
+      # @abstract
+      # @param others [Array<RbsGenerator::RbsObject>] An array of other {RbsObject} instances.
+      # @return [Boolean] Whether this instance may be merged with them.
+      def mergeable?(others); end
+
+      sig do 
+        abstract.params(
+          others: T::Array[RbsGenerator::RbsObject]
+        ).void
+      end
+      # Given an array of other objects, merges them into this one. Each
+      # subclass will do this differently.
+      # You MUST ensure that {mergeable?} is true for those instances.
+      #
+      # @abstract
+      # @param others [Array<RbsGenerator::RbsObject>] An array of other {RbsObject} instances.
+      # @return [void]
+      def merge_into_self(others); end
+
+      sig { overridable.override.returns(String) }
+      def describe
+        'RBS object'
+      end  
+    end
+  end
+end

data/lib/parlour/rbs_generator/type_alias.rb

@@ -0,0 +1,96 @@
+# typed: true
+module Parlour
+  class RbsGenerator < Generator
+    # Represents a type alias.
+    class TypeAlias < RbsObject
+      sig do
+        params(
+          generator: Generator,
+          name: String,
+          type: Types::TypeLike,
+          block: T.nilable(T.proc.params(x: TypeAlias).void)
+        ).void
+      end
+      # Creates a new type alias.
+      #
+      # @param name [String] The name of the alias.
+      # @param value [String] The type to alias to.
+      def initialize(generator, name:, type:, &block)
+        super(generator, name)
+        @type = type
+        yield_self(&block) if block
+      end
+
+      # @return [String] The type to alias to.
+      sig { returns(Types::TypeLike) }
+      attr_reader :type
+
+      sig { params(other: Object).returns(T::Boolean) }
+      # Returns true if this instance is equal to another type alias.
+      #
+      # @param other [Object] The other instance. If this is not a {TypeAlias} (or a
+      #   subclass of it), this will always return false.
+      # @return [Boolean]
+      def ==(other)
+        TypeAlias === other && name == other.name && type == other.type
+      end
+
+      sig do
+        override.params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      # Generates the RBS lines for this type alias.
+      #
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBS lines, formatted as specified.
+      def generate_rbs(indent_level, options)
+        [options.indented(indent_level,
+          "type #{name} = #{String === @type ? @type : @type.generate_rbs}"
+        )]
+      end
+
+      sig do
+        override.params(
+          others: T::Array[RbsGenerator::RbsObject]
+        ).returns(T::Boolean)
+      end
+      # Given an array of {TypeAlias} instances, returns true if they may be 
+      # merged into this instance using {merge_into_self}. This is always false.
+      #
+      # @param others [Array<RbiGenerator::RbsObject>] An array of other
+      #   {TypeAlias} instances.
+      # @return [Boolean] Whether this instance may be merged with them.
+      def mergeable?(others)
+        others.all? { |other| self == other }
+      end
+
+      sig do
+        override.params(
+          others: T::Array[RbsGenerator::RbsObject]
+        ).void
+      end
+      # Given an array of {TypeAlias} instances, merges them into this one.
+      # This particular implementation will simply do nothing, as instances
+      # are only mergeable if they are indentical.
+      # You MUST ensure that {mergeable?} is true for those instances.
+      #
+      # @param others [Array<RbiGenerator::RbsObject>] An array of other
+      #   {TypeAlias} instances.
+      # @return [void]
+      def merge_into_self(others)
+        # We don't need to change anything! We only merge identical type alias
+      end
+
+      sig { override.returns(String) }
+      # Returns a human-readable brief string description of this code.
+      #
+      # @return [String]
+      def describe
+        "Type Alias (#{name} = #{type})"
+      end
+    end
+  end
+end

data/lib/parlour/type_parser.rb

@@ -345,11 +345,28 @@ module Parlour
         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)),
-        )]
+
+        # Determine whether this is a constant or a type alias
+        # A type alias looks like:
+        #   (block (send (const nil :T) :type_alias) (args) (type_to_alias))
+        if body.type == :block &&
+          body.to_a[0].type == :send &&
+          body.to_a[0].to_a[0].type == :const &&
+          body.to_a[0].to_a[0].to_a == [nil, :T] &&
+          body.to_a[0].to_a[1] == :type_alias
+
+          [Parlour::RbiGenerator::TypeAlias.new(
+            generator,
+            name: T.must(name).to_s,
+            type: T.must(node_to_s(body.to_a[2])),
+          )]
+        else
+          [Parlour::RbiGenerator::Constant.new(
+            generator,
+            name: T.must(name).to_s,
+            value: T.must(node_to_s(body)),
+          )]
+        end
       else
         if unknown_node_errors
           parse_err "don't understand node type #{node.type}", node
@@ -696,8 +713,160 @@ module Parlour
       end
     end
 
+    sig { params(str: String).returns(Types::Type) }
+    # TODO doc
+    def self.parse_single_type(str)
+      i = TypeParser.from_source('(none)', str)
+      i.parse_node_to_type(i.ast)
+    end
+
+    sig { params(node: Parser::AST::Node).returns(Types::Type) }
+    # Given an AST node representing an RBI type (such as 'T::Array[String]'),  
+    # parses it into a generic type.
+    #
+    # @param [Parser::AST::Node] node
+    # @return [Parlour::Types::Type]
+    def parse_node_to_type(node)
+      case node.type
+      when :send
+        target, message, *args = *node
+
+        # Special case: is this a generic type instantiation?
+        if message == :[]
+          names = constant_names(target)
+          known_single_element_collections = [:Array, :Set, :Range, :Enumerator, :Enumerable]
+
+          if names.length == 2 && names[0] == :T && 
+            known_single_element_collections.include?(names[1])
+            
+            parse_err "no type in T::#{names[1]}[...]", node if args.nil? || args.empty?
+            parse_err "too many types in T::#{names[1]}[...]", node unless args.length == 1
+            return T.must(Types.const_get(T.must(names[1]))).new(parse_node_to_type(T.must(args.first)))
+          elsif names.length == 2 && names == [:T, :Hash]
+            parse_err "not enough types in T::Hash[...]", node if args.nil? || args.length < 2
+            parse_err "too many types in T::Hash[...]", node unless args.length == 2
+            return Types::Hash.new(
+              parse_node_to_type(args[0]), parse_node_to_type(args[1])
+            )
+          else
+            # TODO
+            warning "user-defined generic types not implemented, treating #{names.last} as untyped", node
+            return Types::Untyped.new
+          end
+        end
+
+        # Special case: is this a proc?
+        # This parsing is pretty simplified, but you'd also have to be doing
+        # something pretty cursed with procs to break this
+        # This checks for (send (send (send (const nil :T) :proc) ...) ...)
+        # That's the right amount of nesting for T.proc.params(...).returns(...)
+        if node.to_a[0].type == :send && 
+          node.to_a[0].to_a[0].type == :send &&
+          node.to_a[0].to_a[0].to_a[1] == :proc &&
+          node.to_a[0].to_a[0].to_a[0].type == :const &&
+          node.to_a[0].to_a[0].to_a[0].to_a == [nil, :T] # yuck
+
+          # Get parameters
+          params_send = node.to_a[0]
+          parse_err "expected 'params' to follow 'T.proc'", node unless params_send.to_a[1] == :params
+          parse_err "expected 'params' to have kwargs", node unless params_send.to_a[2].type == :hash
+
+          parameters = params_send.to_a[2].to_a.map do |pair|
+            name, value = *pair
+            parse_err "expected 'params' name to be symbol", node unless name.type == :sym
+            name = name.to_a[0].to_s
+            value = parse_node_to_type(value)
+
+            RbiGenerator::Parameter.new(name, type: value)
+          end
+
+          # Get return value
+          if node.to_a[1] == :void
+            return_type = nil
+          else
+            _, call, *args = *node
+            parse_err 'expected .returns or .void', node unless call == :returns
+            parse_err 'no argument to .returns', node if args.nil? || args.empty?
+            parse_err 'too many arguments to .returns', node unless args.length == 1
+            return_type = parse_node_to_type(T.must(args.first))
+          end
+
+          return Types::Proc.new(parameters, return_type)
+        end
+
+        # The other options for a valid call are all "T.something" methods
+        parse_err "unexpected call #{node_to_s(node).inspect} in type", node \
+          unless target.type == :const && target.to_a == [nil, :T]
+            
+        case message
+        when :nilable
+          parse_err 'no argument to T.nilable', node if args.nil? || args.empty?
+          parse_err 'too many arguments to T.nilable', node unless args.length == 1
+          Types::Nilable.new(parse_node_to_type(T.must(args.first)))
+        when :any
+          Types::Union.new((args || []).map { |x| parse_node_to_type(T.must(x)) })
+        when :all
+          Types::Intersection.new((args || []).map { |x| parse_node_to_type(T.must(x)) })
+        when :let
+          # Not really allowed in a type signature, but handy for generalizing
+          # constant types
+          parse_err 'not enough argument to T.let', node if args.nil? || args.length < 2
+          parse_err 'too many arguments to T.nilable', node unless args.length == 2
+          parse_node_to_type(args[1])
+        when :type_parameter
+          parse_err 'no argument to T.type_parameter', node if args.nil? || args.empty?
+          parse_err 'too many arguments to T.type_parameter', node unless args.length == 1
+          parse_err 'expected T.type_parameter to be passed a symbol', node unless T.must(args.first).type == :sym
+          Types::Raw.new(T.must(args.first.to_a[0].to_s))
+        when :class_of
+          parse_err 'no argument to T.class_of', node if args.nil? || args.empty?
+          parse_err 'too many arguments to T.class_of', node unless args.length == 1
+          Types::Class.new(parse_node_to_type(args[0]))
+        when :untyped
+          parse_err 'T.untyped does not accept arguments', node if !args.nil? && !args.empty?
+          Types::Untyped.new
+        else
+          warning "unknown method T.#{message}, treating as untyped", node
+          Types::Untyped.new
+        end 
+      when :const
+        # Special case: T::Boolean
+        if constant_names(node) == [:T, :Boolean]
+          return Types::Boolean.new
+        end
+
+        # Otherwise, just a plain old constant
+        Types::Raw.new(constant_names(node).join('::'))
+      when :array
+        # Tuple
+        Types::Tuple.new(node.to_a.map { |x| parse_node_to_type(T.must(x)) })
+      when :hash
+        # Shape/record
+        keys_to_types = node.to_a.map do |pair|
+          key, value = *pair
+          parse_err "all shape keys must be symbols", node unless key.type == :sym
+          [key.to_a[0], parse_node_to_type(value)]
+        end.to_h
+
+        Types::Record.new(keys_to_types)
+      else
+        parse_err "unable to parse type #{node_to_s(node).inspect}", node
+      end
+    end
+
     protected
 
+    sig { params(msg: String, node: Parser::AST::Node).void }
+    def warning(msg, node)
+      return if $VERBOSE.nil?
+
+      print Rainbow("Parlour warning: ").yellow.dark.bold
+      print Rainbow("Type generalization: ").magenta.bright.bold
+      puts msg
+      print Rainbow("      └ at code: ").blue.bright.bold
+      puts node_to_s(node)
+    end
+
     sig { params(node: T.nilable(Parser::AST::Node)).returns(T::Array[Symbol]) }
     # Given a node representing a simple chain of constants (such as A or
     # A::B::C), converts that node into an array of the constant names which