typedocs 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+coverage
+coverage.vim

data/.simplecov

@@ -0,0 +1,11 @@
+# vim: filetype=ruby
+require 'simplecov-vim/formatter'
+class SimpleCov::Formatter::MergedFormatter
+  def format(result)
+    SimpleCov::Formatter::HTMLFormatter.new.format(result)
+    SimpleCov::Formatter::VimFormatter.new.format(result)
+  end
+end
+SimpleCov.start do
+  formatter SimpleCov::Formatter::MergedFormatter
+end

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2
+script: rspec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in typedocs.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 todesking
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,232 @@
+# Typedocs : Human/Machine readable method specifications
+
+[![Build Status](https://travis-ci.org/todesking/typedocs.png)](https://travis-ci.org/todesking/typedocs)
+
+The goal of the project is to provide user-friendly type annotations for Ruby.
+
+NOTICE: This gem is very beta, any APIs/syntaxes may change in future.
+
+## Platform
+
+Ruby 1.9/2.0
+
+## Usage
+
+### Method type annotations with dynamic type checking
+
+```ruby
+require 'typedocs/enable' # Enable dynamic type-checking
+
+require 'typedocs'
+class X
+  include Typedocs::DSL
+
+  tdoc "Numeric -> Numeric"
+  def square x
+    x * x
+  end
+end
+
+X.new.square 10
+# => 100
+
+X.new.square '100'
+# Typedocs::TypeMissmatch: Argument x is not Numeric('100')
+```
+
+By default, `require 'typedocs'` define some do-nothing methods.
+For dynamic type-checking, `require 'typedocs/enable'` bereore `require 'typedocs'`.
+For example: `ruby -rtypedocs/enable ./foo.rb`, or require it in `spec_helper.rb`, etc.
+
+### Example
+```ruby
+class Example
+  include Typedocs::DSL
+
+  tdoc "String"
+  def to_s; end
+
+  tdoc "Integer -> String|nil"
+  def [](index); end
+
+  tdoc "& -> Array || Enumerable"
+  def map; end
+
+  tdoc "[[key:Integer, value:String]...]"
+  def to_a; end
+
+  tdoc "title:String -> url:String|Hash -> ?options:Hash -> String ||
+        url:String|Hash -> ?options:Hash -> &content -> String"
+  def link_to(*args); end
+end
+```
+
+### User Defined Types
+
+```ruby
+class SomethingBuilder
+  include Typedocs
+  tdoc.typedef "@ConfigHash", "{:attr_1 => Integer, :attr_2 => String}"
+
+  tdoc "@ConfigHash -> Something"
+  def build(config); end
+
+  tdoc "@ConfigHash -> SomeContext -> Something"
+  def build_with_context(config, context); end
+end
+```
+
+### Features
+
+```
+syntax: arg1_name:Type1 -> arg2_name:Type2 -> &block -> ResultType
+
+# Type name
+TypeName
+
+# User defined type name
+@TypeName
+
+# Exact value(symbol, string)
+:a
+'a'
+"a"
+
+# Special matchers
+_     # Any object
+void  # The value is not used. Typically for return type.
+      # If return type is omitted, treated as void.
+
+# Data structure
+[Type...]   # Array of Type
+[T1, T2]    # Fixed number array(tuple)
+{K => V}    # Hash specified by key type and value type
+{:key1 => V1, "key2" => V2}
+            # Hash specified by possible key value and value type
+{:key1 => V1, "Key2" => V2, ...}
+            # Same as above, but may contains unspecified key-value pair
+
+# Selection
+A|B  # A or B
+
+# Qualifier
+*var_arg
+?optional_arg
+
+&block
+?&optional_block
+```
+
+### Grammer
+
+Use `typedocs grammer` command for generate list of grammer.
+
+```
+         METHOD_SPEC <- SPACES (METHOD_SPEC1 ('||' SPACES METHOD_SPEC1){0, })
+              SPACES <- \\s{0, }
+        METHOD_SPEC1 <- ((ARG_SPEC '->' SPACES){0, }) ((BLOCK_SPEC '->' SPACES)?) (RETURN_SPEC?)
+            ARG_SPEC <- (ARG_ATTR?) NAMED_TYPE
+            ARG_ATTR <- [*?]
+          NAMED_TYPE <- TYPE / ARG_NAME ((':' SPACES TYPE)?)
+                TYPE <- TYPE1 ('|' SPACES !('|' SPACES) TYPE1){0, }
+               TYPE1 <- TYPE_NAME / DEFINED_TYPE_NAME / ANY / VOID / ARRAY / TUPLE / HASHES / VALUES
+           TYPE_NAME <- '::'? ([A-Z] [A-Za-z0-9_]{0, } ('::' [A-Z] [A-Za-z0-9_]{0, }){0, }) SPACES
+   DEFINED_TYPE_NAME <- '@' TYPE_NAME
+                 ANY <- '_' SPACES
+                VOID <- 'void' SPACES / '--' SPACES
+               ARRAY <- '[' SPACES NAMED_TYPE '...' SPACES ']' SPACES
+               TUPLE <- '[' SPACES ((NAMED_TYPE (',' SPACES NAMED_TYPE){0, }){0, }) ']' SPACES
+              HASHES <- HASH_V / HASH_T
+              HASH_V <- '{' SPACES (HASH_V_ENTRY (',' SPACES HASH_V_ENTRY){0, }) ((',' SPACES '...' SPACES)?) '}' SPACES
+        HASH_V_ENTRY <- VALUES '=>' SPACES NAMED_TYPE
+              VALUES <- NIL_VALUE / STRING_VALUE / SYMBOL_VALUE
+           NIL_VALUE <- 'nil' SPACES
+        STRING_VALUE <- STRING_VALUE_SQ / STRING_VALUE_DQ
+     STRING_VALUE_SQ <- ''' SPACES (([^'] / '\''){0, }) ''' SPACES
+     STRING_VALUE_DQ <- '"' SPACES (([^\"] / '\"'){0, }) '"' SPACES
+        SYMBOL_VALUE <- ':' ([A-Za-z_] [A-Za-z0-9_]{0, } [?!]?) SPACES
+              HASH_T <- '{' SPACES NAMED_TYPE '=>' SPACES NAMED_TYPE '}' SPACES
+            ARG_NAME <- ([_a-z0-9?!]{1, }) SPACES
+          BLOCK_SPEC <- (('?' SPACES)?) '&' SPACES (ARG_NAME?)
+         RETURN_SPEC <- NAMED_TYPE
+```
+
+### Fallbacks
+
+```
+# in your gem dir
+$ typedocs install-fallback lib
+```
+
+and
+
+```ruby
+require 'typedocs/fallback' # instead of `require 'typedocs'`
+
+class A
+  include Typedocs::DSL
+  # ...
+end
+```
+
+With that, your library works without typedocs dependency.
+When typedocs gem not found, `tdoc` method do nothing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'typedocs'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install typedocs
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## TODO
+
+    YARD style comment notation
+      # @tdoc A -> B
+      Support YARD standard tag(@param, @return) (Need another parser...)
+    Type spec:
+      Block type specification
+      Preset UDTs
+        @Boolean
+      UDT with dynamic rule
+        typedef(:@Positive) {|v| v > 0 }
+      Duck typing
+    Method spec:
+      Exception
+        String -> Integer !KeyNotFound|IOError
+    Skip checking for specific argument
+      foo 1,2,skip_validation('3')
+    Informative error message
+    Enable/Disable for specific class
+    get typedoc from method
+    Self hosting
+    Re-define existing method's spec
+    Auto spec inference(from argument name)
+    define from outer
+    Support attr_accessor
+
+## Changes
+
+### 0.0.1
+* Initial release
+
+
+* * * * *
+
+
+    vim: set shiftwidth=2 expandtab:

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/bin/typedocs

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+exit ({
+  'install-fallback' => ->(args) do
+    require 'optparse'
+    require 'fileutils'
+
+    opts={}
+    parser = OptionParser.new
+    parser.on('--help') { opts[:help] = true }
+    args = parser.parse(args)
+    usage_message = <<-EOS
+USAGE: #$0 install-fallback <dir>
+  Install typedocs fallback to <dir> for decouple library from typedocs gem.
+
+  To use it, require 'typedocs/fallback' instead of require 'typedocs'.
+    EOS
+
+    if opts[:help]
+      $stdout.puts usage_message
+      return 0
+    end
+    unless args.size == 1
+      $stderr.puts usage_message
+      return 1
+    end
+
+    dest_dir = args.first
+
+    fallback      = File.join(File.dirname(__FILE__), '..', 'lib', 'typedocs', 'fallback.rb')
+    fallback_impl = File.join(File.dirname(__FILE__), '..', 'lib', 'typedocs', 'fallback')
+    fallback_root = File.join(dest_dir, 'typedocs')
+
+    if File.exists?(fallback_root)
+      $stderr.puts "Fallback is already installed in #{fallback_root}"
+      return 1
+    end
+    FileUtils.mkdir_p(fallback_root)
+    FileUtils.cp(fallback        , fallback_root)
+    FileUtils.cp_r(fallback_impl , fallback_root)
+
+    $stdout.puts "Fallback is installed to #{fallback_root}"
+
+    return 0
+  end,
+  'grammer' => ->(args) do
+    require 'typedocs/enable'
+    require 'typedocs'
+    require 'typedocs/grammer_printer'
+
+    $stdout.puts "Grammer of Typedosc v#{Typedocs::VERSION}"
+    Typedocs::GrammerPrinter.print_grammer($stdout)
+
+    return 0
+  end,
+}[ARGV[0]]||->(args) do
+  $stderr.puts <<-EOS
+USAGE: #$0 <command> <command-args>
+  command:
+    - install-fallback
+    - grammer
+  EOS
+  return 1
+end)[ARGV[1..-1]]

data/lib/typedocs.rb

@@ -0,0 +1,78 @@
+# Dynamic type-checking is disable unless require 'typedocs/enable'
+unless ::Object.const_defined?('TYPEDOCS_ENABLED')
+  require 'typedocs/fallback/impl'
+  Typedocs = TypedocsFallback
+else
+
+
+module Typedocs; end
+
+require "typedocs/version"
+require "typedocs/dsl"
+require "typedocs/parser"
+require "typedocs/type_spec"
+require "typedocs/arguments_spec"
+require "typedocs/block_spec"
+require "typedocs/method_spec"
+require "typedocs/multi_functional_interface"
+require "typedocs/context"
+
+module Typedocs
+  def self.initialize!
+    @@method_specs = {}
+    @@contexts = {}
+  end
+  initialize!
+
+  def self.ensure_klass(obj, klass)
+    raise ArgumentError, "Expected #{klass.name} but #{obj.inspect}" unless obj.kind_of?(klass)
+  end
+
+  # MethodSpec | nil
+  def self.super_method_spec(klass, name)
+    while klass = klass.superclass
+      spec = method_spec(klass, name)
+      return spec if spec
+    end
+    nil
+  end
+
+  def self.method_spec(klass, name)
+    @@method_specs[[klass, name]]
+  end
+
+  def self.define_spec(klass, name, method_spec)
+    klass.instance_eval do
+      original_method = instance_method(name)
+      define_method name do|*args,&block|
+        method_spec.call_with_validate original_method.bind(self), *args, &block
+      end
+    end
+    @@method_specs[[klass, name]] = method_spec
+  end
+
+  def self.create_method_spec(klass, name, tdoc_arg)
+    case tdoc_arg
+    when String
+      Typedocs::Parser.new.parse(klass, tdoc_arg)
+    when :inherit
+      Typedocs.super_method_spec(klass, name) || (raise NoSuchMethod, "can't find typedoc for super method: #{klass}##{name}")
+    else
+      raise "Unsupported document: #{tdoc_arg.inspect}"
+    end
+  end
+
+  def self.context(klass)
+    Typedocs.ensure_klass(klass, Module)
+    @@contexts[klass] ||= Context.new(klass)
+  end
+
+  class ArgumentError < ::ArgumentError; end
+  class RetValError < ::StandardError; end
+  class BlockError < ::StandardError; end
+
+  class NoSuchMethod < ::StandardError; end
+  class NoSuchType < ::StandardError; end
+end
+
+end