rdl 1.1.0 → 1.1.1.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d70ef3cc3d6edbb1cf16a849e412dc465510a606
-  data.tar.gz: b544a1f441d5d2d5beaa023a435940b2ad332ddf
+  metadata.gz: 89545c8109d2fcc279258745760772a7114d6842
+  data.tar.gz: 308333136875d3904304c6475d2503e61adb0a8d
 SHA512:
-  metadata.gz: c3004c7b0b1b13e4d507497bde17980ec35d80fece303666f07ceee739efeec81bc33a35e09283c222782f419ac2cfbc7d19e163d6988c485a764901e41a262d
-  data.tar.gz: 57246478d603a49ef56bc1dd5266ecdda6f8f8331149beb96651a4d4c30c81764feae526522e7c4c73d37e48003520b54946eef732099256df26120aad084bc6
+  metadata.gz: b967fbe0e88dc13e802cb71c85e603d4886cb4beb98b708069507f6bafc7a4507909c8b2e003cdc73f28d926a7de45c610e3a9d3b8a0ba7708c738f25850c56f
+  data.tar.gz: 6f6506ddffe97004b10d01cec5fa1ed3897aa429a2d40c2cbc708440553ad6eab53b746a2084bee9d8861dc67b6b80bfcb6851c25825ddde674a7c2a104b4abe

data/.travis.yml

@@ -17,4 +17,5 @@ rvm:
   - 2.2.3
   - 2.2.4
   - 2.3.0
+  - 2.3.1
 sudo: false

data/CHANGES.md

@@ -0,0 +1,25 @@
+# Change log!
+
+## [Unreleased]
+
+## [1.1.1] - 2016-05-21
+### Fixed
+- Update code to eliminate Ruby 2.3 warning messages
+- Fixed errors in post conditions of numeric types (incorrect number of args)
+- Added syntax highlighting in README.md as pointed out by jsyeo
+- Comprehensive changes to types of Numeric subclass methods to make types more specific & accurate
+- Changed superclasses of numeric classes to be `Numeric`
+
+### Added
+- Higher-order types and tests for them
+- Dependent types
+- `/extras` directory, which contains random type tests for numeric subclass method types
+- `BigDecimal` added to alias `%real`
+- Changelog added!
+
+## [1.1.0] - 2016-01-03
+### Added
+- Added much enhanced `rdl_query` facility and accompanying command-line script.
+
+## [1.0.0] - 2015-12-18
+- First release!

data/README.md

@@ -1,10 +1,11 @@
-[![Gem Version](https://badge.fury.io/rb/rdl.svg)](https://badge.fury.io/rb/rdl)
+[![Gem Version](https://badge.fury.io/rb/rdl.svg)](https://badge.fury.io/rb/rdl) [![Build Status](https://travis-ci.org/plum-umd/rdl.svg?branch=master)](https://travis-ci.org/plum-umd/rdl)
+
 
 # Introduction
 
 RDL is a lightweight system for adding contracts to Ruby. A *contract* decorates a method with assertions describing what the method assumes about its inputs (called a *precondition*) and what the method guarantees about its outputs (called a *postcondition*). For example, using RDL we can write
 
-```
+```ruby
 require 'rdl'
 
 pre { |x| x > 0 }
@@ -21,7 +22,7 @@ RDL contracts are enforced at method entry and exit. For example, if we call `sq
 
 In addition to arbitrary pre- and post-conditions, RDL also has extensive support for contracts that are *types*. For example, we can write the following in RDL:
 
-```
+```ruby
 require 'rdl'
 
 type '(Fixnum, Fixnum) -> String'
@@ -32,7 +33,7 @@ This indicates that `m` is that method that returns a `String` if given two `Fix
 
 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.
 
-```
+```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
@@ -44,7 +45,7 @@ $ rdl_query "(..., Fixnum, ...) -> ."  # print all methods that take a Fixnum as
 
 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`.
 
-```
+```ruby
 $ irb
 > require 'rdl'
  => true
@@ -76,7 +77,7 @@ Use `require 'rdl'` to load the RDL library. If you want to use the core and sta
 
 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):
 
-```
+```ruby
 require 'rdl'
 require 'rdl_types'
 require 'rails_types'
@@ -118,7 +119,7 @@ A type string generally has the form `(typ1, ..., typn) -> typ` indicating a met
 
 A nominal type is simply a class name, and it matches any object of that class or any subclass.
 
-```
+```ruby
 type String, :insert, '(Fixnum, String) -> String'
 ```
 
@@ -126,12 +127,12 @@ type String, :insert, '(Fixnum, String) -> String'
 
 The nominal type `NilClass` can also be written as `nil`. The only object of this type is `nil`:
 
-```
+```ruby
 type IO, :close, '() -> nil' # IO#close always returns nil
 ```
 
 Currently, `nil` is treated as if it were an instance of any class.
-```
+```ruby
 x = "foo"
 x.insert(0, nil) # RDL does not report a type error
 ```
@@ -140,7 +141,7 @@ We chose this design based on prior experience with static type systems for Ruby
 ### Top Type (%any)
 
 RDL includes a special "top" type `%any` that matches any object:
-```
+```ruby
 type Object, :=~, '(%any) -> nil'
 ```
 We call this the "top" type because it is the top of the subclassing hierarchy RDL uses. Note that `%any` is more general than `Object`, because not all classes inherit from `Object`, e.g., `BasicObject` does not.
@@ -149,7 +150,7 @@ We call this the "top" type because it is the top of the subclassing hierarchy R
 
 Many Ruby methods can take several different types of arguments or return different types of results. The union operator `or` can be used to indicate a position where multiple types are possible.
 
-```
+```ruby
 type IO, :putc, '(Numeric or String) -> %any'
 type String, :getbyte, '(Fixnum) -> Fixnum or nil'
 ```
@@ -160,7 +161,7 @@ Note that for `getbyte`, we could leave off the `nil`, but we include it to matc
 
 Sometimes Ruby methods have several different type signatures. (In Java these would be called *overloaded* methods.) In RDL, such methods are assigned a set of type signatures:
 
-```
+```ruby
 type String, :[], '(Fixnum) -> String or nil'
 type String, :[], '(Fixnum, Fixnum) -> String or nil'
 type String, :[], '(Range or Regexp) -> String or nil'
@@ -173,7 +174,7 @@ We say the method's type is the *intersection* of the types above.
 
 When this method is called at run time, RDL checks that at least one type signature matches the call:
 
-```
+```ruby
 "foo"[0]  # matches first type
 "foo"[0,2] # matches second type
 "foo"[0..2] # matches third type
@@ -183,7 +184,7 @@ When this method is called at run time, RDL checks that at least one type signat
 
 Notice that union types in arguments could also be written as intersection types of methods, e.g., instead of the third type of `[]` above we could have equivalently written
 
-```
+```ruby
 type String, :[], '(Range) -> String or nil'
 type String, :[], '(Regexp) -> String or nil'
 ```
@@ -192,13 +193,13 @@ type String, :[], '(Regexp) -> String or nil'
 
 Optional arguments are denoted in RDL by putting `?` in front of the argument's type. For example:
 
-```
+```ruby
 type String, :chomp, '(?String) -> String'
 ```
 
 This is actually just a shorthand for an equivalent intersection type:
 
-```
+```ruby
 type String, :chomp, '() -> String'
 type String, :chomp, '(String) -> String'
 ```
@@ -211,7 +212,7 @@ Like Ruby, RDL allows optional arguments to appear anywhere in a method's type s
 
 In RDL, `*` is used to decorate an argument that may appear zero or more times. Currently in RDL this annotation may only appear on the rightmost argument. For example, `String#delete` takes one or more `String` arguments:
 
-```
+```ruby
 type String, :delete, '(String, *String) -> String'
 ```
 
@@ -219,31 +220,73 @@ type String, :delete, '(String, *String) -> String'
 
 RDL allows arguments to be named, for documentation purposes. Names are given after the argument's type, and they do not affect type contract checking in any way. For example:
 
-```
+```ruby
 type Fixnum, :to_s, '(?Fixnum base) -> String'
 ```
 
 Here we've named the first argument of `to_s` as `base` to give some extra hint as to its meaning.
 
-### Block Types
+### Dependent Types
 
-Types signatures can include a type for a method's block argument:
+RDL allows for refinement predicates to be attached to named arguments. These predicates are then checked when the method is called and returns. For instance:
 
+```ruby
+type '(Float x {{ x>=0 }}) -> Float y {{ y>=0 }}'
+def sqrt(x)
+    # return the square root of x
+end
 ```
-type Pathname, :ascend, '() { (Pathname) -> %any } -> %any'
+
+Here, RDL will check that the `sqrt` method is called on an argument of type `Float` which is greater than or equal to 0, and it will check the same of the return value of the method. Note that, in effect, dependent type contracts can be used in place of pre and post contracts.
+
+Dependencies can also exist across a method's arguments and return value:
+
+```ruby
+type '(Fixnum x {{ x>y }}, Fixnum y) -> Float z {{ z==(x+y) }}'
+def m(x,y) ... end
 ```
 
-Here the block passed to `Pathname.ascend` must take a `Pathname` and can return any object.
+Any arbitrary code can be placed between the double braces of a type refinement, and RDL will dynmically check that this predicate evaluates to true, or raise a type error if it evaluates to false.
+
+### Higher-Order Contracts
+
+RDL supports contracts for arguments or return values which are themselves `Proc` objects. Simply enclose the corresponding argument's type with braces to denote that it is a `Proc`. For example:
 
-This is a *higher-order* contract, because it applies to a higher-order method, i.e., a method that can take a block argument.
+```ruby
+type '(Fixnum, {(Fixnum) -> Fixnum}) -> Fixnum'
+def m(x, y) ... end
+```
+
+The type annotation above states that the method m takes two arguments: one of type `Fixnum`, and another which is a `Proc` which itself takes a `Fixnum` and returns a `Fixnum`. A `Proc` may be the return value of a method as well:
+
+```ruby
+type '(Fixnum) -> {(Float) -> Float}'
+def m(x) ... end
+```
+
+These higher-order contracts are checked by wrapping the corresponding `Proc` argument/return in a new `Proc` which checks that the type contract holds.
+
+A type contract can be provided for a method block as well. The block's type should be included after the method argument types:
+
+```ruby
+type '(Fixnum, Float) {(Fixnum, String) -> String } -> Float'
+def m(x,y,&blk) ... end
+```
 
-Currently higher-order contracts are not enforced. That is, RDL will not actually check contracts on block arguments.
+Note that this notation will work whether or not a method block is explicitly referenced in the parameters, i.e., whether or not `&blk` is included above. Finally, dependent types work across higher order contracts:
+
+```ruby
+type '(Fixnum x, Float y) -> {(Fixnum z {{ z>y }}) -> Fixnum}'
+def m(x,y,&blk) ... end
+```
+
+The type contract above states that method `m` returns a `Proc` which takes a `Fixnum z` which must be greater than the argument `Float y`. Whenver this `Proc` is called, it will be checked that this contract holds.
 
 ### Class/Singleton Method Types
 
 RDL method signatures can be used both for instance methods and for class methods (often called *singleton methods* in Ruby). To indicate a type signature applies to a singleton method, prefix the method name with `self.`:
 
-```
+```ruby
 type File, 'self.dirname', '(String file) -> String dir'
 ```
 
@@ -251,7 +294,7 @@ type File, 'self.dirname', '(String file) -> String dir'
 
 Type signatures can be added to `initialize` by giving a type signature for `self.new`:
 
-```
+```ruby
 type File, 'self.new', '(String file, ?String mode, ?String perm, ?Fixnum opt) -> File'
 ```
 
@@ -259,7 +302,7 @@ type File, 'self.new', '(String file, ?String mode, ?String perm, ?Fixnum opt) -
 
 Some Ruby methods are intended to take any object that has certain methods. RDL uses *structural types* to denote such cases:
 
-```
+```ruby
 type IO, :puts, '(*[to_s: () -> String]) -> nil'
 ```
 
@@ -271,23 +314,24 @@ The actual checking that RDL does here varies depending on what type information
 
 Not to be confused with types for singleton methods, RDL includes *singleton types* that denote positions that always have one particular value; this typically happens only in return positions. For example, `Dir#mkdir` always returns the value 0:
 
-```
+```ruby
 type Dir, 'self.mkdir', '(String, ?Fixnum) -> 0'
 ```
 
 In RDL, any integer or floating point number denotes a singleton type. Arbitrary values can be turned into singleton types by wrapping them in `${.}`. For example, `Float#angle` always returns 0 or pi.
 
-```
+```ruby
 type Float, :angle, '() -> 0 or ${Math::PI}'
 ```
 
 RDL checks if a value matches a singleton type using `equal?`. As a consequence, singleton string types aren't currently possible.
 
+
 ### Self Type
 
 Consider a method that returns `self`:
 
-```
+```ruby
 class A
   def id
     self
@@ -297,7 +341,7 @@ end
 
 If that method might be inherited, we can't just give it a nominal type, because it will return a different object type in a subclass:
 
-```
+```ruby
 class B < A
 end
 
@@ -308,7 +352,7 @@ B.new.id # type error, returns a B
 
 To solve this problem, RDL includes a special type `self` for this situation:
 
-```
+```ruby
 type A, :id, '() -> self'
 A.new.id # okay, returns self
 B.new.id # also okay, returns self
@@ -320,7 +364,7 @@ Note that type `self` means *exactly* the self object, i.e., it is a singleton t
 
 RDL allows types to be aliases to make them faster to write down and more readable. All type aliases begin with `%`. RDL has one built-in alias, `%bool`, which is shorthand for `TrueClass or FalseClass`:
 
-```
+```ruby
 type String, :==, '(%any) -> %bool'
 ```
 
@@ -328,7 +372,7 @@ Note it is not a bug that `==` is typed to allow any object. Though you would th
 
 Method `type_alias(name, typ)` can be used to create a user-defined type alias, where `name` must begin with `%`:
 
-```
+```ruby
 type_alias '%real', 'Integer or Float or Rational'
 type_alias '%string', '[to_str: () -> String]'
 type_alias '%path', '%string or Pathname'
@@ -340,7 +384,7 @@ Type aliases have to be created before they are used (so above, `%path` must be
 
 RDL supports *parametric polymorphism* for classes, a.k.a. *generics*. The `type_params` method names the type parameters of the class, and those parameters can then be used inside type signatures:
 
-```
+```ruby
 class Array
   type_params [:t], :all?
 
@@ -352,7 +396,7 @@ Here the first argument to `type_params` is a list of symbols or strings that na
 
 Generic types are applied to type arguments using `<...>` notation, e.g., `Array<Fixnum>` is an `Array` class where `t` is replaced by `Fixnum`. Thus, for example, if `o` is an `Array<Fixnum>`, then `o.shift` returns `Fixnum`. As another example, here is the type for the `[]` method of `Array`:
 
-```
+```ruby
 type Array, :[], '(Range) -> Array<t>'
 type Array, :[], '(Fixnum or Float) -> t'
 type Array, :[], '(Fixnum, Fixnum) -> Array<t>'
@@ -366,14 +410,14 @@ Thus, by default, even though `Array` is declared to take type parameters, by de
 
 To fully enforce generic types, RDL requires that the developer `instantiate!` an object with the desired type parameters:
 
-```
+```ruby
 x = [1,2]
 x.instantate!('Fixnum')
 x.push("three") # type error
 ```
 
 Note that the instantiated type is associated with the object, not the variable:
-```
+```ruby
 y = x
 y.push("three") # also a type error
 ```
@@ -381,7 +425,7 @@ y.push("three") # also a type error
 When RDL instantiates an object with type parameters, it needs to ensure the object's contents are consistent with the type. Currently this is enforced using the second parameter to `type_params`, which must name a method that behaves like `Array#all?`, i.e., it iterates through the contents, checking that a block argument is satisfied. As seen above, for `Array` we call `type_params(:t, :all?)`. Then at the call `x.instantiate('Fixnum')`, RDL will call `Array#all?` to iterate through the contents of `x` to check they have type `Fixnum`.
 
 RDL also includes a `deinstantiate!` method to remove the type instantiation from an object:
-```
+```ruby
 x.deinstantiate!
 x.push("three") # no longer a type error
 ```
@@ -401,14 +445,14 @@ A type such as `Array<Fixnum>` is useful for homogeneous arrays, where all eleme
 
 RDL includes special *tuple types* to handle this situation. Tuple types are written `[t1, ..., tn]`, denoting an `Array` of `n` elements of types `t1` through `tn`, in that order. For example, `[1, "two"]` has type `[Fixnum, String]`. As another example, here is the type of `Process#getrlimit`, which returns a two-element array of `Fixnums`:
 
-```
+```ruby
 type Process, 'self.getrlimit', '(Symbol or String or Fixnum resource) -> [Fixnum, Fixnum] cur_max_limit'
 ```
 
 ### Finite Hash Types
 
 Similarly to tuple types, RDL also supports *finite hash types* for heterogenous hashes. Finite hash types are written `{k1 => v1, ..., kn => vn}` to indicate a `Hash` with `n` mappings of type `ki` maps to `vi`. The `ki` may be strings, integers, floats, or constants denoted with `${.}`. If a key is a symbol, then the mapping should be written `ki: vi`. In the latter case, the `{}`'s can be left off:
-```
+```ruby
 type MyClass, :foo, '(a: Fixnum, b: String) { () -> %any } -> %any'
 ```
 Here `foo`, takes a hash where key `:a` is mapped to a `Fixnum` and key `:b` is mapped to a `String`. Similarly, `{'a'=>Fixnum, 2=>String}` types a hash where keys `'a'` and `2` are mapped to a `Fixnum` and `String`, respectively. Both syntaxes can be used to define hash types.
@@ -431,21 +475,21 @@ As discussed above, RDL includes a small script, `rdl_query`, to look up type in
 
 * Instance methods can be looked up as `Class#method`.
 
-```
+```shell
 $ rdl_query String#include?
 String#include?: (String) -> TrueClass or FalseClass
 ```
 
 * Singleton (class) methods can be looked up as `Class.method`.
 
-```
+```shell
 $ 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`.
 
-```
+```shell
 $ rdl_query Array
 &: (Array<u>) -> Array<t>
 *: (String) -> String
@@ -454,7 +498,7 @@ $ rdl_query Array
 
 * Methods can also be search for by their type signature:
 
-```
+```shell
 $ rdl_query "(Fixnum) -> Fixnum"      # print all methods of type (Fixnum) -> Fixnum
 BigDecimal.limit: (Fixnum) -> Fixnum
 Dir#pos=: (Fixnum) -> Fixnum
@@ -463,7 +507,7 @@ Dir#pos=: (Fixnum) -> Fixnum
 
 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.
 
-```
+```shell
 $ 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
@@ -479,6 +523,10 @@ Note that aside from `.` and `...`, the matching is exact. For example `(Fixnum)
 
 Here are some research papers we have written exploring contracts, types, and Ruby.
 
+* Brianna M. Ren and Jeffrey S. Foster.
+[Just-in-Time Static Type Checking for Dynamic Languages](http://www.cs.umd.edu/~jfoster/papers/pldi16.pdf).
+In ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI), Santa Barbara, CA, June 2016.
+
 * T. Stephen Strickland, Brianna Ren, and Jeffrey S. Foster.
 [Contracts for Domain-Specific Languages in Ruby](http://www.cs.umd.edu/~jfoster/papers/dls12.pdf).
 In Dynamic Languages Symposium (DLS), Portland, OR, October 2014.
@@ -513,7 +561,7 @@ In Object-Oriented Program Languages and Systems (OOPS) Track at ACM Symposium o
 
 # Copyright
 
-Copyright (c) 2014-2015, University of Maryland, College Park. All rights reserved.
+Copyright (c) 2014-2016, University of Maryland, College Park. All rights reserved.
 
 # Contributors
 
@@ -523,17 +571,10 @@ Copyright (c) 2014-2015, University of Maryland, College Park. All rights reserv
 * [Brianna M. Ren](https://www.cs.umd.edu/~bren/)
 * [T. Stephen Strickland](https://www.cs.umd.edu/~sstrickl/)
 * Alexander T. Yu
-
-# RDL Build Status
-
-[![Build Status](https://travis-ci.org/plum-umd/rdl.svg?branch=master)](https://travis-ci.org/plum-umd/rdl)
+* Milod Kazerounian
 
 # TODO list
 
-* ProcContract, Wrap, MethodType, support higher-order contracts for blocks
-  * And higher-order type checking
-  * Block passed to contracts don't work yet
-
 * How to check whether initialize? is user-defined? method_defined? always
   returns true, meaning wrapping isn't fully working with initialize.
 
@@ -548,27 +589,26 @@ Copyright (c) 2014-2015, University of Maryland, College Park. All rights reserv
 
 * Rails types
 
-* Proc types
-
 * Deferred contracts on new (watch for class addition)
 
 * DSL contracts
 
-* Documentation!
+* double-splat arguments, which bind to an arbitrary set of keywords
 
-* double-splat arguments, which bind to an arbitrary set of keywords.
+* included versus extended modules, e.g., Kernel is included in Object, so its
+  class methods become Object's instance methods
 
-* included versus extended modules, e.g., Kernel is included in
-+  Object, so its class methods become Object's instance methods.
-
-* Better story for different types for different Ruby versions.
+* Better story for different types for different Ruby versions
 
 * 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?
+* 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 ...
+
+* Queries, allow regexp in class and method names; suggested by Andreas Adamcik, Vienna