rdl 1.0.0 → 1.0.1.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55d12c6429608dd736e3eaff00d538a23f6cddab
-  data.tar.gz: 809baeb4d773badba520c4ea8c02aec96abb54d3
+  metadata.gz: 8c8ba5d3f1fe3944a7eadae9366c10428470a623
+  data.tar.gz: d87c55ae1f8877a6cb14fafff20a38b3cc7f3137
 SHA512:
-  metadata.gz: a9169c5a1bd28c8f2acb6efd1249ec208f1ecbe5da6bc899ec6a9709eccde9d6034feda29c8582340fccc063fb226e95826d7d6d1cd5f0882b15112a9f92364c
-  data.tar.gz: 282bbeb9bf69c4e6d07fbf7acf5d715320dbbc9470f885f03e629e1485c74780171782deaa712859a9519caece26392b9784acebe67abb001924271f7ecf826a
+  metadata.gz: f31d49ff2763c501dff6093de526d6770624bae0f0e9d6c147903ade326fc8e8fecde916c7a7156f71ab218948a55334426779dfd9dc570126a2ad24a7fd7d1c
+  data.tar.gz: f81fbff3ac6b8348233c9a49471d99fcbd2885dbbf415a0454580109a2f24dd972944dc4f0a235ebee08b435334c25436b6932040baf3b86bd371256932aeb19

data/.travis.yml

@@ -16,4 +16,5 @@ rvm:
   - 2.2.2
   - 2.2.3
   - 2.2.4
+  - 2.3.0
 sudo: false

data/README.md

@@ -30,23 +30,28 @@ def m(x,y) ... end
 
 This indicates that `m` is that method that returns a `String` if given two `Fixnum` arguments. Again this contract is enforced at run-time: When `m` is called, RDL checks that `m` is given exactly two arguments and both are `Fixnums`, and that `m` returns an instance of `String`. RDL supports many more complex type annotations; see below for a complete discussion and examples. We should emphasize here that RDL types are enforced as contracts at method entry and exit. There is no static checking that the method body conforms to the types.
 
-RDL contracts and types are stored in memory at run time, so it's also possible for programs to query them. RDL includes lots of contracts and types for the core and standard libraries. Since those methods are generally trustworthy, RDL doesn't actually enforce the contracts (since that would add overhead), but they are available to search and query. For example:
+RDL contracts and types are stored in memory at run time, so it's also possible for programs to query them. RDL includes lots of contracts and types for the core and standard libraries. Since those methods are generally trustworthy, RDL doesn't actually enforce the contracts (since that would add overhead), but they are available to search and query. RDL includes a small script `rdl_query` to look up type information from the command line. Note you might need to put the argument in quotes depending on your shell.
 
 ```
+$ rdl_query String#include?            # print type for instance method of another class
+$ rdl_query Pathname.glob              # print type for singleton method of a class
+$ rdl_query Array                      # print types for all methods of a class
+$ rdl_query "(Fixnum) -> Fixnum"       # print all methods that take a Fixnum and return a Fixnum
+$ rdl_query "(.) -> Fixnum"            # print all methods that take a single arg of any type
+$ rdl_query "(..., Fixnum, ...) -> ."  # print all methods that take a Fixnum as some argument
+
+```
+
+See below for more details of the query format. The `rdl_query` method performs the same function as long as the gem is loaded, so you can use this in `irb`.
+
+```
+$ irb
 > require 'rdl'
  => true
 > require 'rdl_types'
  => true
 
-> rdl_query 'hash'             # get type for instance method of current class
-Object#hash: () -> Fixnum
- => nil
-> rdl_query 'String#include?'   # get type for instance method of another class
-String#include?: (String) -> FalseClass or TrueClass
- => nil
- > rdl_query 'Pathname.glob'   # get type for singleton method of a class
- Pathname.glob: (String p1, ?String p2) -> Array<Pathname>
- => nil
+> rdl_query '...' # as above
 ```
 
 Currently only type information is returned by `rdl_query` (and not other pre or postconditions).
@@ -55,7 +60,7 @@ Currently only type information is returned by `rdl_query` (and not other pre or
 
 ## Supported versions of Ruby
 
-RDL currently supports Ruby 2.2. It may or may not work with other versions.
+RDL currently supports Ruby 2.x. It may or may not work with other versions.
 
 ## Installing RDL
 
@@ -67,7 +72,7 @@ Use `require 'rdl'` to load the RDL library. If you want to use the core and sta
 
 * 2.x
 
-(Currently all these are assume to have the same library type signatures, which may not be correct.)
+(Currently all these are assumed to have the same library type signatures, which may not be correct.)
 
 If you're using Ruby on Rails, you can similarly `require 'rails_types'` to load in type annotations for the current `Rails::VERSION::STRING`. More specifically, add the following lines in `application.rb` after the `Bundler.require` call. (This placement is needed so the Rails version string is available and the Rails environment is loaded):
 
@@ -418,6 +423,58 @@ RDL also includes a few other useful methods:
 
 * `rdl_nowrap`, if called at the top-level of a class, tells RDL to record contracts and types for methods in that class but *not* enforce them. This is mostly used for the core and standard libraries, which have trustworthy behavior hence enforcing their types and contracts is not worth the overhead.
 
+* `rdl_query` prints information about types; see below for details.
+
+## Queries
+
+As discussed above, RDL includes a small script, `rdl_query`, to look up type information. (Currently it does not support other pre- and postconditions.) The script takes a single argument, which should be a string. Note that when using the shell script, you may need to use quotes depending on your shell. Currently several queries are supported:
+
+* Instance methods can be looked up as `Class#method`.
+
+```
+$ rdl_query String#include?
+String#include?: (String) -> TrueClass or FalseClass
+```
+
+* Singleton (class) methods can be looked up as `Class.method`.
+
+```
+$ rdl_query Pathname.glob
+Pathname.glob: (String p1, ?String p2) -> Array<Pathname>
+```
+
+* All methods of a class can be listed by passing the class name `Class`.
+
+```
+$ rdl_query Array
+&: (Array<u>) -> Array<t>
+*: (String) -> String
+... and a lot more
+```
+
+* Methods can also be search for by their type signature:
+
+```
+$ rdl_query "(Fixnum) -> Fixnum"      # print all methods of type (Fixnum) -> Fixnum
+BigDecimal.limit: (Fixnum) -> Fixnum
+Dir#pos=: (Fixnum) -> Fixnum
+... and a lot more
+```
+
+The type signature uses the standard RDL syntax, with two extensions: `.` can be used as a wildcard to match any type, and `...` can be used to match any sequence of arguments.
+
+```
+$ rdl_query "(.) -> ."                 # methods that take one argument and return anything
+$ rdl_query "(Fixnum, .) -> ."         # methods that take two arguments, the first of which is a Fixnum
+$ rdl_query "(Fixnum, ...) -> ."       # methods whose first argument is a Fixnum
+$ rdl_query "(..., Fixnum) -> ."       # methods whose last argument is a Fixnum
+$ rdl_query "(..., Fixnum, ...) -> ."  # methods that take a Fixnum somewhere
+$ rdl_query "(Fixnum or .) -> ."       # methods that take a single argument that is a union containing a Fixnum
+$ rdl_query "(.?) -> ."                # methods that take one, optional argument
+```
+
+Note that aside from `.` and `...`, the matching is exact. For example `(Fixnum) -> Fixnum` will not match a method of type `(Fixnum or String) -> Fixnum`.
+
 # Bibliography
 
 Here are some research papers we have written exploring contracts, types, and Ruby.
@@ -509,3 +566,9 @@ Copyright (c) 2014-2015, University of Maryland, College Park. All rights reserv
 * Better query facility (more kinds of searches). Contract queries?
 
 * Write documentation on: Raw Contracts and Types, RDL Configuration, Code Overview
+
+* Structural type queries, allow name to be unknown; same with finite hash keys, same with generic base types?
+
+* Allow ... in named args list in queries
+
+* Queries, include more regexp operators aside from . and ...

data/bin/rdl_query

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/rdl.rb' # Fix for release!
+require_relative '../lib/rdl_types.rb' # Fix for release!
+
+if ARGV.length != 1 then
+print <<EOF
+  Usage: rdl_query <query>
+
+  Valid queries:
+
+  Class#method - Display type of instance method
+  Class.method - Display type of class (singleton) method
+  (method type) - Display methods that have given type
+
+  Method type queries follow the usual syntax for RDL types,
+  but can also include `.' to match any type, and `...' to
+  match any sequence of types. See the README.md file for more
+  detail.
+EOF
+  exit 0
+end
+
+rdl_query(ARGV[0])

data/lib/rdl.rb

@@ -46,6 +46,7 @@ require_rel 'rdl/types/*.rb'
 require_rel 'rdl/contracts/*.rb'
 require_rel 'rdl/util.rb'
 require_rel 'rdl/wrap.rb'
+require_rel 'rdl/query.rb'
 #require_rel 'rdl/stats.rb'
 
 $__rdl_parser = RDL::Type::Parser.new
@@ -53,4 +54,4 @@ $__rdl_parser = RDL::Type::Parser.new
 # Hash from special type names to their values
 $__rdl_special_types = {'%any' => RDL::Type::TopType.new,
                         '%bool' => RDL::Type::UnionType.new(RDL::Type::NominalType.new(TrueClass),
-                                                            RDL::Type::NominalType.new(FalseClass)) }
+                                                            RDL::Type::NominalType.new(FalseClass)) }

data/lib/rdl/query.rb

@@ -0,0 +1,96 @@
+class RDL::Query
+
+  # Return a pair [name, array of the types] for the method specified by q. Valid queries are:
+  # Class#method - instance method
+  # Class.method - class method
+  # method - method of self's class
+  def self.method_query(q)
+    klass = nil
+    klass_pref = nil
+    meth = nil
+    if q =~ /(.+)#(.+)/
+      klass = $1
+      klass_pref = "#{klass}#"
+      meth = $2.to_sym
+    elsif q =~ /(.+)\.(.+)/
+      klass_pref = "#{$1}."
+      klass = RDL::Util.add_singleton_marker($1)
+      meth = $2.to_sym
+    else
+      klass = self.class.to_s
+      klass_pref = "#{klass}#"
+      meth = q.to_sym
+    end
+    name = "#{klass_pref}#{meth}"
+    if RDL::Wrap.has_contracts?(klass, meth, :type)
+      return [name, RDL::Wrap.get_contracts(klass, meth, :type)]
+    else
+      raise "No type for #{name}"
+    end
+  end
+
+  # Return an ordered list of all method types of a class. The query should be a class name.
+  def self.class_query(q)
+    klass = q.to_s
+    return [] unless $__rdl_contracts.has_key? klass
+    cls_meths = []
+    cls_klass = RDL::Util.add_singleton_marker(klass)
+    if $__rdl_contracts.has_key? cls_klass then
+      $__rdl_contracts[cls_klass].each { |meth, kinds|
+        if kinds.has_key? :type then
+          kinds[:type].each { |t| cls_meths << [meth.to_s, t] }
+        end
+      }
+    end
+    inst_meths = []
+    if $__rdl_contracts.has_key? klass then
+      $__rdl_contracts[klass].each { |meth, kinds|
+        if kinds.has_key? :type then
+          kinds[:type].each { |t| inst_meths << [meth.to_s, t] }
+        end
+      }
+    end
+    cls_meths.sort! { |p1,p2| p1[0] <=> p2[0] }
+    cls_meths.each { |m, t| m.insert(0, "self.") }
+    inst_meths.sort! { |p1,p2| p1[0] <=> p2[0] }
+    return cls_meths + inst_meths
+  end
+
+  # Return . The query should be a string containing a method type query.
+  def self.method_type_query(q)
+    q = $__rdl_parser.scan_str "#Q #{q}"
+    $__rdl_contracts.each { |klass, meths|
+      meths.each { |meth, kinds|
+        if kinds.has_key? :type then
+          kinds[:type].each { |t|
+            if q.match(t)
+              puts "#{RDL::Util.pretty_name(klass, meth)}: #{t}"
+            end
+          }
+        end
+      }
+    }
+  end
+
+end
+
+class Object
+
+  def rdl_query(q)
+    $__rdl_contract_switch.off {
+      if q =~ /^([A-Z]\w*(#|\.))?([a-z_]\w*(!|\?|=)?|!|~|\+|\*\*|-|\*|\/|%|<<|>>|&|\||\^|<|<=|=>|>|==|===|!=|=~|!~|<=>|\[\]|\[\]=)$/
+        name, typs = RDL::Query.method_query(q)
+        typs.each { |t|
+          puts "#{name}: #{t}"
+        }
+      elsif q =~ /^[A-Z]\w*$/
+        RDL::Query.class_query(q).each { |m, t| puts "#{m}: #{t}"}
+      elsif q =~ /(.*)/
+        RDL::Query.method_type_query(q)
+      else
+        raise "Don't know how to handle query"
+      end
+    }
+  end
+
+end

data/lib/rdl/types/annotated_arg.rb

@@ -10,7 +10,8 @@ module RDL::Type
     def initialize(name, type)
       @name = name
       @type = type
-      raise RuntimeError, "Attempt to create vararg type with non-type" unless type.is_a? Type
+      raise RuntimeError, "Attempt to create annotated type with non-type" unless type.is_a? Type
+      raise RuntimeError, "Attempt to create doubly annotated type" if type.is_a? AnnotatedArgType
       super()
     end
 
@@ -26,6 +27,8 @@ module RDL::Type
       return (other.instance_of? AnnotatedArgType) && (other.name == @name) && (other.type == @type)
     end
 
+    # doesn't have a match method - queries shouldn't have annotations in them
+
     def hash # :nodoc:
       return (57 + @name.hash) * @type.hash
     end

data/lib/rdl/types/dots_query.rb

@@ -0,0 +1,26 @@
+require_relative 'type_query'
+
+module RDL::Type
+  class DotsQuery < TypeQuery
+    @@cache = nil
+
+    class << self
+      alias :__new__ :new
+    end
+
+    def self.new
+      @@cache = DotsQuery.__new__ unless @@cache
+      return @@cache
+    end
+
+    def to_s
+      "..."
+    end
+
+    def ==(other)
+      return (other.instance_of? DotsQuery)
+    end
+
+    # doesn't have match method---taken care of at a higher level, in MethodType#match
+  end
+end

data/lib/rdl/types/finitehash.rb

@@ -20,6 +20,7 @@ module RDL::Type
       return (@@cache[elts] = t) # assignment evaluates to t
     end
 
+    # [+elts+] is a map from keys to types
     def initialize(elts)
       elts.each { |k, t|
         raise RuntimeError, "Got #{t.inspect} where Type expected" unless t.is_a? Type
@@ -41,20 +42,27 @@ module RDL::Type
       return (other.instance_of? FiniteHashType) && (other.elts == @elts)
     end
 
+    def match(other)
+      other = other.type if other.instance_of? AnnotatedArgType
+      return true if other.instance_of? WildQuery
+      return (@elts.length == other.elts.length &&
+              @elts.all? { |k, v| (other.elts.has_key? k) && (v.match(other.elts[k]))})
+    end
+
     def <=(other)
       return true if other.instance_of? TopType
       return self == other
       # Subtyping with Hash not allowed
       # All positions of HashTuple are invariant since tuples are mutable
     end
-    
+
     def member?(obj, *args)
       t = RDL::Util.rdl_type obj
       return t <= self if t
       rest = @elts.clone # shallow copy
 
       return false unless obj.instance_of? Hash
-      
+
       # Check that every mapping in obj exists in @map and matches the type
       obj.each_pair { |k, v|
         return false unless @elts.has_key?(k)
@@ -73,7 +81,7 @@ module RDL::Type
     def instantiate(inst)
       FiniteHashType.new(Hash[@elts.map { |k, t| [k, t.instantiate(inst)] }])
     end
-    
+
     def hash
       h = 229 * @elts.hash
     end

data/lib/rdl/types/generic.rb

@@ -41,6 +41,12 @@ module RDL::Type
       return (other.instance_of? GenericType) && (other.base == @base) && (other.params == @params)
     end
 
+    def match(other)
+      other = other.type if other.instance_of? AnnotatedArgType
+      return true if other.instance_of? WildQuery
+      return @params.length == other.params.length && @params.zip(other.params).all? { |t,o| t.match(o) }
+    end
+
     def <=(other)
       formals, variance, check = $__rdl_type_params[base.name]
       # do check here to avoid hiding errors if generic type written
@@ -79,7 +85,7 @@ module RDL::Type
       end
       return false
     end
-    
+
     def member?(obj, *args)
       raise "No type parameters defined for #{base.name}" unless $__rdl_type_params[base.name]
       formals = $__rdl_type_params[base.name][0]
@@ -92,7 +98,7 @@ module RDL::Type
     def instantiate(inst)
       GenericType.new(base, *params.map { |t| t.instantiate(inst) })
     end
-    
+
     def hash
       h = (61 + @base.hash) * @params.hash
     end

data/lib/rdl/types/intersection.rb

@@ -42,7 +42,7 @@ module RDL::Type
     def to_s  # :nodoc:
       "(#{@types.map { |t| t.to_s }.join(' and ')})"
     end
-    
+
     def eql?(other)
       self == other
     end
@@ -51,14 +51,21 @@ module RDL::Type
       return (other.instance_of? IntersectionType) && (other.types == @types)
     end
 
+    def match(other)
+      other = other.type if other.instance_of? AnnotatedArgType
+      return true if other.instance_of? WildQuery
+      return false if @types.length != other.types.length
+      @types.all? { |t| other.types.any? { |ot| t.match(ot) } }
+    end
+
     def member?(obj, *args)
       @types.all? { |t| t.member?(obj, *args) }
     end
-    
+
     def instantiate(inst)
       return IntersectionType.new(*(@types.map { |t| t.instantiate(inst) }))
     end
-    
+
     def hash  # :nodoc:
       47 + @types.hash
     end

data/lib/rdl/types/lexer.rex

@@ -24,8 +24,11 @@ rule
   ,             { [:COMMA, text] }
   \?            { [:QUERY, text] }
   \*            { [:STAR, text] }
-  \#\#      	{ [:DOUBLE_HASH, text] }
+  \#T      	    { [:HASH_TYPE, text] }
+  \#Q      	    { [:HASH_QUERY, text] }
   \$\{          { [:CONST_BEGIN, text] }
+  \.\.\.        { [:DOTS, text] }
+  \.            { [:DOT, text] }
   {FLOAT}       { [:FLOAT, text] } # Must go before FIXNUM
   {FIXNUM}      { [:FIXNUM, text] }
   {ID}          { [:ID, text] }