sord 3.0.0.beta.1 → 3.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cfc03da2fe9815159c9041a5afff2a0e1e089567cb92da25bcec87137f9e747
-  data.tar.gz: acd6551c560c205199ec494930f4628c5357a34263b0cce05757033014ba929b
+  metadata.gz: 7a96fafb7c0a8a07c5462a5138b836837e65e2dd14f68d9f51ebd502170c84f9
+  data.tar.gz: 8d82f8e1848f0422cdd4729933f867f78daffeeb226a54b826d5fd75660e73ac
 SHA512:
-  metadata.gz: a3ef67b5162e55af55f81fd056c0a1f232293c021b145fab2054cd482951c9cd22aa2e9f8874687131c65b209f2217488ce6808f9bd88da75a04928720452a34
-  data.tar.gz: 719461ac9a36dc5c636c4f1b79c22923da4e1decb25032ec8e0c6eef8df60454c3eba6d275c61f91fec9d637d200631d3c3003b1aff981d6bafac3c91323e323
+  metadata.gz: f885ba62dd5b528f63e644d6cc6d000b33f372ea07ec7f372b1231464f5989e5353db508d553d997cdb772dc5ad075cf8fc3d37ede901f16efaa031438b59474
+  data.tar.gz: 859a054fdf1e1609035862c4f95d3b03622dcf7fe97c97afae120e80168102af0806dd8463aa00815f2e294cb0c895f511a9387b4f22e8464dc8aa9dc4f9a333

data/CHANGELOG.md

@@ -3,6 +3,11 @@ 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/).
 
+## [3.0.0.beta.2] - 2020-10-05
+### Added
+- Sord is no longer limited to a known set of generics, and will instead
+  generate `Parlour::Types::Generic` types for user-defined generics.
+
 ## [3.0.0.beta.1] - 2020-09-16
 ### Added
 - Sord now uses the Parlour 5 beta's RBS generation to generate RBS files!

data/README.md

@@ -3,24 +3,27 @@
 ## Overview
 
 Sord is a [**So**rbet](https://sorbet.org) and [YA**RD**](https://yardoc.org/)
-crossover. It can automatically generate Sorbet type signatures files by
-looking at the types specified in YARD documentation comments.
+crossover. It can **automatically generate RBI and RBS type signature files** by
+looking at the **types specified in YARD documentation** comments.
 
 If your project is already YARD documented, then this can generate most of the
-Sorbet signatures you need!
+type signatures you need!
+
+Sord is the perfect way to jump-start the adoption of types in your project,
+whether you plan to use Sorbet's RBI format or Ruby 3/Steep's RBS format.
 
 Sord has the following features:
   - Automatically generates signatures for modules, classes and methods
-  - Support for multiple parameter or return types (`T.any`)
-  - Gracefully handles missing YARD types (`T.untyped`)
+  - Support for multiple parameter or return types (`T.any`/`|`)
+  - Gracefully handles missing YARD types (`T.untyped`/`untyped`)
   - Can infer setter parameter type from the corresponding getter's return type
   - Recognises mixins (`include` and `extend`)
   - Support for generic types such as `Array<T>` and `Hash<K, V>`
   - Can infer namespaced classes (`[Bar]` can become `GemName::Foo::Bar`)
-  - Handles return types which can be `nil` (`T.nilable`)
-  - Handles duck types (`T.untyped`)
+  - Handles return types which can be `nil` (`T.nilable`/`untyped`)
+  - Handles duck types (`T.untyped`/`untyped`)
   - Support for ordered list types (`[Array(Integer, Symbol)]` becomes `[Integer, Symbol]`)
-  - Support for boolean types (`[true, false]` becomes `T::Boolean`)
+  - Support for boolean types (`[true, false]` becomes `T::Boolean`/`bool`)
   - Support for `&block` parameters documented with `@yieldparam` and `@yieldreturn`
 
 ## Usage
@@ -29,7 +32,7 @@ Install Sord with `gem install sord`.
 
 Sord is a command line tool. To use it, open a terminal in the root directory
 of your project and invoke `sord`, passing a path where you'd like to save your
-`.rbi` (this file will be overwritten):
+file (this file will be overwritten):
 
 ```
 sord defs.rbi
@@ -37,7 +40,12 @@ sord defs.rbi
 
 Sord will generate YARD docs and then print information about what it's inferred
 as it runs. It is best to fix any issues in the YARD documentation, as any edits
-made to the resulting RBI file will be replaced if you re-run Sord.
+made to the resulting file will be replaced if you re-run Sord.
+
+The output type is inferred by the file extension you use, but you can also
+specify it explicitly with `--rbi` or `--rbs`.
+
+## Shipping RBI Types
 
 RBI files generated by Sord can be used in two main ways:
 
@@ -50,18 +58,22 @@ where the maintainer is unwilling to ship type signatures with the gem itself.
 
 ### Flags
 
-Sord also takes some flags to alter the generated `.rbi` file:
+Sord also takes some flags to alter the generated file:
 
-  - `--no-sord-comments`: Generates the `.rbi` file without any Sord comments 
-    about warnings/inferences/errors. (The original file's comments will still
-    be included.)
+  - `--rbi`/`--rbs`: Override the output format inferred from the file
+    extension.
+  - `--no-sord-comments`: Generates the file without any Sord comments about
+    warnings/inferences/errors. (The original file's comments will still be
+    included.)
   - `--no-regenerate`: By default, Sord will regenerate a repository's YARD
     docs for you. This option skips regenerating the YARD docs.
   - `--break-params`: Determines how many parameters are necessary before
     the signature is changed from a single-line to a multi-line block.
     (Default: 4)
-  - `--replace-errors-with-untyped`: Uses `T.untyped` instead of `SORD_ERROR_*` constants.
-  - `--replace-unresolved-with-untyped`: Uses `T.untyped` when Sord is unable to resolve a constant.
+  - `--replace-errors-with-untyped`: Uses `T.untyped` instead of `SORD_ERROR_*`
+    constants.
+  - `--replace-unresolved-with-untyped`: Uses `T.untyped` when Sord is unable to
+    resolve a constant.
   - `--include-messages` and `--exclude-messages`: Used to filter the logging
     messages given by Sord. `--include-messages` acts as a whitelist, printing
     only messages of the specified logging kinds, whereas `--exclude-messages`
@@ -85,10 +97,10 @@ module Example
       @age = age
     end
 
-    # @return name [String]
+    # @return [String]
     attr_accessor :name
 
-    # @return age [Integer]
+    # @return [Integer]
     attr_accessor :age
 
     # @param possible_names [Array<String>] An array of potential names to choose from.
@@ -106,9 +118,8 @@ First, generate a YARD registry by running `yardoc test.rb`. Then, we can run
 files! Note the `.rbi` file extension.) In doing this, Sord prints:
 
 ```
-[INFER] (Example::Person#name=) inferred type of parameter "value" as String using getter's return type
-[INFER] (Example::Person#age=) inferred type of parameter "value" as Integer using getter's return type
-[DONE ] Processed 8 objects
+[INFER] Assuming from filename you wish to generate in RBI format
+[DONE ] Processed 8 objects (2 namespaces and 6 methods)
 ```
 
 The `test.rbi` file then contains a complete RBI file for `test.rb`:
@@ -117,29 +128,45 @@ The `test.rbi` file then contains a complete RBI file for `test.rb`:
 # typed: strong
 module Example
   class Person
-    # @param `name` — The name of the Person to create.
-    # @param `age` — The age of the Person to create.
-    sig { params(name: String, age: Integer).returns(Example::Person) }
+    # _@param_ `name` — The name of the Person to create.
+    # 
+    # _@param_ `age` — The age of the Person to create.
+    sig { params(name: String, age: Integer).void }
     def initialize(name, age); end
 
-    sig { returns(String) }
-    def name; end
+    # _@param_ `possible_names` — An array of potential names to choose from.
+    # 
+    # _@param_ `possible_ages` — An array of potential ages to choose from.
+    sig { params(possible_names: T::Array[String], possible_ages: T::Array[Integer]).returns(Example::Person) }
+    def self.construct_randomly(possible_names, possible_ages); end
 
-    # sord infer - inferred type of parameter "value" as String using getter's return type
-    sig { params(value: String).returns(String) }
-    def name=(value); end
+    sig { returns(String) }
+    attr_accessor :name
 
     sig { returns(Integer) }
-    def age; end
+    attr_accessor :age
+  end
+end
+```
 
-    # sord infer - inferred type of parameter "value" as Integer using getter's return type
-    sig { params(value: Integer).returns(Integer) }
-    def age=(value); end
+If we had instead generated `test.rbs`, we would get this file in RBS format:
 
-    # @param `possible_names` — An array of potential names to choose from.
-    # @param `possible_ages` — An array of potential ages to choose from.
-    sig { params(possible_names: T::Array[String], possible_ages: T::Array[Integer]).returns(Example::Person) }
-    def self.construct_randomly(possible_names, possible_ages); end
+```ruby
+module Example
+  class Person
+    # _@param_ `name` — The name of the Person to create.
+    # 
+    # _@param_ `age` — The age of the Person to create.
+    def initialize: (String name, Integer age) -> void
+
+    # _@param_ `possible_names` — An array of potential names to choose from.
+    # 
+    # _@param_ `possible_ages` — An array of potential ages to choose from.
+    def self.construct_randomly: (Array[String] possible_names, Array[Integer] possible_ages) -> Example::Person
+
+    attr_accessor name: String
+
+    attr_accessor age: Integer
   end
 end
 ```
@@ -148,12 +175,13 @@ end
 
 The general rule of thumb for type conversions is:
 
-  - If Sord understands the YARD type, then it is converted into the Sorbet type.
+  - If Sord understands the YARD type, then it is converted into the RBI or RBS
+    type.
   - If the YARD type is missing, Sord fills in `T.untyped`.
   - If the YARD type can't be understood, Sord creates an undefined Ruby constant
     with a similar name to the unknown YARD type. For example, the obviously
     invalid YARD type `A%B` will become a constant called `SORD_ERROR_AB`.
-    You should search through your resulting RBI to find and fix and 
+    You should search through your resulting file to find and fix and 
     `SORD_ERROR`s.
 
 ## Contributing
@@ -161,11 +189,11 @@ The general rule of thumb for type conversions is:
 Bug reports and pull requests are welcome on GitHub at https://github.com/AaronC81/sord. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 While contributing, if you want to see the results of your changes to Sord you
-can use the `examples:seed` Rake task. The task uses Sord to generate RBIs for
+can use the `examples:seed` Rake task. The task uses Sord to generate types for
 a number of open source Ruby gems, including Bundler, Haml, Rouge, and RSpec.
-`rake examples:seed` (and `rake examples:reseed` to regenerate the RBI files)
-will clone the repositories of these gems into `sord_examples/` and then
-generate the RBI files into the same directory.
+`rake examples:seed` (and `rake examples:reseed` to regenerate the files) will
+clone the repositories of these gems into `sord_examples/` and then generate the
+files into the same directory.
 
 ## License
 

data/lib/sord/type_converter.rb

@@ -7,7 +7,7 @@ require 'parlour'
 module Sord
   # Contains methods to convert YARD types to Parlour types.
   module TypeConverter
-    # A regular expression which matches Ruby namespaces and identifiers. 
+    # A regular expression which matches Ruby namespaces and identifiers.
     # "Foo", "Foo::Bar", and "::Foo::Bar" are all matches, whereas "Foo.Bar"
     # or "Foo#bar" are not.
     SIMPLE_TYPE_REGEX =
@@ -20,26 +20,25 @@ module Sord
     # "Hash{String => Symbol}", etc.
     GENERIC_TYPE_REGEX =
       /(#{SIMPLE_TYPE_REGEX})\s*[<{]\s*(.*)\s*[>}]/
-    
+
     # Match duck types which require the object implement one or more methods,
     # like '#foo', '#foo & #bar', '#foo&#bar&#baz', and '#foo&#bar&#baz&#foo_bar'.
     DUCK_TYPE_REGEX =
       /^\#[a-zA-Z_][\w]*(?:[a-zA-Z_][\w=]*)*(?:( ?\& ?\#)*[a-zA-Z_][\w=]*)*$/
-    
+
     # A regular expression which matches ordered lists in the format of
     # either "Array(String, Symbol)" or "(String, Symbol)".
     ORDERED_LIST_REGEX = /^(?:Array|)\((.*)\s*\)$/
 
-    # A regular expression which matches the shorthand Hash syntax, 
+    # A regular expression which matches the shorthand Hash syntax,
     # "{String => Symbol}".
     SHORTHAND_HASH_SYNTAX = /^{\s*(.*)\s*}$/
 
-    # A regular expression which matches the shorthand Array syntax, 
+    # A regular expression which matches the shorthand Array syntax,
     # "<String>".
     SHORTHAND_ARRAY_SYNTAX = /^<\s*(.*)\s*>$/
 
-    # An array of built-in types supported by Parlour.
-    SUPPORTED_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range Hash Class}
+    # Built in parlour single arg generics
     SINGLE_ARG_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range}
 
     # Given a string of YARD type parameters (without angle brackets), splits
@@ -51,7 +50,7 @@ module Sord
       buffer = ""
       current_bracketing_level = 0
       character_pointer = 0
-      
+
       while character_pointer < params.length
         should_buffer = true
 
@@ -161,29 +160,30 @@ module Sord
         generic_type = $1
         type_parameters = $2
 
-        if SUPPORTED_GENERIC_TYPES.include?(generic_type)
-          parameters = split_type_parameters(type_parameters)
-            .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
-          if SINGLE_ARG_GENERIC_TYPES.include?(generic_type) && parameters.length > 1
-            Parlour::Types.const_get(generic_type).new(Parlour::Types::Union.new(parameters))
-          elsif generic_type == 'Class' && parameters.length == 1
-            Parlour::Types::Class.new(parameters.first)
-          elsif generic_type == 'Hash'
-            if parameters.length == 2
-              Parlour::Types::Hash.new(*parameters)
-            else
-              handle_sord_error(parameters.map(&:describe).join, "Invalid hash, must have exactly two types: #{yard.inspect}.", item, replace_errors_with_untyped)
-            end
+        parameters = split_type_parameters(type_parameters)
+          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+        if SINGLE_ARG_GENERIC_TYPES.include?(generic_type) && parameters.length > 1
+          Parlour::Types.const_get(generic_type).new(Parlour::Types::Union.new(parameters))
+        elsif generic_type == 'Class' && parameters.length == 1
+          Parlour::Types::Class.new(parameters.first)
+        elsif generic_type == 'Hash'
+          if parameters.length == 2
+            Parlour::Types::Hash.new(*parameters)
           else
-            Parlour::Types.const_get(generic_type).new(*parameters)
+            handle_sord_error(parameters.map(&:describe).join, "Invalid hash, must have exactly two types: #{yard.inspect}.", item, replace_errors_with_untyped)
           end
         else
-          return handle_sord_error(
-            generic_type,
-            "unsupported generic type #{generic_type.inspect} in #{yard.inspect}",
-            item,
-            replace_errors_with_untyped
-          )
+          if Parlour::Types.const_defined?(generic_type)
+            # This generic is built in to parlour, but sord doesn't
+            # explicitly know about it.
+            Parlour::Types.const_get(generic_type).new(*parameters)
+          else
+            # This is a user defined generic
+            Parlour::Types::Generic.new(
+              yard_to_parlour(generic_type),
+              parameters
+            )
+          end
         end
       # Converts ordered lists like Array(Symbol, String) or (Symbol, String)
       # into tuples.

data/lib/sord/version.rb

@@ -1,4 +1,4 @@
 # typed: strong
 module Sord
-  VERSION = '3.0.0.beta.1'
+  VERSION = '3.0.0.beta.2'
 end

data/rbi/sord.rbi

@@ -1,6 +1,6 @@
 # typed: strong
 module Sord
-  VERSION = T.let('3.0.0.beta.1', T.untyped)
+  VERSION = T.let('3.0.0.beta.2', T.untyped)
 
   # Handles writing logs to stdout and any other classes which request them.
   module Logging
@@ -318,7 +318,6 @@ module Sord
     ORDERED_LIST_REGEX = T.let(/^(?:Array|)\((.*)\s*\)$/, T.untyped)
     SHORTHAND_HASH_SYNTAX = T.let(/^{\s*(.*)\s*}$/, T.untyped)
     SHORTHAND_ARRAY_SYNTAX = T.let(/^<\s*(.*)\s*>$/, T.untyped)
-    SUPPORTED_GENERIC_TYPES = T.let(%w{Array Set Enumerable Enumerator Range Hash Class}, T.untyped)
     SINGLE_ARG_GENERIC_TYPES = T.let(%w{Array Set Enumerable Enumerator Range}, T.untyped)
 
     # Given a string of YARD type parameters (without angle brackets), splits

data/sord.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'yard'
   spec.add_dependency 'sorbet-runtime'
   spec.add_dependency 'commander', '~> 4.5'
-  spec.add_dependency 'parlour', '5.0.0.beta.3'
+  spec.add_dependency 'parlour', '5.0.0.beta.6'
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 3.0.0.beta.1
+  version: 3.0.0.beta.2
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-16 00:00:00.000000000 Z
+date: 2020-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.0.0.beta.3
+        version: 5.0.0.beta.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.0.0.beta.3
+        version: 5.0.0.beta.6
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement