parlour 0.1.1 → 0.2.0

data/lib/parlour/rbi_generator/attribute.rb

@@ -0,0 +1,68 @@
+# typed: true
+module Parlour
+  class RbiGenerator
+    # Represents an attribute reader, writer or accessor.
+    class Attribute < Method
+      sig do
+        params(
+          generator: RbiGenerator,
+          name: String,
+          kind: Symbol,
+          type: String,
+          block: T.nilable(T.proc.params(x: Method).void)
+        ).void
+      end
+      # Creates a new attribute.
+      # @note You should use {Namespace#create_attribute} rather than this directly.
+      #
+      # @param generator [RbiGenerator] The current RbiGenerator.
+      # @param name [String] The name of this attribute.
+      # @param kind [Symbol] The kind of attribute this is; one of :writer, :reader or
+      #   :accessor.
+      # @param type [String] A Sorbet string of this attribute's type, such as
+      #   +"String"+ or +"T.untyped"+.
+      # @param block A block which the new instance yields itself to.
+      # @return [void]
+      def initialize(generator, name, kind, type, &block)
+        # According to this source: 
+        #   https://github.com/sorbet/sorbet/blob/2275752e51604acfb79b30a0a96debc996c089d9/test/testdata/dsl/attr_multi.rb
+        # attr_accessor and attr_reader should have: sig { returns(X) }
+        # attr_writer :foo should have: sig { params(foo: X).returns(X) }
+
+        @kind = kind
+        case kind
+        when :accessor, :reader
+          super(generator, name, [], type, &block)
+        when :writer
+          super(generator, name, [
+            Parameter.new(name, type: type)
+          ], type, &block)
+        else
+          raise 'unknown kind'
+        end
+      end
+
+      sig { returns(Symbol) }
+      # The kind of attribute this is; one of +:writer+, +:reader+, or +:accessor+.
+      # @return [Symbol]
+      attr_reader :kind
+
+      private
+
+      sig do
+        override.params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      # Generates the RBI lines for this method.
+      # 
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines, formatted as specified.
+      def generate_definition(indent_level, options)
+        [options.indented(indent_level, "attr_#{kind} :#{name}")]
+      end
+    end
+  end
+end

data/lib/parlour/rbi_generator/class_namespace.rb

@@ -1,20 +1,31 @@
 # typed: true
 module Parlour
   class RbiGenerator
+    # Represents a class definition.
     class ClassNamespace < Namespace
       extend T::Sig
 
       sig do
         params(
+          generator: RbiGenerator,
           name: String,
           superclass: T.nilable(String),
           abstract: T::Boolean,
           block: T.nilable(T.proc.params(x: ClassNamespace).void)
         ).void
       end
-      def initialize(name, superclass, abstract, &block)
-        super(&block)
-        @name = name
+      # Creates a new class definition.
+      # @note You should use {Namespace#create_class} rather than this directly.
+      #
+      # @param generator [RbiGenerator] The current RbiGenerator.
+      # @param name [String] The name of this class.
+      # @param superclass [String, nil] The superclass of this class, or nil if it doesn't
+      #   have one.
+      # @param abstract [Boolean] A boolean indicating whether this class is abstract.
+      # @param block A block which the new instance yields itself to.
+      # @return [void]
+      def initialize(generator, name, superclass, abstract, &block)
+        super(generator, name, &block)
         @superclass = superclass
         @abstract = abstract
       end
@@ -25,25 +36,31 @@ module Parlour
           options: Options
         ).returns(T::Array[String])
       end
+      # Generates the RBI lines for this class.
+      # 
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines, formatted as specified.
       def generate_rbi(indent_level, options)
         class_definition = superclass.nil? \
           ? "class #{name}"
           : "class #{name} < #{superclass}"
         
-        lines = []
+        lines = generate_comments(indent_level, options)
         lines << options.indented(indent_level, class_definition)
         lines += [options.indented(indent_level + 1, "abstract!"), ""] if abstract
-        lines += super(indent_level + 1, options)
+        lines += generate_body(indent_level + 1, options)
         lines << options.indented(indent_level, "end")
       end
 
-      sig { returns(String) }
-      attr_reader :name
-
       sig { returns(T.nilable(String)) }
+      # The superclass of this class, or nil if it doesn't have one.
+      # @return [String, nil]
       attr_reader :superclass
 
       sig { returns(T::Boolean) }
+      # A boolean indicating whether this class is abstract or not.
+      # @return [Boolean]
       attr_reader :abstract
 
       sig do
@@ -51,6 +68,13 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
+      # Given an array of {ClassNamespace} 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.
+      # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
         others = T.cast(others, T::Array[ClassNamespace]) rescue (return false)
         all = others + [self]
@@ -64,17 +88,29 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).void
       end
+      # Given an array of {ClassNamespace} 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 {ClassNamespace} instances.
+      # @return [void]
       def merge_into_self(others)
+        super
+
         others.each do |other|
           other = T.cast(other, ClassNamespace)
 
-          other.children.each { |c| children << c }
-          other.extends.each { |e| extends << e }
-          other.includes.each { |i| includes << i }
-
           @superclass = other.superclass unless superclass
         end
       end
+
+      sig { override.returns(String) }
+      # Returns a human-readable brief string description of this class.
+      # @return [String]
+      def describe
+        "Class #{name} - #{"superclass #{superclass}, " if superclass}" +
+          "#{"abstract, " if abstract}#{children.length} children, " +
+          "#{includes.length} includes, #{extends.length} extends"
+      end
     end
   end
-end
+end

data/lib/parlour/rbi_generator/method.rb

@@ -1,13 +1,13 @@
 # typed: true
 module Parlour
   class RbiGenerator
-    class Method
+    # Represents a method definition.
+    class Method < RbiObject
       extend T::Sig
 
-      include RbiObject
-
       sig do
         params(
+          generator: RbiGenerator,
           name: String,
           parameters: T::Array[Parameter],
           return_type: T.nilable(String),
@@ -15,11 +15,32 @@ module Parlour
           implementation: T::Boolean,
           override: T::Boolean,
           overridable: T::Boolean,
-          class_method: T::Boolean
+          class_method: T::Boolean,
+          block: T.nilable(T.proc.params(x: Method).void)
         ).void
       end
-      def initialize(name, parameters, return_type = nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false)
-        @name = name
+      # Creates a new method definition.
+      # @note You should use {Namespace#create_method} rather than this directly.
+      #
+      # @param generator [RbiGenerator] The current RbiGenerator.
+      # @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 
+      #   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 abstract [Boolean] Whether this method is abstract.
+      # @param implementation [Boolean] Whether this method is an implementation of a
+      #   parent abstract method.
+      # @param override [Boolean] Whether this method is overriding a parent overridable
+      #   method.
+      # @param overridable [Boolean] Whether this method is overridable by subclasses.
+      # @param class_method [Boolean] Whether this method is a class method; that is, it
+      #   it is defined using +self.+.
+      # @param block A block which the new instance yields itself to.
+      # @return [void]
+      def initialize(generator, name, parameters, return_type = nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false, &block)
+        super(generator, name)
         @parameters = parameters
         @return_type = return_type
         @abstract = abstract
@@ -27,9 +48,15 @@ module Parlour
         @override = override
         @overridable = overridable
         @class_method = class_method
+        yield_self(&block)
       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 {Method} (or a
+      #   subclass of it), this will always return false.
+      # @return [Boolean]
       def ==(other)
         Method === other &&
           name           == other.name && 
@@ -42,28 +69,41 @@ module Parlour
           class_method   == other.class_method
       end
 
-      sig { returns(String) }
-      attr_reader :name
-
       sig { returns(T::Array[Parameter]) }
+      # An array of {Parameter} instances representing this method's parameters.
+      # @return [Array<Parameter>]
       attr_reader :parameters
 
       sig { returns(T.nilable(String)) }
+      # A Sorbet string of what this method returns, such as "String" or
+      # "T.untyped". Passing nil denotes a void return.
+      # @return [String, nil]
       attr_reader :return_type
 
       sig { returns(T::Boolean) }
+      # Whether this method is abstract.
+      # @return [Boolean]
       attr_reader :abstract
 
       sig { returns(T::Boolean) }
+      # Whether this method is an implementation of a parent abstract method.
+      # @return [Boolean]
       attr_reader :implementation
 
       sig { returns(T::Boolean) }
+      # Whether this method is overriding a parent overridable method.
+      # @return [Boolean]
       attr_reader :override
 
       sig { returns(T::Boolean) }
+      # Whether this method is overridable by subclasses.
+      # @return [Boolean]
       attr_reader :overridable
 
       sig { returns(T::Boolean) }
+      # Whether this method is a class method; that is, it it is defined using
+      # +self.+.
+      # @return [Boolean]
       attr_reader :class_method
 
       sig do
@@ -72,6 +112,11 @@ module Parlour
           options: Options
         ).returns(T::Array[String])
       end
+      # Generates the RBI lines for this method.
+      #
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines, formatted as specified.
       def generate_rbi(indent_level, options)
         return_call = return_type ? "returns(#{return_type})" : 'void'
 
@@ -98,26 +143,10 @@ module Parlour
               }#{
                 qualifiers.empty? && parameters.empty? ? '' : '.'
               }#{return_call} }"
-            )]
-
-        def_params = parameters.map(&:to_def_param)
-        name_prefix = class_method ? 'self.' : ''
-        def_line = options.indented(
-          indent_level,
-          "def #{name_prefix}#{name}(#{def_params.join(', ')}); end"
-        )
-
-        sig_lines + [def_line]
-      end
+            )]        
 
-      sig { returns(String) }
-      def qualifiers
-        result = ''
-        result += 'abstract.' if abstract
-        result += 'implementation.' if implementation
-        result += 'override.' if override
-        result += 'overridable.' if overridable
-        result
+        generate_comments(indent_level, options) + sig_lines +
+          generate_definition(indent_level, options)
       end
 
       sig do
@@ -125,8 +154,14 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
+      # Given an array of {Method} instances, returns true if they may be merged
+      # into this instance using {merge_into_self}. For instances to be
+      # mergeable, their signatures and definitions must be identical.
+      #
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {Method} instances.
+      # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
-        false
+        others.all? { |other| self == other }
       end
 
       sig do 
@@ -134,9 +169,66 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).void
       end
+      # Given an array of {Method} instances, merges them into this one.
+      # This particular implementation in fact does nothing, because {Method}
+      # instances are only mergeable if they are identical, so nothing needs
+      # to be changed.
+      # You MUST ensure that {mergeable?} is true for those instances.
+      #
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {Method} instances.
+      # @return [void]
       def merge_into_self(others)
-        raise 'methods can never be merged like this'
+        # We don't need to change anything! We only merge identical methods
+      end
+
+      sig { override.returns(String) }
+      # Returns a human-readable brief string description of this method.
+      #
+      # @return [String]
+      def describe
+        # TODO: more info
+        "Method #{name} - #{parameters.length} parameters, " +
+          " returns #{return_type}"
+      end
+
+      private
+
+      sig do
+        overridable.params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      # Generates the RBI lines for this method.
+      # 
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines, formatted as specified.
+      def generate_definition(indent_level, options)
+        def_params = parameters.map(&:to_def_param)
+        name_prefix = class_method ? 'self.' : ''
+        def_line = options.indented(
+          indent_level,
+          "def #{name_prefix}#{name}#{
+            "(#{def_params.join(', ')})" unless parameters.empty?}; end"
+        )
+        [def_line]
+      end
+
+      sig { returns(String) }
+      # Returns the qualifiers which go in front of the +params+ part of this
+      # method's Sorbet +sig+. For example, if {abstract} is true, then this
+      # will return +abstract.+.
+      #
+      # @return [String]
+      def qualifiers
+        result = ''
+        result += 'abstract.' if abstract
+        result += 'implementation.' if implementation
+        result += 'override.' if override
+        result += 'overridable.' if overridable
+        result
       end
     end
   end
-end
+end

data/lib/parlour/rbi_generator/module_namespace.rb

@@ -1,18 +1,29 @@
 # typed: true
 module Parlour
   class RbiGenerator
+    # Represents a module definition.
     class ModuleNamespace < Namespace
       extend T::Sig
 
       sig do
         params(
+          generator: RbiGenerator,
           name: String,
           interface: T::Boolean,
           block: T.nilable(T.proc.params(x: ClassNamespace).void)
         ).void
       end
-      def initialize(name, interface, &block)
-        super(&block)
+      # Creates a new module definition.
+      # @note You should use {Namespace#create_module} rather than this directly.
+      # 
+      # @param generator [RbiGenerator] The current RbiGenerator.
+      # @param name [String] The name of this module.
+      # @param interface [Boolean] A boolean indicating whether this module is an
+      #   interface.
+      # @param block A block which the new instance yields itself to.
+      # @return [void]
+      def initialize(generator, name, interface, &block)
+        super(generator, name, &block)
         @name = name
         @interface = interface
       end
@@ -23,18 +34,22 @@ module Parlour
           options: Options
         ).returns(T::Array[String])
       end
+      # Generates the RBI lines for this module.
+      #
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines, formatted as specified.
       def generate_rbi(indent_level, options)        
-        lines = []
+        lines = generate_comments(indent_level, options)
         lines << options.indented(indent_level, "module #{name}")
         lines += [options.indented(indent_level + 1, "interface!"), ""] if interface
-        lines += super(indent_level + 1, options)
+        lines += generate_body(indent_level + 1, options)
         lines << options.indented(indent_level, "end")
       end
 
-      sig { returns(String) }
-      attr_reader :name
-
       sig { returns(T::Boolean) }
+      # A boolean indicating whether this module is an interface or not.
+      # @return [Boolean]
       attr_reader :interface
 
       sig do
@@ -42,6 +57,13 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
+      # Given an array of {ModuleNamespace} 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.
+      # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
         others = T.cast(others, T::Array[RbiGenerator::ModuleNamespace]) rescue (return false)
         all = others + [self]
@@ -54,15 +76,22 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).void
       end
+      # Given an array of {ModuleNamespace} 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 {ModuleNamespace} instances.
+      # @return [void]
       def merge_into_self(others)
-        others.each do |other|
-          other = T.cast(other, ModuleNamespace)
+        super
+      end
 
-          other.children.each { |c| children << c }
-          other.extends.each { |e| extends << e }
-          other.includes.each { |i| includes << i }
-        end
+      sig { override.returns(String) }
+      # Returns a human-readable brief string description of this module.
+      # @return [String]
+      def describe
+        "Module #{name} - #{"interface, " if interface}#{children.length} " +
+          "children, #{includes.length} includes, #{extends.length} extends"
       end
     end
   end
-end
+end