<commit_before># RDL Build Status

[![Build Status](https://travis-ci.org/plum-umd/rdl.png?branch=cRDL)](https://travis-ci.org/plum-umd/rdl)

# What is RDL?

RDL is a Ruby library designed for the annotation of Ruby code with run-time contracts. The RDL Typesig System is a user annotation shortcut for generating Type Contracts. RDL’s Domain Specific Language functionality further provides syntactic sugar for creating DSL contexts, while RDL’s RubyDoc support helps export Typesig and Contract information to html format.

# How to use RDL

## Writing Typesigs
```
class MyClass
  extend RDL

  def my_method …

  typesig :method_name, “ANNOTATION”, {Optional Hash of Parameterized Types}, *Additional_Contracts
  #i.e. typesig :my_method, “(Array<t>)->Array<t>”, {:t}, pre{|arr| arr.size<5}, post{|ret| ret.size<3}, post{|ret| ret.foobar}
```


### Annotation Syntax
```
#               ( Method Arguments     ) { Block      } -> Return
typesig :foo, ” ( arg0Type, … argNType ) { Annotation } -> ReturnType " 

```

### Argument Syntax
```
# Standard Argument
"Type …"

# Optional Argument
"?Type …"

# Variable Number of Arguments (Splat)
"*Type …"
```

### Type Syntax
```
# Standard Type Definition
"… Type”

# Parameterized Type
“Type<t> …”, {:t}

# Symbol Value
"… :sym" 

# Type Placeholder (any Type)
"… %any" 

# Boolean Value (TrueClass and FalseClass)
"… %bool”

# Nil Value (NilClass)
“… nil”
 
# Union Types
"… Type0 or Type1"

# Labeling (for reference in Contracts)
“… Label:Type”
```

## Using Contracts
```
# Basic Contract
contract = FlatCtc.new(“My Contract Description”) {|…| …}

# Precondition Contract
precond = pre(“My Precondition”) {|…| …}

# Postcondition Contract
postcond = post(“My Postcondition”) {|…| …}

# Bind Contract
spec :my_method_name do

  # Add contract with Contract object
  pre “Additional Description”, precond
  post “Additional Descripton”, postcond

  # Create and add contract from Block
  pre_cond(“My Precondition”) {|…| …}
  post_cond(“My Postcondition”) {|…| …}

end

# Check Contract
contract.check()
```

## Creating DSLs
```
dsl do

  # Create new keyword
  keyword :action {…}

  # Create and store nested dsl
  nested_dsl = dsl do
    …
  end

  # Include keywords from other dsl
  extend other_dsl

  # Use previously declared del context
  nested_dsl.apply {…}

end
```

## Generating RDoc
```
rdocTypesigFor(Klass) # Deprecated FIXME
```

## RDL Quick Reference

* TODO

## RDL and Rails

Add these lines in application.rb after Bundler.require (so that the
Rails version string is available and the Rails environment is loaded):

```
require '/Users/jfoster/proj/rdl/lib/rdl.rb'
require '/Users/jfoster/proj/rdl/lib/rdl_types.rb'
require '/Users/jfoster/proj/rdl/lib/rails_types.rb'
```

# TODO list

* ProcContract, Wrap, MethodType, support higher-order contracts for blocks

* FlatContract, labeled arguments?

* Hash types

* How to check whether initialize? is user-defined? method_defined? always
returns true, meaning wrapping isn't fully working with initialize

* Ruby allows varargs to appear in the middle; currently not allowed
in RDL.

* Currently if a NominalType name is expressed differently, e.g., A
  vs. EnclosingClass::A, the types will be different when compared
  with ==.

* %string type that's [to_str : () -> String]; question: do we wrap to check?

* Inheritance of contracts

* Macros (special types) that have macros instead of them
+ %bool should really be %any

* struct types

* parametric method types

* blocks, higher order type checking

* Rails types

* Proc types<commit_msg>Notes<commit_after># RDL Build Status

[![Build Status](https://travis-ci.org/plum-umd/rdl.png?branch=cRDL)](https://travis-ci.org/plum-umd/rdl)

# What is RDL?

RDL is a Ruby library designed for the annotation of Ruby code with run-time contracts. The RDL Typesig System is a user annotation shortcut for generating Type Contracts. RDL’s Domain Specific Language functionality further provides syntactic sugar for creating DSL contexts, while RDL’s RubyDoc support helps export Typesig and Contract information to html format.

# How to use RDL

## Writing Typesigs
```
class MyClass
  extend RDL

  def my_method …

  typesig :method_name, “ANNOTATION”, {Optional Hash of Parameterized Types}, *Additional_Contracts
  #i.e. typesig :my_method, “(Array<t>)->Array<t>”, {:t}, pre{|arr| arr.size<5}, post{|ret| ret.size<3}, post{|ret| ret.foobar}
```


### Annotation Syntax
```
#               ( Method Arguments     ) { Block      } -> Return
typesig :foo, ” ( arg0Type, … argNType ) { Annotation } -> ReturnType " 

```

### Argument Syntax
```
# Standard Argument
"Type …"

# Optional Argument
"?Type …"

# Variable Number of Arguments (Splat)
"*Type …"
```

### Type Syntax
```
# Standard Type Definition
"… Type”

# Parameterized Type
“Type<t> …”, {:t}

# Symbol Value
"… :sym" 

# Type Placeholder (any Type)
"… %any" 

# Boolean Value (TrueClass and FalseClass)
"… %bool”

# Nil Value (NilClass)
“… nil”
 
# Union Types
"… Type0 or Type1"

# Labeling (for reference in Contracts)
“… Label:Type”
```

## Using Contracts
```
# Basic Contract
contract = FlatCtc.new(“My Contract Description”) {|…| …}

# Precondition Contract
precond = pre(“My Precondition”) {|…| …}

# Postcondition Contract
postcond = post(“My Postcondition”) {|…| …}

# Bind Contract
spec :my_method_name do

  # Add contract with Contract object
  pre “Additional Description”, precond
  post “Additional Descripton”, postcond

  # Create and add contract from Block
  pre_cond(“My Precondition”) {|…| …}
  post_cond(“My Postcondition”) {|…| …}

end

# Check Contract
contract.check()
```

## Creating DSLs
```
dsl do

  # Create new keyword
  keyword :action {…}

  # Create and store nested dsl
  nested_dsl = dsl do
    …
  end

  # Include keywords from other dsl
  extend other_dsl

  # Use previously declared del context
  nested_dsl.apply {…}

end
```

## Generating RDoc
```
rdocTypesigFor(Klass) # Deprecated FIXME
```

## RDL Quick Reference

* TODO

## RDL and Rails

Add these lines in application.rb after Bundler.require (so that the
Rails version string is available and the Rails environment is loaded):

```
require '/Users/jfoster/proj/rdl/lib/rdl.rb'
require '/Users/jfoster/proj/rdl/lib/rdl_types.rb'
require '/Users/jfoster/proj/rdl/lib/rails_types.rb'
```

# TODO list

* ProcContract, Wrap, MethodType, support higher-order contracts for blocks

* Hash types

* How to check whether initialize? is user-defined? method_defined? always
returns true, meaning wrapping isn't fully working with initialize.

* Currently if a NominalType name is expressed differently, e.g., A
  vs. EnclosingClass::A, the types will be different when compared
  with ==.

* Inheritance of contracts

* Macros (special types) that have macros instead of them
+ %bool should really be %any

* struct types

* parametric method types

* blocks, higher order type checking

* Rails types

* Proc types

* Deferred contracts on new (watch for class addition)
{'fraction_non_alphanumeric': 0.11886415525114155, 'fraction_numerical': 0.0014269406392694063, 'mean_word_length': 4.161266568483064, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 16, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2573377', 'n_tokens_mistral': 2354, 'n_tokens_neox': 2222, 'n_words': 810}