parlour 1.0.0 → 4.0.1

data/lib/parlour/detached_rbi_generator.rb

@@ -0,0 +1,25 @@
+# typed: true
+
+module Parlour
+  class DetachedRbiGenerator < RbiGenerator
+    sig { returns(T.untyped) }
+    def detached!
+      raise "cannot call methods on a detached RBI generator"
+    end
+
+    sig { override.returns(Options) }
+    def options
+      detached!
+    end
+
+    sig { override.returns(T.nilable(Plugin)) }
+    def current_plugin
+      nil
+    end
+
+    sig { override.params(strictness: String).returns(String) }
+    def rbi(strictness = 'strong')
+      detached!
+    end
+  end
+end

data/lib/parlour/kernel_hack.rb

@@ -3,4 +3,6 @@ module Kernel
     return to_enum(__method__) { 1 } unless block_given?
     yield self
   end unless method_defined? :yield_self
+
+  alias then yield_self
 end

data/lib/parlour/parse_error.rb

@@ -0,0 +1,19 @@
+# typed: true
+
+module Parlour
+  class ParseError < StandardError
+    extend T::Sig
+
+    sig { returns(Parser::Source::Buffer) }
+    attr_reader :buffer
+
+    sig { returns(Parser::Source::Range) }
+    attr_reader :range
+
+    def initialize(buffer, range)
+      super()
+      @buffer = buffer
+      @range = range
+    end
+  end
+end

data/lib/parlour/plugin.rb

@@ -50,7 +50,7 @@ module Parlour
       end
     end
 
-    sig { params(options: Hash).void }
+    sig { params(options: T::Hash[T.untyped, T.untyped]).void }
     def initialize(options); end
 
     sig { abstract.params(root: RbiGenerator::Namespace).void }

data/lib/parlour/rbi_generator.rb

@@ -4,7 +4,7 @@ module Parlour
   class RbiGenerator
     extend T::Sig
 
-    sig { params(break_params: Integer, tab_size: Integer).void }
+    sig { params(break_params: Integer, tab_size: Integer, sort_namespaces: T::Boolean).void }
     # Creates a new RBI generator.
     #
     # @example Create a default generator.
@@ -16,29 +16,35 @@ module Parlour
     # @param break_params [Integer] If there are at least this many parameters in a 
     #   Sorbet +sig+, then it is broken onto separate lines.
     # @param tab_size [Integer] The number of spaces to use per indent.
+    # @param sort_namespaces [Boolean] Whether to sort all items within a
+    #   namespace alphabetically.
     # @return [void]
-    def initialize(break_params: 4, tab_size: 2)
-      @options = Options.new(break_params: break_params, tab_size: tab_size)
+    def initialize(break_params: 4, tab_size: 2, sort_namespaces: false)
+      @options = Options.new(
+        break_params: break_params,
+        tab_size: tab_size,
+        sort_namespaces: sort_namespaces
+      )
       @root = Namespace.new(self)
     end
 
-    sig { returns(Options) }
+    sig { overridable.returns(Options) }
     # The formatting options for this generator.
     # @return [Options]
     attr_reader :options
 
-    sig { returns(Namespace) }
+    sig { overridable.returns(Namespace) }
     # The root {Namespace} of this generator.
     # @return [Namespace]
     attr_reader :root
 
-    sig { returns(T.nilable(Plugin)) }
+    sig { overridable.returns(T.nilable(Plugin)) }
     # The plugin which is currently generating new definitions.
     # {Plugin#run_plugins} controls this value.
     # @return [Plugin, nil]
     attr_accessor :current_plugin
 
-    sig { params(strictness: String).returns(String) }
+    sig { overridable.params(strictness: String).returns(String) }
     # Returns the complete contents of the generated RBI file as a string.
     #
     # @return [String] The generated RBI file

data/lib/parlour/rbi_generator/class_namespace.rb

@@ -70,19 +70,21 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
-      # Given an array of {ClassNamespace} instances, returns true if they may
+      # Given an array of {Namespace} instances, returns true if they may
       # be merged into this instance using {merge_into_self}. For instances to
       # be mergeable, they must either all be abstract or all not be abstract,
       # and they must define the same superclass (or none at all).
       #
-      # @param others [Array<RbiGenerator::RbiObject>] An array of other {ClassNamespace} instances.
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
-        others = T.cast(others, T::Array[ClassNamespace]) rescue (return false)
+        others = T.cast(others, T::Array[Namespace]) rescue (return false)
         all = others + [self]
 
-        all.map(&:abstract).uniq.length == 1 &&
-          all.map(&:superclass).compact.uniq.length <= 1
+        all_classes = T.cast(all.select { |x| ClassNamespace === x }, T::Array[ClassNamespace])
+
+        all_classes.map(&:abstract).uniq.length == 1 &&
+          all_classes.map(&:superclass).compact.uniq.length <= 1
       end
 
       sig do 
@@ -99,6 +101,7 @@ module Parlour
         super
 
         others.each do |other|
+          next unless ClassNamespace === other
           other = T.cast(other, ClassNamespace)
 
           @superclass = other.superclass unless superclass

data/lib/parlour/rbi_generator/constant.rb

@@ -8,6 +8,7 @@ module Parlour
           generator: RbiGenerator,
           name: String,
           value: String,
+          eigen_constant: T::Boolean,
           block: T.nilable(T.proc.params(x: Constant).void)
         ).void
       end
@@ -15,9 +16,12 @@ module Parlour
       #
       # @param name [String] The name of the constant.
       # @param value [String] The value of the constant, as a Ruby code string.
-      def initialize(generator, name: '', value: '', &block)
+      # @param eigen_constant [Boolean] Whether this constant is defined on the
+      #   eigenclass of the current namespace.
+      def initialize(generator, name: '', value: '', eigen_constant: false, &block)
         super(generator, name)
         @value = value
+        @eigen_constant = eigen_constant
         yield_self(&block) if block
       end
 
@@ -25,6 +29,10 @@ module Parlour
       sig { returns(String) }
       attr_reader :value
 
+      # @return [Boolean] Whether this constant is defined on the eigenclass
+      #   of the current namespace.
+      attr_reader :eigen_constant
+
       sig { params(other: Object).returns(T::Boolean) }
       # Returns true if this instance is equal to another extend.
       #
@@ -32,7 +40,8 @@ module Parlour
       #   subclass of it), this will always return false.
       # @return [Boolean]
       def ==(other)
-        Constant === other && name == other.name && value == other.value
+        Constant === other && name == other.name && value == other.value \
+          && eigen_constant == other.eigen_constant
       end
 
       sig do

data/lib/parlour/rbi_generator/enum_class_namespace.rb

@@ -80,10 +80,32 @@ module Parlour
       # @param others [Array<RbiGenerator::RbiObject>] An array of other {EnumClassNamespace} instances.
       # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
-        others = T.cast(others, T::Array[EnumClassNamespace]) rescue (return false)
+        others = T.cast(others, T::Array[Namespace]) rescue (return false)
         all = others + [self]
+        all_enums = T.cast(all.select { |x| EnumClassNamespace === x }, T::Array[EnumClassNamespace])
 
-        T.must(super && all.map(&:enums).uniq.length <= 1)
+        T.must(super && all_enums.map { |e| e.enums.sort }.reject(&:empty?).uniq.length <= 1)
+      end
+
+      sig do
+        override.params(
+          others: T::Array[RbiGenerator::RbiObject]
+        ).void
+      end
+      # Given an array of {EnumClassNamespace} instances, merges them into this one.
+      # You MUST ensure that {mergeable?} is true for those instances.
+      #
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {EnumClassNamespace} instances.
+      # @return [void]
+      def merge_into_self(others)
+        super
+
+        others.each do |other|
+          next unless EnumClassNamespace === other
+          other = T.cast(other, EnumClassNamespace)
+
+          @enums = other.enums if enums.empty?
+        end
       end
     end
   end

data/lib/parlour/rbi_generator/module_namespace.rb

@@ -59,18 +59,20 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
-      # Given an array of {ModuleNamespace} instances, returns true if they may
+      # Given an array of {Namespace} instances, returns true if they may
       # be merged into this instance using {merge_into_self}. For instances to
       # be mergeable, they must either all be interfaces or all not be 
       # interfaces.
       #
-      # @param others [Array<RbiGenerator::RbiObject>] An array of other {ModuleNamespace} instances.
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
-        others = T.cast(others, T::Array[RbiGenerator::ModuleNamespace]) rescue (return false)
+        others = T.cast(others, T::Array[Namespace]) rescue (return false)
         all = others + [self]
 
-        all.map(&:interface).uniq.length == 1
+        all_modules = T.cast(all.select { |x| ModuleNamespace === x }, T::Array[ModuleNamespace])
+
+        all_modules.map(&:interface).uniq.length == 1
       end
 
       sig do 

data/lib/parlour/rbi_generator/namespace.rb

@@ -196,6 +196,35 @@ module Parlour
         new_enum_class
       end
 
+      sig do
+        params(
+          name: String,
+          final: T::Boolean,
+          props: T.nilable(T::Array[StructProp]),
+          abstract: T::Boolean,
+          block: T.nilable(T.proc.params(x: StructClassNamespace).void)
+        ).returns(StructClassNamespace)
+      end
+      # Creates a new struct class definition as a child of this namespace.
+      #
+      # @example Create a person struct.
+      #   namespace.create_class('Person', props: [
+      #     Parlour::RbiGenerator::StructProp.new('name', 'String')
+      #   ])
+      #
+      # @param name [String] The name of this class.
+      # @param final [Boolean] Whether this namespace is final.
+      # @param props [Array<StructProp>] The props of the struct.
+      # @param abstract [Boolean] A boolean indicating whether this class is abstract.
+      # @param block A block which the new instance yields itself to.
+      # @return [EnumClassNamespace]
+      def create_struct_class(name, final: false, props: nil, abstract: false, &block)
+        new_struct_class = StructClassNamespace.new(generator, name, final, props || [], abstract, &block)
+        move_next_comments(new_struct_class)
+        children << new_struct_class
+        new_struct_class
+      end
+
       sig do
         params(
           name: String,
@@ -247,13 +276,13 @@ module Parlour
       #
       # @param name [String] The name of this method. You should not specify +self.+ in
       #   this - use the +class_method+ parameter instead.
-      # @param parameters [Array<Parameter>] An array of {Parameter} instances representing this 
+      # @param parameters [Array<Parameter>] An array of {Parameter} instances representing this
       #   method's parameters.
       # @param return_type [String, nil] A Sorbet string of what this method returns, such as
       #   +"String"+ or +"T.untyped"+. Passing nil denotes a void return.
       # @param returns [String, nil] Same as return_type.
       # @param abstract [Boolean] Whether this method is abstract.
-      # @param implementation [Boolean] DEPRECATED: Whether this method is an 
+      # @param implementation [Boolean] DEPRECATED: Whether this method is an
       #   implementation of a parent abstract method.
       # @param override [Boolean] Whether this method is overriding a parent overridable
       #   method, or implementing a parent abstract method.
@@ -498,7 +527,7 @@ module Parlour
         returned_includables
       end
 
-      sig { params(name: String, value: String, block: T.nilable(T.proc.params(x: Constant).void)).returns(Constant) }
+      sig { params(name: String, value: String, eigen_constant: T::Boolean, block: T.nilable(T.proc.params(x: Constant).void)).returns(Constant) }
       # Adds a new constant definition to this namespace.
       #
       # @example Add an +Elem+ constant to the class.
@@ -506,13 +535,16 @@ module Parlour
       #
       # @param name [String] The name of the constant.
       # @param value [String] The value of the constant, as a Ruby code string.
+      # @param eigen_constant [Boolean] Whether this constant is defined on the
+      #   eigenclass of the current namespace.
       # @param block A block which the new instance yields itself to.
       # @return [RbiGenerator::Constant]
-      def create_constant(name, value:, &block)
+      def create_constant(name, value:, eigen_constant: false, &block)
         new_constant = RbiGenerator::Constant.new(
           generator,
           name: name,
           value: value,
+          eigen_constant: eigen_constant,
           &block
         )
         move_next_comments(new_constant)
@@ -544,26 +576,30 @@ module Parlour
       # can be merged into each other, as they lack definitions for themselves,
       # so there is nothing to conflict. (This isn't the case for subclasses
       # such as {ClassNamespace}.)
-      # 
+      #
       # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [true] Always true.
       def mergeable?(others)
         true
       end
 
-      sig do 
+      sig do
         override.overridable.params(
           others: T::Array[RbiGenerator::RbiObject]
         ).void
       end
       # Given an array of {Namespace} instances, merges them into this one.
-      # All children, constants, extends and includes are copied into this 
+      # All children, constants, extends and includes are copied into this
       # instance.
-      # 
+      #
+      # There may also be {RbiGenerator::Method} instances in the stream, which
+      # are ignored.
+      #
       # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [void]
       def merge_into_self(others)
         others.each do |other|
+          next if other.is_a?(RbiGenerator::Method)
           other = T.cast(other, Namespace)
 
           other.children.each { |c| children << c }
@@ -598,31 +634,61 @@ module Parlour
 
         result += [options.indented(indent_level, 'final!'), ''] if final
 
-        if includes.any? || extends.any? || constants.any?
-          result += includes
+        # Split away the eigen constants; these need to be put in a
+        # "class << self" block later
+        eigen_constants, non_eigen_constants = constants.partition(&:eigen_constant)
+        eigen_constants.sort_by!(&:name) if options.sort_namespaces
+
+        if includes.any? || extends.any? || non_eigen_constants.any?
+          result += (options.sort_namespaces ? includes.sort_by(&:name) : includes)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
-          result += extends
+          result += (options.sort_namespaces ? extends.sort_by(&:name) : extends)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
-          result += constants
+          result += (options.sort_namespaces ? non_eigen_constants.sort_by(&:name) : non_eigen_constants)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
           result << ""
         end
 
         # Process singleton class attributes
-        class_attributes, remaining_children = children.partition do |child|
+        sorted_children = (
+          if options.sort_namespaces
+            # sort_by can be unstable (and is in current MRI).
+            # Use the this work around to preserve order for ties
+            children.sort_by.with_index { |child, i| [child.name, i] }
+          else
+            children
+          end
+        )
+        class_attributes, remaining_children = sorted_children.partition do |child|
           child.is_a?(Attribute) && child.class_attribute
         end
-        if class_attributes.any?
-          result << options.indented(indent_level, 'class << self')
 
+        # Handle the "class << self block"
+        result << options.indented(indent_level, 'class << self') \
+          if class_attributes.any? || eigen_constants.any?
+
+        if eigen_constants.any?
+          first, *rest = eigen_constants
+          result += T.must(first).generate_rbi(indent_level + 1, options) + T.must(rest)
+            .map { |obj| obj.generate_rbi(indent_level + 1, options) }
+            .map { |lines| [""] + lines }
+            .flatten
+        end
+
+        result << '' if eigen_constants.any? && class_attributes.any?
+
+        if class_attributes.any?
           first, *rest = class_attributes
           result += T.must(first).generate_rbi(indent_level + 1, options) + T.must(rest)
             .map { |obj| obj.generate_rbi(indent_level + 1, options) }
             .map { |lines| [""] + lines }
             .flatten
+        end
+
+        if class_attributes.any? || eigen_constants.any?
           result << options.indented(indent_level, 'end')
           result << ''
         end

data/lib/parlour/rbi_generator/options.rb

@@ -6,7 +6,7 @@ module Parlour
     class Options
       extend T::Sig
 
-      sig { params(break_params: Integer, tab_size: Integer).void }
+      sig { params(break_params: Integer, tab_size: Integer, sort_namespaces: T::Boolean).void }
       # Creates a new set of formatting options.
       #
       # @example Create Options with +break_params+ of +4+ and +tab_size+ of +2+.
@@ -15,10 +15,13 @@ module Parlour
       # @param break_params [Integer] If there are at least this many parameters in a 
       #   Sorbet +sig+, then it is broken onto separate lines.
       # @param tab_size [Integer] The number of spaces to use per indent.
+      # @param sort_namespaces [Boolean] Whether to sort all items within a
+      #   namespace alphabetically.
       # @return [void]
-      def initialize(break_params:, tab_size:)
+      def initialize(break_params:, tab_size:, sort_namespaces:)
         @break_params = break_params
         @tab_size = tab_size
+        @sort_namespaces = sort_namespaces
       end
       
       sig { returns(Integer) }
@@ -46,6 +49,16 @@ module Parlour
       # @return [Integer]
       attr_reader :tab_size
 
+      sig { returns(T::Boolean) }
+      # Whether to sort all items within a namespace alphabetically.
+      # Items which are typically grouped together, such as "include" or
+      # "extend" calls, will remain grouped together when sorted.
+      # If true, items are sorted by their name when the RBI is generated.
+      # If false, items are generated in the order they are added to the
+      # namespace.
+      # @return [Boolean]
+      attr_reader :sort_namespaces
+
       sig { params(level: Integer, str: String).returns(String) }
       # Returns a string indented to the given indent level, according to the
       # set {tab_size}.