parlour 3.0.0 → 5.0.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e2b9021c22592632f30a0a51c17cfbf3838c18061638297e9437c1dd34b5c9f
-  data.tar.gz: 337e2ea6d8212e6c2d16d2f8f5577b16bfd1c8ffa41197fad70f9dc7c51620b5
+  metadata.gz: 9c9fa581e9b41195e54a4716df7926d1beb225c47871ff39d2f08fb0fa462aeb
+  data.tar.gz: 1aa333b0896df783baefa79d87fdbda732dea8676b85e89b7d76de607716658c
 SHA512:
-  metadata.gz: 22e0196918f8214827f9904e45fff8689f4609ec71683ad4aca36c8eb75593e19f5d0ec4e5a5e034afdca1d3bdf7f0d9482bfb24b0e3e667553c13b5cb5b65a6
-  data.tar.gz: 2b322d3dcdce74985b2104a8d8beb8ac0a7b6b4de1bcc8af7288d5334d715765285cba032017c7ab6e5dccde045b284dd8056e57515e13f32f319de26fdc0666
+  metadata.gz: 30486957baea0d7b30f827483ca69fbf589bd55039bedbcee6ea4f6258c0601612d191818a547569b32fe2e805dd29e34f27a46005eb3d5586dd7cb3462f7fb2
+  data.tar.gz: ed021b13ea01c171852be2d4892ba1042bc7dbf747e3413881e7d9c674553dea82337172c986dfec8ec78bfbed2be5519b6a091e2f3cd19f142797f54e35689e

data/.gitignore

@@ -8,7 +8,7 @@
 /tmp/
 Gemfile.lock
 /.vscode
-/sorbte/rbi/hidden-definitions/errors.txt
+/sorbet/rbi/hidden-definitions/errors.txt
 
 # rspec failure tracking
 .rspec_status

data/.parlour

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

data/CHANGELOG.md

@@ -3,6 +3,63 @@ 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/).
 
+## [5.0.0.beta.3] - 2020-09-15
+### Changed
+- Changed the RBS keyword warning to come from "RBS generation" rather than
+  "Type generalization"
+- Added many more of RBS' keywords which are detected and prefixed with an
+  underscore to avoid syntax errors
+
+## [5.0.0.beta.2] - 2020-09-14
+### Added
+- Added `Types::Type#describe` for simple text descriptions of types
+- Added `Types::Self` for RBI's `T.self_type` or RBS' `self`
+
+### Fixed
+- Fixed `RbiGenerator::Namespace#create_method`'s `returns:` kwarg only
+  accepting String types
+- Fixed lack of spacing between argument lists and blocks in RBS
+- Fixed RBS attributes not having comments
+
+## [5.0.0.beta.1] - 2020-09-13
+### Added
+- Added RBS generation support! This includes:
+  - The new `RbsGenerator` class
+  - `RbsObject` and a set of subclasses representing different RBS components
+- Added the `Types` module, which is used to describe types agnostic of the
+  underlying type system
+  - Added `RbiGenerator::Namespace#generalize_from_rbi!` to convert RBI string
+    types into `Types` types
+  - **Specifying types as strings is still currently supported, but may be
+    phased out in future, and should be avoided in new projects**.
+- Added conversion from RBI to RBS type trees
+- Added a couple of classes to deduplicate functionality between type systems:
+  - `TypedObject`, which `RbiObject` and `RbsObject` both inherit from
+  - `Generator`, which `RbiGenerator` and `RbsGenerator` both inherit from
+- Added RBI type aliases
+
+### Changed
+- `Parlour::RbiGenerator::Options` is now `Parlour::Options`. An alias exists
+  for now, but **`Parlour::RbiGenerator::Options` is deprecated** and could be
+  removed in future versions.
+- Updated README and gem metadata to refer to Parlour as a type information
+  generator, rather than just an RBI generator
+
+## [4.0.1] - 2020-08-05
+### Fixed
+- Fixed duplicate includes and extends.
+- Fixed the block return type for `#resolve_conflicts` not being nilable.
+
+## [4.0.0] - 2020-05-23
+### Added
+- Parlour now defaults to loading the current project when running its command
+  line tool, allowing it to be used as a "`sig` extractor" when run without
+  plugins! **Breaking if you invoke Parlour from its command line tool** - to
+  revert to the old behaviour of having nothing loaded into the root namespace
+  initially, add `parser: false` to your `.parlour` file.
+- Generating constants in an eigenclass context (`class << self`) is now
+  supported.
+
 ## [3.0.0] - 2020-05-15
 ### Added
 - `T::Struct` classes can now be generated and parsed.

data/README.md

@@ -3,39 +3,77 @@
 [![Build Status](https://travis-ci.org/AaronC81/parlour.svg?branch=master)](https://travis-ci.org/AaronC81/parlour)
 ![Gem](https://img.shields.io/gem/v/parlour.svg)
 
-Parlour is an RBI generator, merger and parser for Sorbet. It consists of three
-key parts:
+Parlour is a Ruby type information generator, merger and parser, supporting both
+**Sorbet RBI files and Ruby 3/Steep RBS files**. It consists of three key parts:
 
-  - The generator, which outputs beautifully formatted RBI files, created using
-    an intuitive DSL.
+  - The generator, which outputs beautifully formatted RBI/RBS files, created 
+    using an intuitive DSL.
 
   - The plugin/build system, which allows multiple Parlour plugins to generate
     RBIs for the same codebase. These are combined automatically as much as
     possible, but any other conflicts can be resolved manually through prompts.
 
-  - The parser, which can read an RBI and convert it back into a tree of 
-    generator objects.
+  - The parser (currently RBI-only), which can read an RBI and convert it back
+    into a tree of generator objects.
 
 ## Why should I use this?
 
-  - Parlour enables **much easier creation of RBI generators**, as formatting
-    is all handled for you, and you don't need to write your own CLI.
+  - Parlour enables **much easier creation of RBI/RBS generators**, as
+    formatting is all handled for you, and you don't need to write your own CLI.
 
   - You can **use many plugins together seamlessly**, running them all with a
     single command and consolidating all of their definitions into a single
-    RBI output file.
+    output file.
 
   - You can **effortlessly build tools which need to access types within an RBI**;
-    no need to write your own parser! 
+    no need to write your own parser!
+
+  - You can **generate RBI/RBS to ship with your gem** for consuming projects to
+    use ([see "RBIs within gems" in Sorbet's
+    docs](https://sorbet.org/docs/rbi#rbis-within-gems)).
 
 Please [**read the wiki**](https://github.com/AaronC81/parlour/wiki) to get
 started!
 
-## Creating RBIs
+## Feature Support
+
+| Feature | RBI | RBS |
+|---------|-----|-----|
+| **GENERATION** |  |  |
+| Classes | ✅ | ⚠️ (missing `extension`) |
+| Modules | ✅ | ⚠️ (missing `extension`) |
+| Interfaces | ✅ | ✅ |
+| Attributes | ✅ | ✅ |
+| Methods | ✅ | ✅ |
+| Overloaded methods | ❌* | ✅ |
+| Structs | ✅ | ✅† |
+| Enums | ✅ | ✅† |
+| Generation with plugins | ✅ | ❌ |
+| **MANIPULATION** |  |  |
+| Parsing | ✅ | ❌ |
+| Merging | ✅ | ❌ |
+
+- ✅ - Well supported
+- ⚠️ - Some missing features
+- ❌ - Not currently supported
+
+- \* Only supported in stdlib types anyway
+- † Not natively supported; available as a one-way conversion from RBI
+
+## Creating Type Information
 
-### Using just the generator
+Each file format has its own type information generator class, so there are two
+different generators you can use: `RbiGenerator` and `RbsGenerator`. Both
+generators are similar to use, however they provide different object types and
+parameters to match the functionality of their underlying type systems.
 
-Here's a quick example of how you can generate an RBI:
+You can also convert your type information between formats; see
+[converting between formats](#converting-between-formats).
+
+### Using Just the Generator
+
+Here's a quick example of how you can generate some type information. Here
+we'll generate an RBI using the `RbiGenerator` classes:
 
 ```ruby
 require 'parlour'
@@ -69,11 +107,50 @@ module A
 end
 ```
 
-### Writing a plugin
+Using the RBS generator looks similar, but has an intermediary 
+`MethodSignature` class to support RBS' method overloading:
+
+```ruby
+require 'parlour'
+
+generator = Parlour::RbsGenerator.new
+generator.root.create_module('A') do |a|
+  a.create_class('Foo') do |foo|
+    foo.create_method('add_two_integers', [
+      Parlour::RbsGenerator::MethodSignature.new(
+        [
+          Parlour::RbsGenerator::Parameter.new('a', type: 'Integer'),
+          Parlour::RbsGenerator::Parameter.new('b', type: 'Integer')
+        ],
+        'Integer'
+      )
+    ])
+  end
+
+  a.create_class('Bar', superclass: 'Foo')
+end
+
+generator.rbs # => Our RBS as a string
+```
+
+This generates an equivalent RBS file:
+
+```ruby
+module A
+  class Foo
+    def add_two_integers: (Integer a, Integer b) -> Integer
+  end
+
+  class Bar < Foo
+  end
+end
+```
+
+### Writing a Plugin
 Plugins are better than using the generator alone, as your plugin can be
-combined with others to produce larger RBIs without conflicts.
+combined with others to produce larger files without conflicts.
 
-We could write the above example as a plugin like this:
+We could write the above example as an RBI plugin like this:
 
 ```ruby
 require 'parlour'
@@ -104,7 +181,8 @@ called `plugin.rb`, then using this `.parlour` file and then running `parlour`
 would save the RBI into `output.rbi`:
 
 ```yaml
-output_file: output.rbi
+output_file:
+  rbi: output.rbi
 
 relative_requires:
   - plugin.rb
@@ -128,7 +206,8 @@ You can also use plugins from gems. If that plugin was published as a gem called
 `parlour-gem`:
 
 ```yaml
-output_file: output.rbi
+output_file:
+  rbi: output.rbi
 
 requires:
   - parlour-gem
@@ -140,7 +219,8 @@ plugins:
 The real power of this is the ability to use many plugins at once:
 
 ```yaml
-output_file: output.rbi
+output_file:
+  rbi: output.rbi
 
 requires:
   - gem1
@@ -153,6 +233,92 @@ plugins:
   Gem3::Plugin: {}
 ```
 
+Currently, only plugins which generate RBI files are supported. However, you can
+use [Parlour's type conversion](#converting-between-formats) to convert the RBI
+types into RBS types:
+
+```yaml
+output_file:
+  rbi: output.rbi
+  rbs: output.rbs
+```
+
+## Using Types
+
+The most important part of your type information is the types themselves, which
+you'll be specifying for method parameters, method returns, and attributes. 
+These include simple types like `String`, up to more complex types like
+"an array of elements which are one of `Integer`, `String`, or nil".
+
+There are two ways to represent these types in Parlour:
+
+1. As **generalized types**; that is, instances of classes in the
+   `Parlour::Types` namespace. This is the **recommended way**, as it is
+   format-agnostic and can be compiled to RBI or RBS. For more information
+   about these types and how to use them, see
+   [this wiki page](https://github.com/AaronC81/parlour/wiki/The-Types-namespace).
+
+2. As **strings of code** written in the format that your type system expects.
+   The given strings are directly inserted into the final type file. These types
+   are **not portable across formats**, and as such are
+   **not recommended and may be phased out** in the future.
+
+Currently most type values within Parlour are typed as `Types::TypeLike`,
+which accepts a `String` or a `Types::Type` subclass.
+
+```ruby
+include Parlour
+
+# Two ways to express an attribute called 'example', which is:
+#   an array of nilable strings or integers
+
+# 1. With generalised types - type is agnostic to the underlying type system
+root.create_attr_accessor('example', type:
+  Types::Array.new(
+    Types::Nilable.new(
+      Types::Union.new(['String', 'Integer'])
+    )
+  )
+)
+
+# 2. With string types - format depends on type system
+#    If using RBI...
+root.create_attr_accessor('example', type:
+  'T::Array[T.nilable(T.any(String, Integer))]'
+)
+#    If using RBS...
+root.create_attr_accessor('example', type:
+  'Array[?(String | Integer)]'
+)
+```
+
+### Generalizing String Types
+
+If you have loaded an RBI project or created a structure of nodes on an
+`RbiGenerator`, you can use `#generalize_from_rbi!` on your root namespace
+to attempt to permanently convert the RBI string types into generalized types:
+
+```ruby
+# Build up an RBI tree with string types
+root.create_attr_accessor('example', type:
+  'T::Array[T.nilable(T.any(String, Integer))]'
+)
+
+# Generalize it
+root.generalize_from_rbi!
+
+# Take a look at our generalized type!
+pp root.children.first.type
+# => #<Parlour::Types::Array:0x0000557cdcebfdf8
+#     @element=
+#      #<Parlour::Types::Nilable:0x0000557cdcef8c70
+#       @type=
+#        #<Parlour::Types::Union:0x0000557cdcea0a70
+#         @types=
+#          [#<Parlour::Types::Raw:0x0000557cdcea1920 @str="String">,
+#           #<Parlour::Types::Raw:0x0000557cdcea0ae8 @str="Integer">]>>>
+```
+
 ## Parsing RBIs
 
 You can either parse individual RBI files, or point Parlour to the root of a
@@ -174,6 +340,54 @@ Parlour::TypeLoader.load_project('root/of/the/project')
 The structure of the returned object trees is identical to those you would
 create when generating an RBI, built of instances of `RbiObject` subclasses.
 
+## Generating RBI for a Gem
+
+Include `parlour` as a development_dependency in your `.gemspec`:
+
+```ruby
+spec.add_development_dependency 'parlour'
+```
+
+Run Parlour from the command line:
+
+```ruby
+bundle exec parlour
+```
+
+Parlour is configured to use sane defaults assuming a standard gem structure
+to generate an RBI that Sorbet will automatically find when your gem is included
+as a dependency. If you require more advanced configuration you can add a
+`.parlour` YAML file in the root of your project (see this project's `.parlour`
+file as an example).
+
+To disable the parsing step entire and just run plugins you can set `parser: false`
+in your `.parlour` file.
+
+## Converting Between Formats
+
+_For more information, see the [wiki page](https://github.com/AaronC81/parlour/wiki/Converting-between-RBI-and-RBS)._
+
+Currently, only RBI to RBS conversion is supported, and if you've used string
+types (or are using a freshly-loaded project) you
+**must [generalize them](#generalizing-string-types) first**.
+
+Then, all you need to do is create an `RbsGenerator` (which the converter will
+add your converted types to) and a `Conversion::RbiToRbs` instance (which 
+performs the conversion). Then you can convert each object at your
+`RbiGenerator`'s root namespace:
+
+```ruby
+rbi_gen = Parlour::RbiGenerator.new
+# Then, after populating the RbiGenerator with types...
+
+# Create an RbsGenerator and a converter
+rbs_gen = Parlour::RbsGenerator.new
+converter = Parlour::Conversion::RbiToRbs.new(rbs_gen)
+
+# Convert each item at the root of the RbiGenerator and it to the root of the RbsGenerator
+converter.convert_all(rbi_gen.root, rbs_gen.root)
+```
+
 ## Parlour Plugins
 
 _Have you written an awesome Parlour plugin? Please submit a PR to add it to this list!_

data/exe/parlour

@@ -16,15 +16,67 @@ command :run do |c|
   c.description = 'Generates an RBI file from your .parlour file'
 
   c.action do |args, options|
-    configuration = keys_to_symbols(YAML.load_file(File.join(Dir.pwd, '.parlour')))
+    working_dir = Dir.pwd
+    config_filename = File.join(working_dir, '.parlour')
 
-    raise 'you must specify output_file in your .parlour file' unless configuration[:output_file]
+    if File.exists?(config_filename)
+      configuration = keys_to_symbols(YAML.load_file(config_filename))
+    else
+      configuration = {}
+    end
+
+    # Output file
+    if configuration[:output_file].is_a?(String)
+      assumed_format = \
+        if configuration[:output_file].end_with?('.rbi')
+          :rbi
+        elsif configuration[:output_file].end_with?('.rbs')
+          :rbs
+        else
+          raise 'invalid output file; please specify an RBI or RBS file'
+        end
+
+      unless $VERBOSE.nil?
+        print Rainbow("Parlour warning: ").yellow.dark.bold
+        print Rainbow("CLI: ").magenta.bright.bold
+        puts "Specifying output_file in .parlour as a string is deprecated."
+        puts "For now, generating an #{assumed_format.to_s.upcase} file based on the file extension."
+        puts "Please update your .parlour to use the new form:"
+        puts "  output_file:"
+        puts "    #{assumed_format}: #{configuration[:output_file]}"
+      end
+      configuration[:output_file] = {
+        assumed_format => configuration[:output_file]
+      }
+    end
+    configuration[:output_file] ||= {
+      rbi: "rbi/#{File.basename(working_dir)}.rbi"
+    }    
 
     # Style defaults
     configuration[:style] ||= {}
     configuration[:style][:tab_size] ||= 2
     configuration[:style][:break_params] ||= 4
 
+    # Parser defaults, set explicitly to false to not run parser
+    if configuration[:parser] != false
+      configuration[:parser] ||= {}
+
+      # Input/Output defaults
+      configuration[:parser][:root] ||= '.'
+
+      # Included/Excluded path defaults
+      configuration[:parser][:included_paths] ||= ['lib']
+      configuration[:parser][:excluded_paths] ||= ['sorbet', 'spec']
+
+      # Defaults can be overridden but we always want to exclude the output file
+      configuration[:parser][:excluded_paths] << configuration[:output_file][:rbi]
+    end
+
+    # Included/Excluded module defaults
+    configuration[:included_modules] ||= []
+    configuration[:excluded_modules] ||= []
+
     # Require defaults
     configuration[:requires] ||= []
     configuration[:relative_requires] ||= []
@@ -53,6 +105,15 @@ command :run do |c|
       break_params: configuration[:style][:break_params],
       tab_size: configuration[:style][:tab_size]
     )
+
+    if configuration[:parser]
+      Parlour::TypeLoader.load_project(
+        configuration[:parser][:root],
+        inclusions: configuration[:parser][:included_paths],
+        exclusions: configuration[:parser][:excluded_paths],
+        generator: gen,
+      )
+    end
     Parlour::Plugin.run_plugins(plugin_instances, gen)
 
     # Run a pass of the conflict resolver
@@ -74,6 +135,14 @@ command :run do |c|
       choice == 0 ? nil : candidates[choice - 1]
     end
 
+    if !configuration[:included_modules].empty? || !configuration[:excluded_modules].empty?
+      remove_unwanted_modules(
+        gen.root,
+        included_modules: configuration[:included_modules],
+        excluded_modules: configuration[:excluded_modules],
+      )
+    end
+
     # Figure out strictness levels
     requested_strictness_levels = plugin_instances.map do |plugin|
       s = plugin.strictness&.to_s
@@ -97,8 +166,23 @@ command :run do |c|
       end
     end
 
-    # Write the final RBI
-    File.write(configuration[:output_file], gen.rbi(strictness))
+    # Write the final files
+    if configuration[:output_file][:rbi]
+      FileUtils.mkdir_p(File.dirname(configuration[:output_file][:rbi]))
+      File.write(configuration[:output_file][:rbi], gen.rbi(strictness))
+    end
+    if configuration[:output_file][:rbs]
+      gen.root.generalize_from_rbi!
+      rbs_gen = Parlour::RbsGenerator.new
+
+      converter = Parlour::Conversion::RbiToRbs.new(rbs_gen)
+      gen.root.children.each do |child|
+        converter.convert_object(child, rbs_gen.root)
+      end
+
+      FileUtils.mkdir_p(File.dirname(configuration[:output_file][:rbs]))
+      File.write(configuration[:output_file][:rbs], rbs_gen.rbs)
+    end
   end
 end
 
@@ -122,3 +206,24 @@ def keys_to_symbols(hash)
     ]
   end.to_h
 end
+
+def remove_unwanted_modules(root, included_modules:, excluded_modules:, prefix: nil)
+  root.children.select! do |child|
+    module_name = "#{prefix}#{child.name}"
+
+    if child.respond_to?(:children)
+      remove_unwanted_modules(
+        child,
+        included_modules: included_modules,
+        excluded_modules: excluded_modules,
+        prefix: "#{module_name}::",
+      )
+      has_included_children = !child.children.empty?
+    end
+
+    included = included_modules.empty? ? true : included_modules.any? { |m| module_name.start_with?(m) }
+    excluded = excluded_modules.empty? ? false : excluded_modules.any? { |m| module_name.start_with?(m) }
+
+    (included || has_included_children) && !excluded
+  end
+end