parlour 5.0.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb1e682fc74b2ccd30ac9055caf652889e898e2632347bf6cf0898f218bd5562
-  data.tar.gz: fcca5ca04676cbeed657add051e344fd9b5fa0a7efc757339847310300aa4d42
+  metadata.gz: cc5c6c8baabe95bbc999a4143264b1dad8b84260bdc156d2a35526244322db2f
+  data.tar.gz: 580430b0cfe37f80b60f9dd47f8673f4d1d973e6ef6abca44efa299355d19fed
 SHA512:
-  metadata.gz: cef41723b922734b49f8377dc3b5c60cf0071d2a9723326299872fea4789f8e6ea1cb280fcd21161d48bd5dbb074b416e60668138116e56caf1c8334cce8e535
-  data.tar.gz: b9ea0db060c8789e1324460cde4a69b1c20b829920e660024f53834e48cef536b5423736e6fce4859c2e2fea5339e3f26bdd7513947bafcc82bd239db57cc68a
+  metadata.gz: ae2fd0263a3d955ff7904a28e69bf16eb21b413bda3e71be42636e0829e730a33ee0eb477712fc45dffbce948de3a4c3d6ae6e19147e21b114cd58fe93679676
+  data.tar.gz: 549cd5f91736b8aa5c1f5e1ebaa69fd2d8e4e9f905f1d4aa9ed799677e2d2367a573548d6a9ea220f3c6c6dbf268cc2679c8d0e26516c52224574563974070b6

data/.github/workflows/ruby.yml

@@ -0,0 +1,46 @@
+name: Run tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        ruby: [2.4, 2.5, 2.6, 2.7, 3.0]
+    continue-on-error: false
+      
+    runs-on: ubuntu-latest    
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake
+    - name: Check RBI is up-to-date
+      run: ./ci/check_rbi.sh
+
+  # Deploy documentation to GitHub Pages, if this is a push to master and the tests passed
+  deploy-docs:
+    if: ${{ github.ref == 'refs/heads/master' }}
+    
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.7
+    - name: Install dependencies
+      run: bundle install
+    - name: Build documentation
+      run: bundle exec yard
+    - name: Deploy to GitHub Actions
+      uses: JamesIves/github-pages-deploy-action@3.7.1
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: gh-pages
+        folder: doc

data/.parlour

@@ -1,5 +1,7 @@
-excluded_paths:
-  - lib/parlour/kernel_hack.rb
+parser:
+  excluded_paths:
+    - lib/parlour/kernel_hack.rb
 
 excluded_modules:
   - Parlour::DetachedRbiGenerator
+  - Parlour::DetachedRbsGenerator

data/CHANGELOG.md

@@ -3,6 +3,39 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [7.0.0] - 2022-04-18
+### Added
+- `#describe` now uses a new, clearer format.
+- Added `#describe_tree`, which produces `#describe` output for a node and all
+  of its children.
+- Added `#find` and `#find_all` for retrieving a node's children based on
+  criteria.
+
+### Changed
+- Parlour now uses the new block-based `type_member` syntax internally.
+  **Potentially breaking** if you pin an older version of Sorbet which doesn't
+  support this syntax!
+- Improved error message when unable to retrieve the file table from Sorbet.
+- `#inspect` and `#to_s` now call `#describe`.
+
+## Fixed
+- Fixed some incorrect YARD documentation tags.
+
+## [6.0.1] - 2021-02-28
+### Changed
+- Disabled runtime type checking for `TypedObject#name`, resulting in a
+  significant decrease in the time taken to run the conflict resolver.
+
+## [6.0.0] - 2021-02-28
+### Changed
+- The RBI previously included with the Parlour gem has been removed,
+  as it was causing issues with Sorbet. **If you were relying on Parlour's
+  bundled RBI while type-checking your project, you will now need to use the
+  RBI from sorbet-typed or the Parlour repo.**
+- `Namespace#path` will now work much more reliably for classes and
+  modules which replace methods from `Module` and `Class`, such as
+  `#name`.
+
 ## [5.0.0] - 2020-12-26
 ### Added
 - Added RBS generation support! This includes:

data/exe/parlour

@@ -11,9 +11,8 @@ program :description, 'An RBI generator and plugin system'
 
 default_command :run
 command :run do |c|
-  # TODO: re-add support for flags and figure out how to merge them with .parlour
-  c.syntax = 'parlour run <plugins...> <output-file> [options]'
-  c.description = 'Generates an RBI file from your .parlour file'
+  c.syntax = 'parlour run'
+  c.description = 'Generates a signature file from your .parlour file'
 
   c.action do |args, options|
     working_dir = Dir.pwd

data/lib/parlour/conflict_resolver.rb

@@ -7,6 +7,10 @@ module Parlour
   class ConflictResolver
     extend T::Sig
 
+    def initialize
+      @debugging_tree = Debugging::Tree.new(colour: true)
+    end
+
     sig do
       params(
         namespace: RbiGenerator::Namespace,
@@ -41,7 +45,7 @@ module Parlour
     #   will be kept, or nil to keep none of them.
     # @return [void]
     def resolve_conflicts(namespace, &resolver)
-      Debugging.debug_puts(self, Debugging::Tree.begin("Resolving conflicts for #{namespace.name}..."))
+      Debugging.debug_puts(self, @debugging_tree.begin("Resolving conflicts for #{namespace.name}..."))
 
       # Check for multiple definitions with the same name
       # (Special case here: writer attributes get an "=" appended to their name)
@@ -54,10 +58,10 @@ module Parlour
       end
 
       grouped_by_name_children.each do |name, children|
-        Debugging.debug_puts(self, Debugging::Tree.begin("Checking children named #{name}..."))
+        Debugging.debug_puts(self, @debugging_tree.begin("Checking children named #{name}..."))
 
         if children.length > 1
-          Debugging.debug_puts(self, Debugging::Tree.here("Possible conflict between #{children.length} objects"))
+          Debugging.debug_puts(self, @debugging_tree.here("Possible conflict between #{children.length} objects"))
 
           # Special case: do we have two methods, one of which is a class method
           # and the other isn't? If so, do nothing - this is fine
@@ -65,7 +69,7 @@ module Parlour
             children.all? { |c| c.is_a?(RbiGenerator::Method) } &&
             children.count { |c| T.cast(c, RbiGenerator::Method).class_method } == 1
 
-            Debugging.debug_puts(self, Debugging::Tree.end("One is an instance method and one is a class method; no resolution required"))
+            Debugging.debug_puts(self, @debugging_tree.end("One is an instance method and one is a class method; no resolution required"))
             next
           end
 
@@ -80,7 +84,7 @@ module Parlour
             end
             deduplicate_mixins_of_name(namespace, name)
 
-            Debugging.debug_puts(self, Debugging::Tree.end("Includes/extends do not conflict with namespaces; no resolution required"))
+            Debugging.debug_puts(self, @debugging_tree.end("Includes/extends do not conflict with namespaces; no resolution required"))
             next
           end
 
@@ -90,13 +94,13 @@ module Parlour
             children.all? { |c| c.is_a?(RbiGenerator::Attribute) } &&
             children.count { |c| T.cast(c, RbiGenerator::Attribute).class_attribute } == 1
 
-            Debugging.debug_puts(self, Debugging::Tree.end("One is an instance attribute and one is a class attribute; no resolution required"))
+            Debugging.debug_puts(self, @debugging_tree.end("One is an instance attribute and one is a class attribute; no resolution required"))
             next
           end
 
           # Optimization for Special case: are they all clearly equal? If so, remove all but one
           if all_eql?(children)
-            Debugging.debug_puts(self, Debugging::Tree.end("All children are identical"))
+            Debugging.debug_puts(self, @debugging_tree.end("All children are identical"))
 
             # All of the children are the same, so this deletes all of them
             namespace.children.delete(T.must(children.first))
@@ -116,7 +120,7 @@ module Parlour
           # and get the strategy to use
           strategy = merge_strategy(children)
           unless strategy
-            Debugging.debug_puts(self, Debugging::Tree.end("Children are unmergeable types; requesting manual resolution"))
+            Debugging.debug_puts(self, @debugging_tree.end("Children are unmergeable types; requesting manual resolution"))
             # The types aren't the same, so ask the resolver what to do, and
             # insert that (if not nil)
             choice = resolver.call("Different kinds of definition for the same name", children)
@@ -135,7 +139,7 @@ module Parlour
             # a single method
             if non_namespaces.length != 0
               unless non_namespaces.length == 1 && RbiGenerator::Method === non_namespaces.first
-                Debugging.debug_puts(self, Debugging::Tree.end("Non-namespace item in a differing namespace conflict is not a single method; requesting manual resolution"))
+                Debugging.debug_puts(self, @debugging_tree.end("Non-namespace item in a differing namespace conflict is not a single method; requesting manual resolution"))
                 # The types aren't the same, so ask the resolver what to do, and
                 # insert that (if not nil)
                 choice = resolver.call("Non-namespace item in a differing namespace conflict is not a single method", non_namespaces)
@@ -167,29 +171,29 @@ module Parlour
           # Can the children merge themselves automatically? If so, let them
           first, rest = T.must(first), T.must(rest)
           if T.must(first).mergeable?(T.must(rest))
-            Debugging.debug_puts(self, Debugging::Tree.end("Children are all mergeable; resolving automatically"))
+            Debugging.debug_puts(self, @debugging_tree.end("Children are all mergeable; resolving automatically"))
             first.merge_into_self(rest)
             namespace.children << first
             next
           end
 
           # I give up! Let it be resolved manually somehow
-          Debugging.debug_puts(self, Debugging::Tree.end("Unable to resolve automatically; requesting manual resolution"))
+          Debugging.debug_puts(self, @debugging_tree.end("Unable to resolve automatically; requesting manual resolution"))
           choice = resolver.call("Can't automatically resolve", children)
           namespace.children << choice if choice
         else
-          Debugging.debug_puts(self, Debugging::Tree.end("No conflicts"))
+          Debugging.debug_puts(self, @debugging_tree.end("No conflicts"))
         end
       end
 
-      Debugging.debug_puts(self, Debugging::Tree.here("Resolving children..."))
+      Debugging.debug_puts(self, @debugging_tree.here("Resolving children..."))
 
       # Recurse to child namespaces
       namespace.children.each do |child|
         resolve_conflicts(child, &resolver) if RbiGenerator::Namespace === child
       end
 
-      Debugging.debug_puts(self, Debugging::Tree.end("All children done"))
+      Debugging.debug_puts(self, @debugging_tree.end("All children done"))
     end
 
     private

data/lib/parlour/debugging.rb

@@ -17,7 +17,7 @@ module Parlour
       @debug_mode = value
     end
 
-    # Whether debug messages sent by {#debug_puts} should be printed.
+    # Whether debug messages sent by {.debug_puts} should be printed.
     # Defaults to true if the PARLOUR_DEBUG environment variable is set.
     # @return [Boolean] True if debug messages will be printed, false otherwise.
     sig { returns(T::Boolean) }
@@ -25,11 +25,11 @@ module Parlour
       @debug_mode
     end
 
-    # Prints a message with a debugging prefix to STDOUT if {#debug_mode?} is
+    # Prints a message with a debugging prefix to STDOUT if {.debug_mode?} is
     # true.
-    # @params [Object] object The object which is printing this debug message. 
+    # @param [Object] object The object which is printing this debug message.
     #   Callers should pass +self+.
-    # @params [String] message The message to print. It should not contain
+    # @param [String] message The message to print. It should not contain
     #   newlines.
     # @return [void]
     sig { params(object: T.untyped, message: String).void }
@@ -45,7 +45,7 @@ module Parlour
     # "conflict resolver". If the object type is unknown, this returns its class
     # name.
     # @param [Object] object The object to convert.
-    # @return [String] A string describing the object for {#debug_puts}. 
+    # @return [String] A string describing the object for {.debug_puts}.
     sig { params(object: T.untyped).returns(String) }
     def self.name_for_debug_caller(object)
       case object
@@ -63,24 +63,32 @@ module Parlour
 
     # A module for generating a globally-consistent, nicely-formatted tree of
     # output using Unicode block characters.
-    module Tree
+    class Tree
       extend T::Sig
 
       # The number of spaces to indent each layer of the tree by. Should be at
       # least 1.
       INDENT_SPACES = 2
 
-      # The current indent level of the tree.
-      @indent_level = 0
+      # Whether to colour output or not.
+      sig { returns(T::Boolean) }
+      attr_reader :colour
+
+      sig { params(colour: T::Boolean).void }
+      def initialize(colour: false)
+        @colour = colour
+        @indent_level = 0
+      end
 
       # Returns a new heading, and then decents the tree one level into it. 
       # (That is, future output will go under the new heading.)
       # @param [String] message The heading.
       # @return [String] The line of this tree which should be printed.
       sig { params(message: String).returns(String) }
-      def self.begin(message)
-        result = line_prefix + '├' + text_prefix + Rainbow(message).green.bright.bold
-        @indent_level += 1
+      def begin(message)
+        result = line_prefix + '├' + text_prefix +
+          (colour ? Rainbow(message).green.bright.bold : message)
+        indent!(1)
         result
       end
 
@@ -88,7 +96,7 @@ module Parlour
       # @param [String] message The element.
       # @return [String] The line of this tree which should be printed.
       sig { params(message: String).returns(String) }
-      def self.here(message)
+      def here(message)
         line_prefix + '├' + text_prefix + message
       end
 
@@ -97,16 +105,16 @@ module Parlour
       # @param [String] message The element.
       # @return [String] The line of this tree which should be printed.
       sig { params(message: String).returns(String) }
-      def self.end(message)
+      def end(message)
         result = line_prefix + '└' + text_prefix + message
-        @indent_level = [0, @indent_level - 1].max
+        indent!(-1)
         result
       end
 
       # The prefix which should be printed before anything else on this line of
       # the tree, based on the current indent level.
       # @return [String]
-      def self.line_prefix
+      def line_prefix
         @indent_level.times.map { '│' + ' ' * INDENT_SPACES }.join
       end
 
@@ -114,9 +122,14 @@ module Parlour
       # the current element and its text, based on the specified number of
       # spaces to use for indents.
       # @return [String]
-      def self.text_prefix
+      def text_prefix
         '─' * (INDENT_SPACES - 1) + " "
       end
+
+      # Modifies the current indent level by the given offset.
+      def indent!(offset)
+        @indent_level = [0, @indent_level + offset].max
+      end
     end
   end
 end

data/lib/parlour/mixin/searchable.rb

@@ -0,0 +1,54 @@
+# typed: true
+
+module Parlour
+  module Mixin
+    # Extends a particular type system's Namespace class to provide searchable
+    # children.
+    module Searchable
+      extend T::Sig
+      extend T::Generic
+
+      Child = type_member
+
+      abstract!
+
+      sig { abstract.returns(T::Array[Child]) }
+      def children; end
+
+      sig { params(name: T.nilable(String), type: T.nilable(Class)).returns(Child) }
+      # Finds the first child matching the given predicates.
+      #
+      # @param [String, nil] name The name of the child to filter on, or nil.
+      # @param [Class, nil] type The type of the child to filter on, or nil. The
+      #   type is compared using #is_a?.
+      def find(name: nil, type: nil)
+        T.unsafe(children).find { |c| searchable_child_matches(c, name, type) }
+      end
+
+      sig { params(name: T.nilable(String), type: T.nilable(Class)).returns(T::Array[Child]) }
+      # Finds the first child matching the given predicates.
+      #
+      # @param [String, nil] name The name of the child to filter on, or nil.
+      # @param [Class, nil] type The type of the child to filter on, or nil. The
+      #   type is compared using #is_a?.
+      def find_all(name: nil, type: nil)
+        T.unsafe(children).select { |c| searchable_child_matches(c, name, type) }
+      end
+
+      private
+
+      sig do
+        params(
+          child: Child,
+          name: T.nilable(String),
+          type: T.nilable(Class)
+        )
+        .returns(T::Boolean)
+      end
+      def searchable_child_matches(child, name, type)
+        (name.nil? ? true : child.name == name) \
+        && (type.nil? ? true : child.is_a?(type))
+      end
+    end
+  end
+end

data/lib/parlour/rbi_generator/arbitrary.rb

@@ -80,12 +80,9 @@ module Parlour
         raise 'arbitrary code is never mergeable'
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Arbitrary code (#{code})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:code]
       end
 
       sig { override.void }

data/lib/parlour/rbi_generator/attribute.rb

@@ -78,6 +78,15 @@ module Parlour
         @type = TypeParser.parse_single_type(@type) if String === @type
       end
 
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [
+          :kind,
+          {type: type}, # avoid quotes
+          :class_attribute
+        ]
+      end
+
       private
 
       sig do

data/lib/parlour/rbi_generator/class_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class ClassNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -110,13 +112,10 @@ module Parlour
         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"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        (superclass ? [:superclass] : []) \
+          + [:children, :abstract, :final, :sealed]
       end
 
       sig { override.void }

data/lib/parlour/rbi_generator/constant.rb

@@ -95,12 +95,9 @@ module Parlour
         # We don't need to change anything! We only merge identical constants
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Constant (#{name} = #{value})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:value, :eigen_constant]
       end
 
       sig { override.void }

data/lib/parlour/rbi_generator/enum_class_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class EnumClassNamespace < ClassNamespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -114,6 +116,11 @@ module Parlour
       def generalize_from_rbi!
         super
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        super + [{enums: enums.inspect}]
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/extend.rb

@@ -75,16 +75,13 @@ module Parlour
         # We don't need to change anything! We only merge identical extends
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Extend (#{name})"
-      end
-
       sig { override.void }
       def generalize_from_rbi!; end # Nothing to do
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        []
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/include.rb

@@ -75,16 +75,13 @@ module Parlour
         # We don't need to change anything! We only merge identical includes
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Include (#{name})"
-      end
-
       sig { override.void }
       def generalize_from_rbi!; end # Nothing to do
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        []
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/method.rb

@@ -206,16 +206,6 @@ module Parlour
         # 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
-
       sig { override.void }
       def generalize_from_rbi!
         @return_type = TypeParser.parse_single_type(@return_type) if String === @return_type
@@ -223,6 +213,21 @@ module Parlour
         parameters.each(&:generalize_from_rbi!)
       end
 
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        (type_parameters.any? ? [{ type_parameters: type_parameters.join(", ")}] : []) \
+          + [
+            {parameters: "(#{parameters.map(&:describe_in_method).join(", ")})"},
+            {return_type: return_type || '(void)'}, # avoid quotes
+            :class_method,
+            :abstract,
+            :implementation,
+            :override,
+            :overridable,
+            :final,
+          ]
+      end
+
       private
 
       sig do

data/lib/parlour/rbi_generator/module_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class ModuleNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -100,19 +102,15 @@ module Parlour
         super
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this module.
-      # @return [String]
-      def describe
-        "Module #{name} - #{"interface, " if interface}" +
-          "#{"abstract, " if abstract}#{children.length} " +
-          "children, #{includes.length} includes, #{extends.length} extends"
-      end
-
       sig { override.void }
       def generalize_from_rbi!
         super
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:children, :abstract, :interface, :final, :sealed]
+      end
     end
   end
 end