parlour 0.1.1 → 0.2.0

data/lib/parlour/rbi_generator/parameter.rb

@@ -1,6 +1,7 @@
 # typed: true
 module Parlour
   class RbiGenerator
+    # Represents a method parameter with a Sorbet type signature.
     class Parameter
       extend T::Sig
 
@@ -11,6 +12,27 @@ module Parlour
           default: T.nilable(String)
         ).void
       end
+      # Create a new method parameter.
+      #
+      # @example Create a simple Integer parameter named +num+.
+      #   Parlour::RbiGenerator::Parameter.new('num', type: 'Integer')
+      # @example Create a nilable array parameter.
+      #   Parlour::RbiGenerator::Parameter.new('array_of_strings_or_symbols', type: 'T.nilable(T::Array(String, Symbol))')
+      # @example Create a block parameter.
+      #   Parlour::RbiGenerator::Parameter.new('&blk', type: 'T.proc.void')
+      # @example Create a parameter with a default value.
+      #   Parlour::RbiGenerator::Parameter.new('name', type: 'String', default: 'Parlour')
+      #
+      # @param name [String] The name of this parameter. This may start with +*+, +**+,
+      #   or +&+, or end with +:+, which will infer the {kind} of this
+      #   parameter. (If it contains none of those, {kind} will be +:normal+.)
+      # @param type [String, nil] A Sorbet string of this parameter's type, such as
+      #   +"String"+ or +"T.untyped"+.
+      # @param default [String, nil] A string of Ruby code for this parameter's default value.
+      #   For example, the default value of an empty string would be represented
+      #   as +"\"\""+ (or +'""'+). The default value of the decimal +3.14+
+      #   would be +"3.14"+.
+      # @return [void]
       def initialize(name, type: nil, default: nil)
         @name = name
 
@@ -24,6 +46,11 @@ module Parlour
       end
 
       sig { params(other: Object).returns(T::Boolean) }
+      # Returns true if this instance is equal to another method.
+      #
+      # @param other [Object] The other instance. If this is not a {Parameter} (or a
+      #   subclass of it), this will always return false.
+      # @return [Boolean]
       def ==(other)
         Parameter === other &&
           name    == other.name &&
@@ -33,9 +60,16 @@ module Parlour
       end
 
       sig { returns(String) }
+      # The name of this parameter, including any prefixes or suffixes such as
+      # +*+.
+      # @return [String]
       attr_reader :name
 
       sig { returns(String) }
+      # The name of this parameter, stripped of any prefixes or suffixes. For
+      # example, +*rest+ would become +rest+, or +foo:+ would become +foo+.
+      #
+      # @return [String]
       def name_without_kind
         return T.must(name[0..-2]) if kind == :keyword
 
@@ -46,15 +80,28 @@ module Parlour
       end
 
       sig { returns(T.nilable(String)) }
+      # A Sorbet string of this parameter's type, such as +"String"+ or
+      # +"T.untyped"+.
+      # @return [String, nil]
       attr_reader :type
 
       sig { returns(T.nilable(String)) }
+      # A string of Ruby code for this parameter's default value. For example,
+      # the default value of an empty string would be represented as +"\"\""+
+      # (or +'""'+). The default value of the decimal +3.14+ would be +"3.14"+.
+      # @return [String, nil]
       attr_reader :default
 
       sig { returns(Symbol) }
+      # The kind of parameter that this is. This will be one of +:normal+, 
+      # +:splat+, +:double_splat+, +:block+ or +:keyword+.
+      # @return [Symbol]
       attr_reader :kind
 
       sig { returns(String) }
+      # A string of how this parameter should be defined in a method definition.
+      #
+      # @return [String]
       def to_def_param
         if default.nil?
           "#{name}"
@@ -66,10 +113,14 @@ module Parlour
       end
 
       sig { returns(String) }
+      # A string of how this parameter should be defined in a Sorbet +sig+.
+      #
+      # @return [String]
       def to_sig_param
         "#{name_without_kind}: #{type || 'T.untyped'}"
-      end
+      end#
 
+      # A mapping of {kind} values to the characteristic prefixes each kind has.
       PREFIXES = {
         normal: '',
         splat: '*',

data/lib/parlour/rbi_generator/rbi_object.rb

@@ -1,10 +1,76 @@
 # typed: true
 module Parlour
   class RbiGenerator
-    module RbiObject
+    # An abstract class which is subclassed by any classes which can generate
+    # entire lines of an RBI, such as {Namespace} and {Method}. (As an example,
+    # {Parameter} is _not_ a subclass because it does not generate lines, only
+    # segments of definition and signature lines.)
+    # @abstract
+    class RbiObject
       extend T::Helpers
       extend T::Sig
-      interface!
+      abstract!
+
+      sig { params(generator: RbiGenerator, name: String).void }
+      # Creates a new RBI object.
+      # @note Don't call this directly.
+      #
+      # @param generator [RbiGenerator] The current RbiGenerator.
+      # @param name [String] The name of this module.
+      # @return [void]
+      def initialize(generator, name)
+        @generator = generator
+        @generated_by = generator.current_plugin
+        @name = name
+        @comments = []
+      end
+
+      sig { returns(RbiGenerator) }
+      # The generator which this object belongs to.
+      # @return [RbiGenerator]
+      attr_reader :generator
+
+      sig { returns(T.nilable(Plugin)) }
+      # The {Plugin} which was controlling the {generator} when this object was
+      # created.
+      # @return [Plugin, nil]
+      attr_reader :generated_by
+
+      sig { returns(String) }
+      # The name of this object.
+      # @return [String]
+      attr_reader :name
+
+      sig { returns(T::Array[String]) }
+      # An array of comments which will be placed above the object in the RBI
+      # file.
+      # @return [Array<String>]
+      attr_reader :comments
+
+      sig { params(comment: T.any(String, T::Array[String])).void }
+      # Adds one or more comments to this RBI object.
+      #
+      # @example Creating a module with a comment.
+      #   namespace.create_module('M') do |m|
+      #     m.add_comment('This is a module')
+      #   end
+      #
+      # @example Creating a class with a multi-line comment.
+      #   namespace.create_class('C') do |c|
+      #     c.add_comment(['This is a multi-line comment!', 'It can be as long as you want!'])
+      #   end
+      #
+      # @param comment [String, Array<String>] The new comment(s).
+      # @return [void]
+      def add_comment(comment)
+        if comment.is_a?(String)
+          comments << comment
+        elsif comment.is_a?(Array)
+          comments.concat(comment)
+        end
+      end
+
+      alias_method :add_comments, :add_comment
 
       sig do
         abstract.params(
@@ -12,6 +78,12 @@ module Parlour
           options: Options
         ).returns(T::Array[String])
       end
+      # Generates the RBI lines for this object.
+      #
+      # @abstract
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines, formatted as specified.
       def generate_rbi(indent_level, options); end
 
       sig do
@@ -19,6 +91,13 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
+      # Given an array of other objects, returns true if they may be merged
+      # into this instance using {merge_into_self}. Each subclass will have its
+      # own criteria on what allows objects to be mergeable.
+      #
+      # @abstract
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {RbiObject} instances.
+      # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others); end
 
       sig do 
@@ -26,7 +105,41 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).void
       end
+      # Given an array of other objects, merges them into this one. Each
+      # subclass will do this differently.
+      # You MUST ensure that {mergeable?} is true for those instances.
+      #
+      # @abstract
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {RbiObject} instances.
+      # @return [void]
       def merge_into_self(others); end
+
+      sig { abstract.returns(String) }
+      # Returns a human-readable brief string description of this object. This
+      # is displayed during manual conflict resolution with the +parlour+ CLI.
+      #
+      # @abstract
+      # @return [String]
+      def describe; end
+      
+      private
+
+      sig do
+        params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      # Generates the RBI lines for this object's comments.
+      #
+      # @param indent_level [Integer] The indentation level to generate the lines at.
+      # @param options [Options] The formatting options to use.
+      # @return [Array<String>] The RBI lines for each comment, formatted as specified.
+      def generate_comments(indent_level, options)
+        comments.any? \
+          ? comments.map { |c| options.indented(indent_level, "# #{c}") }
+          : []
+      end
     end
   end
-end
+end

data/lib/parlour/version.rb

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

data/parlour.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "sorbet-runtime"
+  spec.add_dependency "rainbow", "~> 3.0.0"
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"

data/plugin_examples/foobar_plugin.rb

@@ -0,0 +1,13 @@
+require 'parlour'
+
+module FooBar
+  class Plugin < Parlour::Plugin
+    def generate(root)
+      root.create_module('Foo') do |foo|
+        foo.add_comment('This is an example plugin!')
+        foo.create_module('Bar')
+        foo.create_module('Bar', interface: true)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parlour
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-05 00:00:00.000000000 Z
+date: 2019-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -97,20 +111,28 @@ dependencies:
 description: 
 email:
 - hello@aaronc.cc
-executables: []
+executables:
+- parlour
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/ISSUE_TEMPLATE/bug-report.md"
+- ".github/ISSUE_TEMPLATE/feature-request.md"
 - ".gitignore"
 - ".rspec"
+- ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
+- Rakefile
+- exe/parlour
 - lib/parlour.rb
 - lib/parlour/conflict_resolver.rb
+- lib/parlour/plugin.rb
 - lib/parlour/rbi_generator.rb
+- lib/parlour/rbi_generator/attribute.rb
 - lib/parlour/rbi_generator/class_namespace.rb
 - lib/parlour/rbi_generator/method.rb
 - lib/parlour/rbi_generator/module_namespace.rb
@@ -120,6 +142,7 @@ files:
 - lib/parlour/rbi_generator/rbi_object.rb
 - lib/parlour/version.rb
 - parlour.gemspec
+- plugin_examples/foobar_plugin.rb
 - sorbet/config
 - sorbet/rbi/gems/rake.rbi
 - sorbet/rbi/gems/rspec-core.rbi