parlour 2.0.0 → 5.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 382331994bebd14df33b96b084d725b0375fa84e0a3aa263e944bad22bb5ef3f
-  data.tar.gz: 33b9014173a85bc6dddec5aa3ad38cc7e23d869636694fbbe96d4e07c7e78886
+  metadata.gz: 8117de48194856013f343430fd893e1b8bc75e51fc8b8811e70bc89a3f9989aa
+  data.tar.gz: bc980c3cb70a33c60fc92c23f10f2d844da076161a65e2c24fde49e24d4aceb9
 SHA512:
-  metadata.gz: 6ecd35a473c689909a7ef3b84af799cfa718b1901929743676c557d95f6dd717b3c9cd60dcec1c4274ce1ecc4e69310aa3213505c6f3ef479cfa580ccb39f187
-  data.tar.gz: 7dddda7cb3a9d123e74f0ed218d62b17697f63451b7389d6d5c92bb4712d41b1cc920380eb8ee3b84c7916be5ad8c32c5d2bb0f3b46c7828acefa45fa0581683
+  metadata.gz: 6bcf142fd126d52f38d2d0d5f597e85d7a4274c321b927230ce100aae9d3941bd6abb7e2cf35ccf597c2b5eaf71121126d5bd85c814d63cdece0e479536740c3
+  data.tar.gz: 5af1d6099e12dff2105dca26c4a6db90bba1190018ab7e514dd413e272e3942ef3b608666e91e5fa26b6bdc23f2d886e41ab1d1655085e36ca5f0b94b461448f

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/.travis.yml

@@ -10,9 +10,6 @@ rvm:
   - 2.6
   - 2.7
   - ruby-head
-matrix:
-  allow_failures:
-    - rvm: ruby-head
 
 jobs:
   include:
@@ -26,3 +23,6 @@ jobs:
         keep_history: true
         on:
           branch: master
+  allow_failures:
+    - rvm: 2.3
+    - rvm: ruby-head

data/CHANGELOG.md

@@ -3,6 +3,70 @@ 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.
+- 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.
+- `T::Enum` classes can now be parsed.
+- Constants are now parsed.
+- `TypeParser` now detects and parses methods which do not have a `sig`.
+  **Potentially breaking if there is a strict set of methods you are expecting Parlour to detect.**
+
+### Fixed
+- "Specialized" classes, such as enums and now structs, have had many erroneous
+  conflicts with standard classes or namespaces fixed.
+- Attributes writers and methods with the same name no longer conflict incorrectly.
+
+## [2.1.0] - 2020-03-22
+### Added
+- Files can now be excluded from the `TypeLoader`.
+
+### Changed
+- A block argument in the definition but not in the signature no longer causes
+an error in the `TypeParser`.
+- Sorting of namespace children is now a stable sort.
+
+### Fixed
+- Type parameters are now parsed by the `TypeParser`.
+
 ## [2.0.0] - 2020-02-10
 ### Added
 - Parlour can now load types back out of RBI files or Ruby source files by

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!_