parlour 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7b2efb86589a0b2212d88906507d92990457318bdb3902426eef282a3da1b0e
-  data.tar.gz: 16e1cb30836c714623ca43d5b72a1cfe2225bd4f93993d1c7ea9c04d2bb6db15
+  metadata.gz: 74fcc1898cf62ffe8cd5300bb14409c02b9d3a1fd3f323a07606ef399de2f9c7
+  data.tar.gz: 111bb1a4d35a610797e4d845388f6cf7dc2815b8b7732b885bc91eb281fc0408
 SHA512:
-  metadata.gz: b5862a79da284a4953bd5d87b81c7cbe3852c91434d9d9b6b6f766d7838878ac2e40699f423951a559bc4e02e51bc922b936e133f12ddbe6a8276d44df16f607
-  data.tar.gz: d563d410dce0963e554d45fceb69c295ff25a36f99093c7b392bfd52d3d33c4d7a6aa6f4e15aacb19a999db71cd98b2fd58f6e540b811793d987316573985be1
+  metadata.gz: c44c7ca71ffa19834234533348c340c341df6332f8f7ff15708e4d46c4016ef8dd5fbee5012e333338b79746bb8360aef68ea83bf50f651d6fc1b5636567895d
+  data.tar.gz: cc64f14e22f32a6952b896cb51eca120a0a5a94ccbd0aca41147af9d0dcb90d9ba6748771a1a17324a9c7ba5ecf1b6615963a174ce90b5b5a8e2d48ec8de5c91

data/CHANGELOG.md

@@ -3,6 +3,12 @@ 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/).
 
+## [0.4.0] - 2019-07-10
+### Changed
+- Breaking change: The Parlour CLI tool no longer takes command-line arguments, and instead uses a `.parlour` configuration file. See the README!
+- RBIs now begin with `# typed: strong`.
+- Plugins now define a stub constructor to avoid an exception if they don't define one.
+
 ## [0.3.1] - 2019-07-09
 ### Changed
 - Multi-line parameter lists no longer have a trailing comma.

data/README.md

@@ -11,6 +11,15 @@ Parlour is an RBI generator and merger for Sorbet. It consists of two key parts:
     RBIs for the same codebase. These are combined automatically as much as 
     possible, but any other conflicts can be resolved manually through prompts.
 
+## 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.
+
+  - 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.
+
 ## Usage
 
 There aren't really any docs currently, so have a look around the code to find
@@ -18,8 +27,7 @@ any extra options you may need.
 
 ### Using just the generator
 
-Here's a quick example of how you might generate an RBI currently, though this
-API is very likely to change:
+Here's a quick example of how you can generate an RBI:
 
 ```ruby
 require 'parlour'
@@ -82,27 +90,67 @@ end
 useful!)
 
 You can then run several plugins, combining their output and saving it into one
-RBI file, using the command-line tool. For example, if that code was in a file
-called `plugin.rb`, this would save the RBI into `output.rbi`:
+RBI file, using the command-line tool. The command line tool is configurated
+using a `.parlour` YAML file. For example, if that code was in a file
+called `plugin.rb`, then using this `.parlour` file and then running `parlour`
+would save the RBI into `output.rbi`:
 
+```yaml
+output_file: output.rbi
+
+relative_requires:
+  - plugin.rb
+  
+plugins:
+  MyPlugin: {}
 ```
-parlour --relative-requires plugin.rb MyPlugin output.rbi
+
+The `{}` indicates that this plugin needs no extra configuration. If it did need
+configuration, this could be specified like so:
+
+```yaml
+plugins:
+  MyPlugin:
+    foo: something
+    bar: something else
 ```
 
 You can also use plugins from gems. If that plugin was published as a gem called
 `parlour-gem`:
 
-```
-parlour --requires parlour-gem MyPlugin output.rbi
+```yaml
+output_file: output.rbi
+
+requires:
+  - parlour-gem
+  
+plugins:
+  MyPlugin: {}
 ```
 
 The real power of this is the ability to use many plugins at once:
 
-```
-parlour --requires gem1,gem2,gem3 Gem1::Plugin Gem2::Plugin Gem3::Plugin output.rbi
+```yaml
+output_file: output.rbi
+
+requires:
+  - gem1
+  - gem2
+  - gem3
+  
+plugins:
+  Gem1::Plugin: {}
+  Gem2::Plugin: {}
+  Gem3::Plugin: {}
 ```
 
-## Code Structure
+## Parlour Plugins
+
+_Have you written an awesome Parlour plugin? Please submit a PR to add it to this list!_
+
+  - [Sord](https://github.com/AaronC81/sord) - Generate RBIs from YARD documentation
+
+## Parlour's Code Structure
 
 ### Overall Flow
 ```
@@ -137,9 +185,6 @@ accepts the current indentation level and a set of formatting options.
 (Each object is responsible for generating its own indentation; that is, the
 lines generated by a child object should not then be indented by its parent.)
 
-I think generation is quite close to done, but it still needs features like 
-constants and type parameters.
-
 ### Plugins
 Plugins are automatically detected when they subclass `Plugin`. Plugins can then
 be run by passing an array of them, along with an `RbiGenerator`, to
@@ -165,7 +210,7 @@ It is able to do the following merges automatically:
 If a merge can't be performed automatically, then the `#resolve_conflicts`
 method takes a block. This block is passed all the conflicting objects, and one
 should be selected and returned - all others will be deleted. (Alternatively,
-the block can return nil, and all will be deleted.) This will allow a CLI to 
+the block can return nil, and all will be deleted.) This allows the CLI to 
 prompt the user asking them what they'd like to do, in the case of conflicts
 between each plugin's signatures which can't automatically be resolved.
 

data/exe/parlour

@@ -3,6 +3,7 @@ require 'parlour'
 require 'commander/import'
 require 'bundler'
 require 'rainbow'
+require 'yaml'
 
 program :name, 'parlour'
 program :version, Parlour::VERSION
@@ -10,43 +11,45 @@ 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 a list of plugins'
-  c.option '--requires STRING', String, 'A comma-separated string of gems to require'
-  c.option '--relative-requires STRING', String, 'A comma-separated string of files to require, relative to the working dir'
-  c.option '--tab-size INTEGER', Integer, 'The size of tabs to use'
-  c.option '--break-params INTEGER', Integer, 'Break params onto their own lines if there are this many'
+  c.description = 'Generates an RBI file from your .parlour file'
 
   c.action do |args, options|
-    options.default(
-      tab_size: 2,
-      break_params: 4,
-      requires: '',
-      relative_requires: ''
-    )
+    configuration = keys_to_symbols(YAML.load_file(File.join(Dir.pwd, '.parlour')))
 
-    options.requires.split(',').each { |source| require(source) }
-    options.relative_requires.split(',').each do |source|
-      require(File.join(Dir.pwd, source))
-    end
+    raise 'you must specify output_file in your .parlour file' unless configuration[:output_file]
 
-    *plugin_names, output_file = args
+    # Style defaults
+    configuration[:style] ||= {}
+    configuration[:style][:tab_size] ||= 2
+    configuration[:style][:break_params] ||= 4
 
-    raise 'no output file specified' if output_file.nil?
+    # Require defaults
+    configuration[:requires] ||= []
+    configuration[:relative_requires] ||= []
+
+    # Plugin defaults
+    configuration[:plugins] ||= []
 
     plugin_instances = []
 
+    configuration[:requires].each { |source| require(source) }
+    configuration[:relative_requires].each do |source|
+      require_relative(File.join(Dir.pwd, source))
+    end
+
     # Collect the instances of each plugin into an array
-    plugin_names.each do |name|
-      plugin = Parlour::Plugin.registered_plugins[name]
+    configuration[:plugins].each do |name, options|
+      plugin = Parlour::Plugin.registered_plugins[name.to_s]&.new(options)
       raise "missing plugin #{name}" unless plugin
       plugin_instances << plugin
     end
 
     # Create a generator instance and run all plugins on it
     gen = Parlour::RbiGenerator.new(
-      break_params: options.break_params,
-      tab_size: options.tab_size
+      break_params: configuration[:style][:break_params],
+      tab_size: configuration[:style][:tab_size]
     )
     Parlour::Plugin.run_plugins(plugin_instances, gen)
 
@@ -70,6 +73,27 @@ command :run do |c|
     end
  
     # Write the final RBI
-    File.write(output_file, gen.rbi)
+    File.write(configuration[:output_file], gen.rbi)
   end
-end
+end
+
+private
+
+# Given a hash, converts its keys and any keys of child hashes to symbols.
+# @param [Hash] hash
+# @return [void]
+def keys_to_symbols(hash)
+  hash.map do |k, v|
+    [
+      k.to_sym,
+      case v
+      when Hash
+        keys_to_symbols(v)
+      when Array
+        v.map { |x| x.is_a?(Hash) ? keys_to_symbols(x) : x }
+      else
+        v
+      end
+    ]
+  end.to_h
+end

data/lib/parlour/plugin.rb

@@ -9,7 +9,7 @@ module Parlour
 
     @@registered_plugins = {}
 
-    sig { returns(T::Hash[String, Plugin]) }
+    sig { returns(T::Hash[String, T.class_of(Plugin)]) }
     # Returns all registered plugins, as a hash of their paths to the {Plugin}
     # instances themselves.
     #
@@ -25,7 +25,7 @@ module Parlour
     # @param new_plugin [Plugin] The new plugin.
     # @return [void]
     def self.inherited(new_plugin)
-      registered_plugins[T.must(new_plugin.name)] = new_plugin.new
+      registered_plugins[T.must(new_plugin.name)] = new_plugin
     end
 
     sig { params(plugins: T::Array[Plugin], generator: RbiGenerator).void }
@@ -36,11 +36,17 @@ module Parlour
     # @return [void]
     def self.run_plugins(plugins, generator)
       plugins.each do |plugin|
+        puts "=== #{plugin.class.name}"
         generator.current_plugin = plugin
         plugin.generate(generator.root)
+      rescue Exception => e
+        puts "!!! This plugin threw an exception: #{e}"
       end
     end
 
+    sig { params(options: Hash).void }
+    def initialize(options); end
+
     sig { abstract.params(root: RbiGenerator::Namespace).void }
     # Plugin subclasses should redefine this method and do their RBI generation
     # inside it.

data/lib/parlour/rbi_generator.rb

@@ -43,7 +43,7 @@ module Parlour
     #
     # @return [String] The generated RBI file
     def rbi
-      root.generate_rbi(0, options).join("\n")
+      "# typed: strong\n" + root.generate_rbi(0, options).join("\n")
     end
   end
 end

data/lib/parlour/version.rb

@@ -1,5 +1,5 @@
 # typed: strong
 module Parlour
   # The library version.
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parlour
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-09 00:00:00.000000000 Z
+date: 2019-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime