parlour 4.0.1 → 5.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 707934b89fd83fbb876582bd7e66679bc2f8cf2179961eed62358ba6266bf524
-  data.tar.gz: 3d0a0c8be95e09275a9b02232ce9b9b062a9f00eb3216a0e74ce63a036025d76
+  metadata.gz: 8117de48194856013f343430fd893e1b8bc75e51fc8b8811e70bc89a3f9989aa
+  data.tar.gz: bc980c3cb70a33c60fc92c23f10f2d844da076161a65e2c24fde49e24d4aceb9
 SHA512:
-  metadata.gz: ae723cbe6bebbba12ee3d802b223fa91fcda085f6b1fce4ec107efa3f9e3cc5df53ee0269a6e9d1391ff32c903d15b72153c67fae61392b7e5495688b69b7b0a
-  data.tar.gz: 98626719eb9d2c08f7e87c1ae48933d8b1afb9badab000bb408a8df26c57716846b71278654193c821ce59a552c83456d1f61523ce5bd9ff0e52d296ab34e274
+  metadata.gz: 6bcf142fd126d52f38d2d0d5f597e85d7a4274c321b927230ce100aae9d3941bd6abb7e2cf35ccf597c2b5eaf71121126d5bd85c814d63cdece0e479536740c3
+  data.tar.gz: 5af1d6099e12dff2105dca26c4a6db90bba1190018ab7e514dd413e272e3942ef3b608666e91e5fa26b6bdc23f2d886e41ab1d1655085e36ca5f0b94b461448f

data/CHANGELOG.md

@@ -3,6 +3,30 @@ 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.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.

data/README.md

@@ -3,42 +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!
 
-  - You can **generate RBI 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)).
+  - 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
 
-### Using just the generator
+| Feature | RBI | RBS |
+|---------|-----|-----|
+| **GENERATION** |  |  |
+| Classes | ✅ | ⚠️ (missing `extension`) |
+| Modules | ✅ | ⚠️ (missing `extension`) |
+| Interfaces | ✅ | ✅ |
+| Attributes | ✅ | ✅ |
+| Methods | ✅ | ✅ |
+| Overloaded methods | ❌* | ✅ |
+| Structs | ✅ | ✅† |
+| Enums | ✅ | ✅† |
+| Generation with plugins | ✅ | ❌ |
+| **MANIPULATION** |  |  |
+| Parsing | ✅ | ❌ |
+| Merging | ✅ | ❌ |
 
-Here's a quick example of how you can generate an RBI:
+- ✅ - 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
+
+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.
+
+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'
@@ -72,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'
@@ -107,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
@@ -131,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
@@ -143,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
@@ -156,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
@@ -200,6 +363,31 @@ 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

@@ -25,8 +25,33 @@ command :run do |c|
       configuration = {}
     end
 
-    # Output default
-    configuration[:output_file] ||= "rbi/#{File.basename(working_dir)}.rbi"
+    # 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] ||= {}
@@ -45,7 +70,7 @@ command :run do |c|
       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]
+      configuration[:parser][:excluded_paths] << configuration[:output_file][:rbi]
     end
 
     # Included/Excluded module defaults
@@ -141,9 +166,23 @@ command :run do |c|
       end
     end
 
-    # Write the final RBI
-    FileUtils.mkdir_p(File.dirname(configuration[:output_file]))
-    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
 

data/lib/parlour.rb

@@ -9,12 +9,17 @@ require 'parlour/kernel_hack'
 
 require 'parlour/plugin'
 
+require 'parlour/types'
+
+require 'parlour/options'
+require 'parlour/typed_object'
+require 'parlour/generator'
 require 'parlour/rbi_generator/parameter'
 require 'parlour/rbi_generator/rbi_object'
+require 'parlour/rbi_generator/type_alias'
 require 'parlour/rbi_generator/method'
 require 'parlour/rbi_generator/attribute'
 require 'parlour/rbi_generator/arbitrary'
-require 'parlour/rbi_generator/options'
 require 'parlour/rbi_generator/include'
 require 'parlour/rbi_generator/extend'
 require 'parlour/rbi_generator/constant'
@@ -27,6 +32,27 @@ require 'parlour/rbi_generator/struct_class_namespace'
 require 'parlour/rbi_generator'
 require 'parlour/detached_rbi_generator'
 
+require 'parlour/rbs_generator/rbs_object'
+require 'parlour/rbs_generator/type_alias'
+require 'parlour/rbs_generator/namespace'
+require 'parlour/rbs_generator/method'
+require 'parlour/rbs_generator/arbitrary'
+require 'parlour/rbs_generator/attribute'
+require 'parlour/rbs_generator/block'
+require 'parlour/rbs_generator/class_namespace'
+require 'parlour/rbs_generator/constant'
+require 'parlour/rbs_generator/extend'
+require 'parlour/rbs_generator/include'
+require 'parlour/rbs_generator/method_signature'
+require 'parlour/rbs_generator/module_namespace'
+require 'parlour/rbs_generator/interface_namespace'
+require 'parlour/rbs_generator/parameter'
+require 'parlour/rbs_generator'
+require 'parlour/detached_rbs_generator'
+
+require 'parlour/conversion/converter'
+require 'parlour/conversion/rbi_to_rbs'
+
 require 'parlour/conflict_resolver'
 
 require 'parlour/parse_error'