typedocs 0.0.1

data/lib/typedocs/parser/ast_builder.rb

@@ -0,0 +1,70 @@
+require 'parslet'
+
+class Typedocs::Parser::ASTBuilder < Parslet::Parser
+  root :method_spec
+
+  rule(:method_spec) { spaces >> rep1(method_spec1, s('||')).as(:method_spec) }
+  rule(:method_spec1) { (arg_spec >> s('->')).repeat.as(:arg_specs) >> (block_spec >> s('->')).maybe.as(:block_spec) >> return_spec.maybe.as(:return_spec) }
+
+  rule(:arg_spec) { arg_attr.maybe.as(:attr) >> named_type }
+  rule(:arg_name) { v(match['_a-z0-9?!'].repeat(1)) >> spaces }
+  rule(:arg_attr) { match['*?'] }
+  rule(:named_type) {type.as(:type) | arg_name.as(:name) >> (s(':') >> type).maybe.as(:type) }
+
+  rule(:block_spec) { s('?').maybe.as(:attr) >> s('&') >> arg_name.maybe.as(:name) }
+
+  rule(:return_spec) { named_type }
+
+  rule(:type) { rep1(type1, s('|') >> s('|').absent?) }
+  rule(:type1) {
+    t(:type_name) | t(:defined_type_name) | t(:any) | t(:void) | t(:array) | t(:tuple) | hashes | values
+  }
+
+  rule(:type_name) { str('::').maybe >> v(rep1(match['A-Z'] >> match['A-Za-z0-9_'].repeat, str('::'))) >> spaces }
+  rule(:defined_type_name) { str('@') >> type_name }
+
+  rule(:any) { s('_') }
+  rule(:void) { s('void') | s('--') }
+
+  rule(:array) { s('[') >> named_type >> s('...') >> s(']') }
+  rule(:tuple) { s('[') >> rep0(named_type, s(',')).as(:types) >> s(']') }
+
+  rule(:hashes) { t(:hash_v) | t(:hash_t) }
+  rule(:hash_t) { s('{') >> named_type.as(:key_t) >> s('=>') >> named_type.as(:val_t) >> s('}') }
+  rule(:hash_v) { s('{') >> rep1(hash_v_entry, s(',')).as(:entries) >> (s(',') >> s('...')).maybe.as(:anymore) >> s('}') }
+  rule(:hash_v_entry) { values.as(:key_v) >> s("=>") >> named_type.as(:val_t) }
+
+  rule(:values) { t(:nil_value) | t(:string_value) | t(:symbol_value) }
+  rule(:nil_value) { s('nil') }
+  rule(:string_value) { string_value_sq | string_value_dq }
+  rule(:string_value_sq) { s("'") >> v((match["^'"] | str("\\'")).repeat) >> s("'") }
+  rule(:string_value_dq) { s('"') >> v((match['^"'] | str('\\"')).repeat) >> s('"') }
+  rule(:symbol_value) { str(':') >> v(match['A-Za-z_'] >> match['A-Za-z0-9_'].repeat >> match['?!'].maybe) >> spaces }
+
+  rule(:spaces) { match('\\s').repeat }
+
+  private
+    def s(string)
+      str(string) >> spaces
+    end
+
+    def sv(string)
+      str(string).as(:value) >> spaces
+    end
+
+    def v(rule)
+      rule.as(:value)
+    end
+
+    def t(rule_name)
+      send(rule_name).as(rule_name)
+    end
+
+    def rep0(rule, separator)
+      rep1(rule, separator).repeat(0)
+    end
+
+    def rep1(rule, separator)
+      rule >> (separator >> rule).repeat
+    end
+end

data/lib/typedocs/parser/object_builder.rb

@@ -0,0 +1,104 @@
+class Typedocs::Parser; end
+
+require 'parslet'
+require 'typedocs/type_spec'
+
+class Typedocs::Parser::ObjectBuilder
+  module Helper
+    def self.array(a)
+      case a
+      when Array
+        a
+      else
+        [a]
+      end
+    end
+  end
+  def self.create_builder_for(klass)
+    Parslet::Transform.new do
+      val = {value: simple(:v)}
+      ts = Typedocs::TypeSpec
+      h = Helper
+      dc = subtree(:_) # dont care
+      dc2 = subtree(:__)
+      mktype = ->(t, name) {
+        unnamed =
+          case t
+          when Array
+            ts::Or.new(t)
+          else
+            t || ts::Any.new
+          end
+        if name
+          ts::Named.new(name, unnamed)
+        else
+          unnamed
+        end
+      }
+
+      rule(method_spec: subtree(:ms)) {
+        specs = h.array(ms).map {|tree|
+          args_spec = Typedocs::ArgumentsSpec.new
+          tree[:arg_specs].each do|as|
+            type = as[:t] || Typedocs::TypeSpec::Any.new
+            case as[:a]
+            when '*'
+              args_spec.add_rest(type)
+            when '?'
+              args_spec.add_optional(type)
+            when nil
+              args_spec.add_required(type)
+            else
+              raise "Unknown attr: #{as[:a].inspect}"
+            end
+          end
+          return_spec = tree[:return_spec] || Typedocs::TypeSpec::Void.new
+          block_spec =
+            tree[:block_spec].tap do|bs|
+              break Typedocs::BlockSpec.new(:none, nil) if !bs
+              name = bs[:name] ? bs[:name][:value] : nil
+              if bs[:attr] == '?'
+                break Typedocs::BlockSpec.new(:opt, name)
+              else
+                break Typedocs::BlockSpec.new(:req, name)
+              end
+            end
+          Typedocs::MethodSpec::Single.new(args_spec, block_spec, return_spec)
+        }
+        if specs.size > 1
+          Typedocs::MethodSpec::AnyOf.new(specs)
+        else
+          specs.first
+        end
+      }
+
+      # arg
+      rule(type: subtree(:t), attr: simple(:attr)) { {t: mktype[t, nil], a: attr} }
+      rule(type: subtree(:t), name: {value: simple(:name)}, attr: simple(:attr)) { {t: mktype[t, name], a: attr} }
+      # return
+      rule(type: subtree(:t)) { mktype[t, nil] }
+      rule(type: subtree(:t), name: {value: simple(:name)}) { mktype[t, name] }
+
+      rule(type_name: val) { ts::TypeIsA.new(klass, v.to_s) }
+      rule(defined_type_name: val) { ts::UserDefinedType.new(klass, "@#{v.to_s}") }
+      rule(any: dc) { ts::Any.new }
+      rule(void: dc) { ts::Void.new }
+      rule(array: simple(:v)) { ts::Array.new(v) }
+      rule(tuple: {types: subtree(:vs)}) { ts::ArrayAsStruct.new(vs) }
+      rule(hash_t: {key_t: simple(:k), val_t: simple(:v)}) { ts::HashType.new(k,v) }
+      rule(hash_v: {entries: subtree(:entries), anymore: simple(:anymore)}) {
+        kvs = h.array(entries).map{|e|
+          k = e[:key_v]
+          v = e[:val_t]
+          key_v = k.value
+          [key_v, v]
+        }
+        ts::HashValue.new(kvs, !!anymore)
+      }
+
+      rule(string_value: val) { ts::Value.new(v.to_s) }
+      rule(symbol_value: val) { ts::Value.new(v.to_sym) }
+      rule(nil_value: dc) { ts::Value.new(nil) }
+    end
+  end
+end

data/lib/typedocs/type_spec.rb

@@ -0,0 +1,210 @@
+class Typedocs::TypeSpec
+  def error_message_for(obj)
+    "Expected #{self.to_source}, but #{obj.inspect}"
+  end
+
+  class Named < self
+    def initialize(name, spec)
+      Typedocs.ensure_klass(spec, Typedocs::TypeSpec)
+      @name = name
+      @spec = spec
+    end
+    attr_reader :name
+    attr_reader :spec
+    def valid?(arg); spec.valid?(arg); end
+    def to_source; "#{name}:#{spec.to_source}"; end
+    def error_message_for(arg)
+      spec.error_message_for(arg)
+    end
+  end
+
+  class Any < self
+    def valid?(arg); true; end
+    def to_source; '_'; end
+    def error_message_for(arg)
+      raise "This spec accepts ANY value"
+    end
+  end
+  class Void < Any
+    def to_source; 'void' end
+  end
+  class TypeIsA < self
+    def initialize(klass, name)
+      @klass = klass
+      @name = name
+    end
+    def target_klass
+      @target_klass ||= find_const @klass, @name
+    end
+    def valid?(arg);
+      arg.is_a? target_klass
+    end
+    def to_source
+      @name
+    end
+    private
+    def find_const(start, name)
+      raise ::ArgumentError, 'name' if name.empty?
+      raise ::ArgumentError, 'start' unless start
+      case name
+      when /^::/
+        const_get_from! ::Object, name
+      else
+        candidates = []
+        candidates << const_get_from(start, name)
+        candidates << const_get_with_nested(start, name)
+        candidates = candidates.reject(&:nil?).uniq
+        raise ::ArgumentError, "Type name #{name} is ambigious(search base: #{start}): #{candidates.map(&:name).join(' and ')}" if candidates.size > 1
+        raise ::ArgumentError, "Type not found: #{name}(search base: #{start})" unless candidates.size == 1
+        candidates.first
+      end
+    end
+    def const_get_with_nested(start, name)
+      top = name.split(/::/).first
+      root = start
+      until root.nil?
+        return const_get_from(root, name) if root.const_defined?(top, false)
+        root = parent_nest(root)
+      end
+      nil
+    end
+    def parent_nest(klass)
+      return nil unless klass.name =~ /::/
+      name = klass.name.split(/::/)[0..-2].join('::')
+      const_get_from ::Object, name
+    end
+    def const_get_from(root, name)
+      begin
+        const_get_from! root, name
+      rescue NameError
+        nil
+      end
+    end
+    def const_get_from!(root, name)
+      name.gsub(/^::/,'').split(/::/).inject(root) do|root, name|
+        root.const_get(name.to_sym)
+      end
+    rescue NameError => e
+      raise NameError, "NameError: #{name.inspect}"
+    end
+  end
+  class Nil < self
+    def initialize
+      @value = nil
+    end
+    def valid?(obj)
+      obj == @value
+    end
+    def to_source
+      @value.inspect
+    end
+    def error_message_for(obj)
+      "#{obj} should == #{@value.inspect}"
+    end
+  end
+  class ArrayAsStruct < self
+    def initialize(specs)
+      specs.each {|s| Typedocs.ensure_klass(s, Typedocs::TypeSpec) }
+      @specs = specs
+    end
+    def valid?(obj)
+      obj.is_a?(::Array) &&
+      @specs.size == obj.size &&
+      @specs.zip(obj).all?{|spec,elm| spec.valid?(elm)}
+    end
+    def to_source
+      "[#{@specs.map(&:to_source).join(', ')}]"
+    end
+  end
+  class Array < self
+    def initialize(spec)
+      Typedocs.ensure_klass(spec, Typedocs::TypeSpec)
+      @spec = spec
+    end
+    def valid?(obj)
+        obj.is_a?(::Array) && obj.all?{|elm| @spec.valid?(elm)}
+    end
+    def to_source
+      "#{@spec.to_source}..."
+    end
+  end
+  class HashValue < self
+    # [key, spec]... ->
+    def initialize(entries, accept_others)
+      entries.each do|k, s|
+        Typedocs.ensure_klass(s, Typedocs::TypeSpec)
+      end
+      @entries = entries
+      @accept_others = accept_others
+    end
+    def valid?(obj)
+      obj.is_a?(::Hash) &&
+      (@accept_others || @entries.size == obj.size) &&
+      @entries.all? {|key, spec| obj.has_key?(key) && spec.valid?(obj[key]) }
+    end
+    def to_source
+      "{#{@entries.map{|key,value| "#{key.inspect} => #{value.to_source}"}.join(', ')}#{@accept_others ? ', ...' : ''}}"
+    end
+  end
+  class HashType < self
+    def initialize(key_spec, value_spec)
+      @key_spec = key_spec
+      @value_spec = value_spec
+    end
+    def valid?(obj)
+      obj.is_a?(::Hash) &&
+        obj.keys.all?{|k| @key_spec.valid? k} &&
+        obj.values.all?{|v| @value_spec.valid? v}
+    end
+    def to_source
+      "{#{@key_spec.to_source} => #{@value_spec.to_source}}"
+    end
+  end
+  class Or < self
+    def initialize(children)
+      raise ArgumentError, "Children is empty" if children.empty?
+      children.each do|c|
+        Typedocs.ensure_klass(c, Typedocs::TypeSpec)
+      end
+      @children = children
+    end
+    def valid?(obj)
+      @children.any?{|spec| spec.valid? obj}
+    end
+    def to_source
+      "#{@children.map(&:to_source).join('|')}"
+    end
+  end
+  class UserDefinedType < self
+    def initialize(klass, name, spec = nil)
+      raise ArgumentError, "Invalid UDT name: #{name.inspect}" unless Typedocs::Context.valid_udt_name?(name)
+      @klass = klass
+      @name = name
+      @spec = spec
+    end
+    attr_reader :klass
+    attr_reader :name
+    def spec
+      @spec ||= Typedocs.context(klass).defined_type!(name)
+    end
+    def valid?(arg)
+      spec.valid?(arg)
+    end
+    def to_source
+      name
+    end
+  end
+  class Value < self
+    def initialize(val)
+      @value = val
+    end
+    attr_reader :value
+    def valid?(obj)
+      obj == value
+    end
+    def to_source
+      value.inspect
+    end
+  end
+end
+

data/lib/typedocs/version.rb

@@ -0,0 +1,3 @@
+module Typedocs
+  VERSION = "0.0.1"
+end

data/spec/example_spec.rb

@@ -0,0 +1,130 @@
+load File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+describe 'Usage examples' do
+  describe 'Simple example' do
+    class SimpleExample
+      include Typedocs::DSL
+
+      tdoc "Numeric -> Numeric"
+      def square x
+        x * x
+      end
+    end
+
+    subject { SimpleExample.new }
+    it { subject.square(10).should == 100 }
+    it { expect { subject.square('10') }.to raise_error Typedocs::ArgumentError }
+  end
+  describe 'Basic usage' do
+    class BasicUsage
+      include Typedocs::DSL
+
+      tdoc "Numeric -> Numeric"
+      def square(x)
+        x * x
+      end
+
+      tdoc "String"
+      def expected_string_but_nil
+        nil
+      end
+
+      tdoc "Numeric -> [Integer,String]"
+      def return_pair(num)
+        [num.to_i, num.to_s]
+      end
+
+      tdoc "[]"
+      def return_empty_array
+        []
+      end
+
+      tdoc "_ -> String | Integer"
+      def return_int_or_string(is_str)
+        is_str ? 'string' : 100
+      end
+
+      tdoc "nil"
+      def return_nil
+        nil
+      end
+    end
+
+    describe BasicUsage do
+      subject { BasicUsage.new }
+      it do
+        subject.square(10).should == 100
+      end
+      it do
+        expect { subject.square('10') }.to raise_error Typedocs::ArgumentError
+      end
+      it do
+        expect { subject.expected_string_but_nil }.to raise_error Typedocs::RetValError
+      end
+      it do
+        subject.return_pair(1).should == [1, '1']
+      end
+
+      it do
+        subject.return_empty_array.should == []
+      end
+
+      it do
+        subject.return_int_or_string(true).should == 'string'
+        subject.return_int_or_string(false).should == 100
+      end
+      it do
+        subject.return_nil.should == nil
+      end
+    end
+  end
+  class Initialize
+    include Typedocs::DSL
+
+    tdoc "Integer ->"
+    def initialize(n)
+    end
+  end
+  describe Initialize do
+    it do
+      Initialize.new(1)
+    end
+    it do
+      expect { Initialize.new(nil) }.to raise_error Typedocs::ArgumentError
+    end
+  end
+
+  class KlassMethods
+    include Typedocs::DSL
+
+    tdoc "String->Integer"
+    def self.class_method(s); s.to_i; end
+
+    def untyped_instance_method(arg); arg; end
+  end
+  describe KlassMethods do
+    it do
+      KlassMethods.new.untyped_instance_method(1).should == 1
+    end
+    it do
+      expect { KlassMethods.class_method(1) }.to raise_error Typedocs::ArgumentError
+    end
+  end
+
+  class RelativeTypeNames
+    class Outer
+      include Typedocs::DSL
+
+      tdoc "A"
+      def self.a; A.new; end
+    end
+    class A; end
+  end
+  describe RelativeTypeNames do
+    it do
+      RelativeTypeNames::Outer.a.should be_is_a(RelativeTypeNames::A)
+    end
+  end
+
+end
+