yard-virtus 0.0.4

data/lib/yard/virtus/declarations/virtus_attribute.rb

@@ -0,0 +1,67 @@
+module YARD
+  module Virtus
+    module Declarations
+      # VirtusModel declaration wraps AST which represents
+      # call to `attribute` method
+      class VirtusAttribute
+        attr_reader :ast
+
+        # @params [YARD::Parser::Ruby::MethodCallNode] ast
+        def initialize(ast)
+          @ast = ast
+          @options = Options.new(parameters[2])
+        end
+
+        def readable?
+          true
+        end
+
+        def writable?
+          true
+        end
+
+        def has_private_writer?
+          options[:writer] == :private
+        end
+
+        def attr_name
+          parameters.first.jump(:ident).first.to_sym
+        end
+
+        def type
+          Type.new(type_param).yard_type_string
+        end
+
+        def attribute_reader
+          CodeObjects::AttributeReader.new(attr_name, type)
+        end
+
+        def attribute_writer
+          CodeObjects::AttributeWriter.new(attr_name, type, has_private_writer?)
+        end
+
+        protected
+        attr_reader :options
+
+        def parameters
+          ast.parameters(false)
+        end
+
+        def type_param
+          parameters[1]
+        end
+
+        def scalar_type_to_string(ref)
+          ref.path.join("::")
+        end
+
+        def collection_type_to_string(type)
+          collection_type = scalar_type_to_string(type_param[0])
+          element_type    = scalar_type_to_string(type_param[1].jump(:var_ref))
+
+          "#{collection_type}<#{element_type}>"
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/declarations/virtus_model.rb

@@ -0,0 +1,33 @@
+module YARD
+  module Virtus
+    module Declarations
+      # VirtusModel declaration wraps AST which represents
+      # inclusion of Virtus and allows to extract useful data
+      # like module proxies from it.
+      #
+      # @example
+      #   ast = s(:call, s(:var_ref, s(:const, "Virtus")), :".", s(:ident, "model"))
+      #   d   = VirtusModel.new(ast)
+      #   d.module_proxies_in_ns(ns) # => P("Virtus.model")
+      #
+      class VirtusModel
+        attr_reader :ast
+
+        # @params [YARD::Parser::Ruby::MethodCallNode] ast
+        def initialize(ast)
+          @ast = ast
+        end
+
+        # @param [YARD::CodeObjects::ClassObject] namespace
+        def module_proxies_in_ns(namespace)
+          [YARD::CodeObjects::Proxy.new(namespace, mixin_name, :module)]
+        end
+
+        protected
+        def mixin_name
+          "%s.%s" % [ast.namespace, ast.method_name].map(&:source)
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/handlers.rb

@@ -0,0 +1,2 @@
+require File.join(File.dirname(__FILE__), "handlers", "include_virtus_model")
+require File.join(File.dirname(__FILE__), "handlers", "virtus_attribute")

data/lib/yard/virtus/handlers/include_virtus_model.rb

@@ -0,0 +1,32 @@
+module YARD
+  module Virtus
+    module Handlers
+      class IncludeVirtusModel < YARD::Handlers::Ruby::Base
+        handles method_call(:include)
+        namespace_only
+
+        def process
+          raise YARD::Handlers::HandlerAborted unless virtus_module?
+
+          declaration = Declarations::VirtusModel.new(virtus_call)
+          declaration.module_proxies_in_ns(namespace).each do |proxy|
+            namespace.mixins(scope).unshift(proxy)
+          end
+
+          namespace[:supports_virtus_attributes] = true
+        end
+
+        protected
+
+        def virtus_module?
+          included_module = statement.parameters.jump(:var_ref)
+          included_module and included_module.source == "Virtus"
+        end
+
+        def virtus_call
+          statement.parameters(false)[0]
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/handlers/virtus_attribute.rb

@@ -0,0 +1,58 @@
+module YARD
+  module Virtus
+    module Handlers
+      class VirtusAttribute < YARD::Handlers::Ruby::Base
+        handles method_call(:attribute)
+        namespace_only
+
+        def process
+          raise YARD::Handlers::HandlerAborted unless virtus_model?
+
+          declaration = Declarations::VirtusAttribute.new(statement)
+
+
+          register_attribute!(declaration.attribute_reader, :read)  if declaration.readable?
+          register_attribute!(declaration.attribute_writer, :write) if declaration.writable?
+        end
+
+        protected
+
+        # @param [CodeObjects::AttributeReader, CodeObjects::AttributeWriter] mobject
+        # @param [YARD::CodeObjects::MethodObject] mobject
+        # @param [:read, :write] type
+        def register_attribute!(mobject, type)
+          yard_mobject = mobject.yard_method_object(namespace)
+
+          register_preserving_tags!(yard_mobject)
+          attributes_data_for(mobject.attr_name)[type] = yard_mobject
+        end
+
+        def attributes_data_for(name)
+          namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
+        end
+
+        def virtus_model?
+          namespace.inheritance_tree(true).any? { |n| n[:supports_virtus_attributes] == true }
+        end
+
+        # When you register an object it can get assigned docstring which
+        # followed statement which was handled. If such a docstring exists it
+        # can result in removal of previously extracted tags like `@return` and
+        # `@private` as well as default values. To prevent it we restore all
+        # tags which disappeared after registration.
+        #
+        # Do you love uncontrolled mutations as much as I do?
+        def register_preserving_tags!(object)
+          tags_before_registration = object.tags
+
+          register(object)
+
+          lost_tags = tags_before_registration - object.tags
+          if lost_tags.size > 0
+            object.add_tag(*lost_tags)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/virtus/version.rb

@@ -0,0 +1,5 @@
+module YARD
+  module Virtus
+    VERSION = "0.0.4"
+  end
+end

data/spec/code_objects/attribute_reader_spec.rb

@@ -0,0 +1,38 @@
+require "spec_helper"
+
+describe YARD::Virtus::CodeObjects::AttributeReader do
+  subject { described_class.new(:title, "String") }
+
+  it "has #attr_name" do
+    expect(subject.attr_name).to eq(:title)
+  end
+
+  it "has #type" do
+    expect(subject.type).to eq("String")
+  end
+
+  it "has #method_name" do
+    expect(subject.method_name).to eq(:title)
+  end
+
+  describe "#yard_method_object" do
+    let(:reader)    { described_class.new(:title, "String") }
+    let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+
+    subject { reader.yard_method_object(namespace) }
+
+    it { expect(subject).to be_instance_of(YARD::CodeObjects::MethodObject) }
+
+    it "is not explicit" do
+      expect(subject.is_explicit?).to be_false
+    end
+
+    it "has the same name as attribute it reads" do
+      expect(subject.name).to eq(:title)
+    end
+
+    it "has @return tag" do
+      expect(subject.has_tag?(:return)).to be_true
+    end
+  end
+end

data/spec/code_objects/attribute_writer_spec.rb

@@ -0,0 +1,75 @@
+require "spec_helper"
+
+describe YARD::Virtus::CodeObjects::AttributeWriter do
+  before :each do
+    # All YARD::CodeObjects::* objects are added to
+    # registry on creation which causes conflicts in
+    # this test.
+    YARD::Registry.clear
+  end
+
+  subject { described_class.new(:title, "String") }
+
+  it "has #attr_name" do
+    expect(subject.attr_name).to eq(:title)
+  end
+
+  it "has #type" do
+    expect(subject.type).to eq("String")
+  end
+
+  it "has #method_name" do
+    expect(subject.method_name).to eq(:"title=")
+  end
+
+  describe "#yard_method_object" do
+    let(:writer)    { described_class.new(:title, "String") }
+    let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+
+    subject { writer.yard_method_object(namespace) }
+
+    it { expect(subject).to be_instance_of(YARD::CodeObjects::MethodObject) }
+
+    it "is not explicit" do
+      expect(subject.is_explicit?).to be_false
+    end
+
+    it "has the writer name for attribute" do
+      expect(subject.name).to eq(:"title=")
+    end
+
+    it "has parameter" do
+      expect(subject.parameters).not_to be_empty
+    end
+
+    it "has type signature tag for parameter" do
+      param_tags = subject.tags(:param).select { |t| t.name == "value" }
+
+      expect(param_tags).not_to be_empty
+    end
+
+    context "when writer visibility is not specified" do
+      let(:writer) { described_class.new(:title, "String") }
+
+      it "does not have @private tag" do
+        expect(subject.tags(:private)).to be_empty
+      end
+    end
+
+    context "when writer is public" do
+      let(:writer) { described_class.new(:title, "String", false) }
+
+      it "does not have @private tag" do
+        expect(subject.tags(:private)).to be_empty
+      end
+    end
+
+    context "when writer is private" do
+      let(:writer) { described_class.new(:title, "String", true) }
+
+      it "has @private tag" do
+        expect(subject.tags(:private)).to have(1).item
+      end
+    end
+  end
+end

data/spec/declarations/options_spec.rb

@@ -0,0 +1,50 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::Options do
+  def self.example(src, &block)
+    c = context "'#{src}'"
+    # We can not generate AST for `:a => 1` so we wrap it into
+    # method call like in `attribute :a => 1` and then extract
+    # part corresponding to options. AST for wrapped code will look
+    # like this:
+    #
+    #     s(:command,
+    #       s(:ident, "attribute"),
+    #       s(s(s(:assoc,
+    #             s(:symbol_literal, s(:symbol, s(:ident, "a"))),
+    #             s(:int, "1"))), false))
+    #
+    c.let(:ast) { ruby_ast("attribute #{src}")[1] }
+    c.class_eval(&block)
+  end
+
+  subject { described_class.new(ast) }
+
+  example "" do
+    it { expect(subject).to be_empty }
+  end
+
+  example ":a => :b" do
+    it { expect(subject).not_to be_empty }
+
+    it "has information about key :a" do
+      expect(subject[:a]).to eq(:b)
+    end
+  end
+
+  example "a: :b" do
+    it { expect(subject).not_to be_empty }
+
+    it "has information about key :a" do
+      expect(subject[:a]).to eq(:b)
+    end
+  end
+
+  example ":default => lambda { 123 }" do
+    it { expect(subject).not_to be_empty }
+
+    it "has information about lambda function" do
+      expect(subject[:default]).to be_kind_of(Proc)
+    end
+  end
+end

data/spec/declarations/type_spec.rb

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::Type do
+  def self.example(src, &block)
+    c = context "'#{src}'"
+    c.let(:ast) { ruby_ast(src) }
+    c.class_eval(&block)
+  end
+
+  describe "#yard_type_string" do
+    let(:subject) { described_class.new(ast).yard_type_string }
+
+    example "String" do
+      it { expect(subject).to eq "String" }
+    end
+
+    example "Some::Nested::String" do
+      it { expect(subject).to eq "Some::Nested::String" }
+    end
+
+    example "Array[String]" do
+      it { expect(subject).to eq "Array<String>" }
+    end
+
+    example "Array[Nested::String]" do
+      it { expect(subject).to eq "Array<Nested::String>" }
+    end
+
+    example "Collection[Address]" do
+      it { expect(subject).to eq "Collection<Address>" }
+    end
+
+    example "Hash[String => Integer]" do
+      it { expect(subject).to eq "Hash{String => Integer}" }
+    end
+  end
+end

data/spec/declarations/virtus_attribute_spec.rb

@@ -0,0 +1,73 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::VirtusAttribute do
+  let(:ast) { ruby_ast(declaration) }
+  let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+  let(:subject) { described_class.new(ast) }
+
+  def self.example(src, &block)
+    c = context "'#{src}'"
+    c.let(:declaration) { src }
+    c.class_eval(&block)
+  end
+
+  example "attribute :title, String" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:title) }
+    it { expect(subject.type).to eq("String") }
+
+    it "produces reader method object" do
+      expect(subject.attribute_reader).to be_kind_of(YARD::Virtus::CodeObjects::AttributeReader)
+    end
+
+    it "produces writer method object" do
+      expect(subject.attribute_writer).to be_kind_of(YARD::Virtus::CodeObjects::AttributeWriter)
+    end
+  end
+
+  example "attribute :title, Namespaced::String" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:title) }
+    it { expect(subject.type).to eq("Namespaced::String") }
+  end
+
+  example "attribute :locations, Array[Address]" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:locations) }
+    it { expect(subject.type).to eq("Array<Address>") }
+  end
+
+  example "attribute :locations, Array[Array[Point]]" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:locations) }
+    it { expect(subject.type).to eq("Array<Array<Point>>") }
+  end
+
+  example "attribute :locations, Hash[Symbol => Address]" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:locations) }
+    it { expect(subject.type).to eq("Hash{Symbol => Address}") }
+  end
+
+  example "attribute :unique_id, String, :writer => :private" do
+    it { expect(subject).to have_private_writer }
+  end
+
+  example "attribute :unique_id, String, writer: :private" do
+    it { expect(subject).to have_private_writer }
+  end
+
+  example "attribute :unique_id, String, :writer => :private, :a => :b" do
+    it { expect(subject).to have_private_writer }
+  end
+end