├── .gitignore ├── .github └── workflows │ ├── test.yml │ ├── snapshot.yml │ └── release.yml ├── src ├── main │ └── clojure │ │ ├── clojure │ │ └── core │ │ │ ├── contracts │ │ │ ├── impl │ │ │ │ ├── readers.clj │ │ │ │ ├── funcify.clj │ │ │ │ ├── utils.clj │ │ │ │ └── transformers.clj │ │ │ └── constraints.clj │ │ │ └── contracts.clj │ │ └── data_readers.clj └── test │ └── clojure │ └── clojure │ └── core │ ├── constraints_tests.clj │ ├── with_constraints_tests.clj │ ├── provide_tests.clj │ └── contracts_tests.clj ├── examples └── simple.clj ├── docs ├── notes.org ├── thoughts.org ├── wiki │ ├── notes.markdown │ ├── with-constraints.markdown │ ├── references.markdown │ ├── provide.markdown │ └── contract.markdown ├── with-constraints.org ├── footer.org ├── toc.org ├── header.org ├── index.org ├── provide.org ├── references.org ├── contract.org └── styles │ └── default.css ├── spec2-repl.sh ├── CONTRIBUTING.md ├── spec2-cider.sh ├── project.clj ├── pom.xml ├── README.md ├── LICENSE └── epl-v10.html /.gitignore: -------------------------------------------------------------------------------- 1 | target 2 | .lein* 3 | lib 4 | multi-lib 5 | *.html 6 | -------------------------------------------------------------------------------- /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: Test 2 | 3 | on: [push] 4 | 5 | jobs: 6 | call-test: 7 | uses: clojure/build.ci/.github/workflows/test.yml@master 8 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/contracts/impl/readers.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts.impl.readers) 2 | 3 | (defn read-constraints 4 | [form] 5 | {:pre [] 6 | :post []}) 7 | 8 | -------------------------------------------------------------------------------- /src/main/clojure/data_readers.clj: -------------------------------------------------------------------------------- 1 | { 2 | ;cc/contract clojure.core.contracts.impl.readers/read-constraints 3 | ;cc/fun clojure.core/identity 4 | ;cc/invariants clojure.core/identity 5 | } 6 | -------------------------------------------------------------------------------- /.github/workflows/snapshot.yml: -------------------------------------------------------------------------------- 1 | name: Snapshot on demand 2 | 3 | on: [workflow_dispatch] 4 | 5 | jobs: 6 | call-snapshot: 7 | uses: clojure/build.ci/.github/workflows/snapshot.yml@master 8 | secrets: inherit 9 | -------------------------------------------------------------------------------- /examples/simple.clj: -------------------------------------------------------------------------------- 1 | 2 | (defn sqr [n] (* n n)) 3 | 4 | (sqr 10) 5 | ;=> 100 6 | 7 | (sqr 0) 8 | ;=> 0 9 | 10 | (contracts/provide 11 | (sqr "Constraints for squaring" 12 | [x] [number? (not= 0 x) => number? pos?])) 13 | -------------------------------------------------------------------------------- /docs/notes.org: -------------------------------------------------------------------------------- 1 | * Correctness 2 | 3 | ** Specification 4 | 5 | > Correctness is a relative notion 6 | 7 | ** Consequences 8 | 9 | 1. Knowing its correct 10 | 2. Gaining a deeper understanding of the problem 11 | 3. Documentation 12 | 4. A basis for testing 13 | 5. A basis for debugging 14 | 15 | ** Weak and Strong 16 | 17 | - weak pre 18 | - strong post 19 | -------------------------------------------------------------------------------- /docs/thoughts.org: -------------------------------------------------------------------------------- 1 | * core.contracts 2 | 3 | /A library to foster contracts programming in Clojure and ClojureScript/ 4 | 5 | ** Goals 6 | 7 | - Leverage Spec to provide a set of utiltities and usage patterns 8 | 9 | ** References / Influences 10 | 11 | - TODO 12 | 13 | ** Tasks 14 | 15 | *** TODO Remove old Trammel-inspired code. 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /docs/wiki/notes.markdown: -------------------------------------------------------------------------------- 1 | notes 2 | ===== 3 | 4 | ## 1) Correctness 5 | 6 | ### 1.1) Specification 7 | > Correctness is a relative notion 8 | 9 | ### 1.2) Consequences 10 | 1. Knowing its correct 11 | 2. Gaining a deeper understanding of the problem 12 | 3. Documentation 13 | 4. A basis for testing 14 | 5. A basis for debugging 15 | 16 | ### 1.3) Weak and Strong 17 | 18 | * weak pre 19 | * strong post 20 | 21 | -------------------------------------------------------------------------------- /docs/with-constraints.org: -------------------------------------------------------------------------------- 1 | * with-constraints 2 | 3 | core.contracts's ~with-constraints~ macro takes a function followed by one or more contracts and returns a new function that is the amalgamation of them all: 4 | 5 | #+begin_src clojure 6 | (def constrained-sqr 7 | (with-constraints 8 | sqr 9 | sqr-contract)) 10 | #+end_src 11 | 12 | See the docs of [[./contract/][contract]] for more detail. 13 | 14 | [[../docs.html][return to documentation]] 15 | -------------------------------------------------------------------------------- /spec2-repl.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | sha=`git ls-remote https://github.com/clojure/spec-alpha2.git refs/heads/master | cut -c1-40` 4 | 5 | echo "Pulling Spec2 at SHA \"${sha}\"" 6 | 7 | clj -Sdeps "{:deps {org.clojure/clojure {:mvn/version \"1.10.1\"} 8 | org.clojure/test.check {:mvn/version \"0.9.0\"} 9 | org.clojure/alpha.spec {:git/url \"https://github.com/clojure/spec-alpha2.git\" 10 | :sha \"${sha}\"}}}" 11 | -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/constraints_tests.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.constraints-tests 2 | (:use [clojure.test :only (deftest is)] 3 | [clojure.core.contracts.constraints :only (defconstrainedrecord)])) 4 | 5 | (defconstrainedrecord Foo [a] 6 | "My doc" 7 | []) 8 | 9 | (deftest instance-predicate-test 10 | (is (Foo? (->Foo 'a))) 11 | (is (not (Foo? nil)))) 12 | 13 | ;(let [a (->Foo 'a)] 14 | ; (time 15 | ; (dotimes [_ 1e6] 16 | ; (Foo? a)))) 17 | ; 17ms (instance?) 18 | ; 185ms (type) 19 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | This is a [Clojure contrib] project. 2 | 3 | Under the Clojure contrib [guidelines], this project cannot accept 4 | pull requests. All patches must be submitted via [JIRA]. 5 | 6 | See [Contributing] on the Clojure website for 7 | more information on how to contribute. 8 | 9 | [Clojure contrib]: https://clojure.org/community/contrib_libs 10 | [Contributing]: https://clojure.org/community/contributing 11 | [JIRA]: http://dev.clojure.org/jira/browse/CCONTRACTS 12 | [guidelines]: https://clojure.org/community/contrib_howto 13 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release on demand 2 | 3 | on: 4 | workflow_dispatch: 5 | inputs: 6 | releaseVersion: 7 | description: "Version to release" 8 | required: true 9 | snapshotVersion: 10 | description: "Snapshot version after release" 11 | required: true 12 | 13 | jobs: 14 | call-release: 15 | uses: clojure/build.ci/.github/workflows/release.yml@master 16 | with: 17 | releaseVersion: ${{ github.event.inputs.releaseVersion }} 18 | snapshotVersion: ${{ github.event.inputs.snapshotVersion }} 19 | secrets: inherit -------------------------------------------------------------------------------- /docs/footer.org: -------------------------------------------------------------------------------- 1 | #+begin_html 2 | 3 | 4 | source code → 5 | tickets → 6 | 7 |
8 | © 2010-2013 Michael Fogus
9 | theme based on a design by Rory Marinich 10 |
11 | 12 | 13 | #+end_html 14 | 15 | # Local Variables: 16 | # org-export-html-style-include-default: nil 17 | # org-export-html-style-include-scripts: nil 18 | # org-export-html-postamble: nil 19 | -------------------------------------------------------------------------------- /docs/toc.org: -------------------------------------------------------------------------------- 1 | * documentation 2 | 3 | Trammel provides a set of functions used to ease the inclusion of [contracts-programming](cp.html) for the [Clojure](http://clojure.org) programming language. In addition 4 | to providing a DSL for defining functions that adhere to a specific contract, Trammel provides a way to define isolated contracts that can later be applied to 5 | existing functions at runtime. Below you will find a more information on both approaches to contracts: 6 | 7 | - Applying Contracts to Existing Functions 8 | - Defining Constrained Functions 9 | - Defining Isolated Unnamed Contracts 10 | - Defining Isolated Named Contracts 11 | - Applying Contracts Manually 12 | -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/with_constraints_tests.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.with-constraints-tests 2 | (:use [clojure.core.contracts :only (contract with-constraints provide)] 3 | [clojure.test :only [deftest is]] 4 | clojure.core.contracts.impl.transformers)) 5 | 6 | (defn sqr [n] 7 | (* n n)) 8 | 9 | (def sqr-contract 10 | (contract sqr-constraints 11 | "Defines the constraints for squaring" 12 | [n] [number? (not= 0 n) => pos? number?])) 13 | 14 | (def constrained-sqr 15 | (with-constraints 16 | sqr 17 | sqr-contract)) 18 | 19 | (deftest test-with-constraints 20 | (is (= 4 (constrained-sqr 2))) 21 | (is (thrown? AssertionError (constrained-sqr 0)))) 22 | 23 | -------------------------------------------------------------------------------- /spec2-cider.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | sha=`git ls-remote https://github.com/clojure/spec-alpha2.git refs/heads/master | cut -c1-40` 4 | 5 | echo "Pulling Spec2 at SHA \"${sha}\"" 6 | 7 | clj -Sdeps "{:deps {org.clojure/clojure {:mvn/version \"1.10.1\"} 8 | org.clojure/test.check {:mvn/version \"0.9.0\"} 9 | org.clojure/alpha.spec {:git/url \"https://github.com/clojure/spec-alpha2.git\" 10 | :sha \"${sha}\"} 11 | nrepl {:mvn/version \"0.6.0\"} 12 | cider/cider-nrepl {:mvn/version \"0.22.4\"}}}" \ 13 | -m nrepl.cmdline --middleware '["cider.nrepl/cider-middleware"]' \ 14 | / 15 | 16 | 17 | -------------------------------------------------------------------------------- /project.clj: -------------------------------------------------------------------------------- 1 | (defproject core.contracts "0.0.5-SNAPSHOT" 2 | :description "Contracts programming for Clojure." 3 | :dependencies [[org.clojure/clojure "1.10.1"] 4 | [org.clojure/core.unify "0.5.7"]] 5 | :plugins [[lein-swank "1.4.4"] 6 | [lein-marginalia "0.7.1"]] 7 | :profiles {:1.2 {:dependencies [[org.clojure/clojure "1.2.0"]]} 8 | :1.2.1 {:dependencies [[org.clojure/clojure "1.2.1"]]} 9 | :1.3 {:dependencies [[org.clojure/clojure "1.3.0"]]} 10 | :1.4 {:dependencies [[org.clojure/clojure "1.4.0"]]}} 11 | :repositories {"sonatype-oss-public" "https://oss.sonatype.org/content/groups/public/"} 12 | :source-paths ["src/main/clojure"] 13 | :test-paths ["src/test/clojure"]) 14 | -------------------------------------------------------------------------------- /docs/header.org: -------------------------------------------------------------------------------- 1 | #+begin_html 2 |
3 |
4 |
a contracts-programming library for Clojure
5 |
6 |

Contracts Programming

7 |

the relationship between a class and 8 | its clients as a formal agreement, expressing each party's 9 | rights and obligations

10 |
Bertrand Meyer
11 | 12 | 15 |
16 | #+end_html 17 | 18 | 19 | 20 | #+begin_html 21 |
22 | #+end_html 23 | -------------------------------------------------------------------------------- /docs/wiki/with-constraints.markdown: -------------------------------------------------------------------------------- 1 | with-constraints 2 | ================ 3 | 4 | core.contracts's with-constraints macro takes a function followed by 5 | one or more contracts and returns a new function that is the 6 | amalgamation of them all: 7 |
8 |
9 |
10 |
11 | 
(def constrained-sqr
13 |   
  (with-constraints
    sqr
    sqr-contract))
19 |
20 |
21 |
22 |
23 | See the docs of [contract] for more detail. 24 | [return to documentation] 25 | 26 | [contract]: ./contract/ 27 | [return to documentation]: ../docs.html 28 | 29 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/contracts/impl/funcify.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts.impl.funcify) 2 | 3 | (declare funcify*) 4 | (declare funcify-factor) 5 | 6 | (defn funcify 7 | [args cnstr] 8 | (vec (map #(funcify* % args) cnstr))) 9 | 10 | 11 | (defmulti funcify* (fn [e _] (class e))) 12 | 13 | (defmethod funcify* clojure.lang.IFn [e args] (list* e args)) 14 | (defmethod funcify* java.util.regex.Pattern [e args] (list* 'clojure.core/re-matches e args)) 15 | (defmethod funcify* java.lang.String [e args] (list* 'clojure.core/= e args)) 16 | (defmethod funcify* java.lang.Number [e args] (list* 'clojure.core/= e args)) 17 | (defmethod funcify* :default [e args] (funcify-factor e args)) 18 | 19 | 20 | ;; funcify-factor 21 | 22 | (defmulti funcify-factor (fn [[h & _] _] h)) 23 | 24 | (defmethod funcify-factor 'or 25 | [e args] 26 | (list* 'or (funcify args (rest e)))) 27 | 28 | (defmethod funcify-factor 'in 29 | [e args] 30 | (concat (list* 'in args) (rest e))) 31 | 32 | (defmethod funcify-factor 'whitelist 33 | [e args] 34 | (concat (list* 'whitelist args) (rest e))) 35 | 36 | (defmethod funcify-factor :default 37 | [e args] 38 | e) -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/provide_tests.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.provide-tests 2 | (:use [clojure.test :only (deftest is)] 3 | [clojure.core.contracts :as contract])) 4 | 5 | ;; # Inline contract syntax 6 | 7 | (defn sqr [n] 8 | (* n n)) 9 | 10 | (contract/provide 11 | (sqr "The constraining of sqr" [n] 12 | [number? (not= 0 n) 13 | => 14 | pos? number?])) 15 | 16 | (deftest test-basic-provide-syntax 17 | (is (= 25 (sqr 5))) 18 | (is (= 25 (sqr -5))) 19 | (is (thrown? AssertionError (sqr 0)))) 20 | 21 | ;; # Contract name use 22 | 23 | (defn sqr2 [n] 24 | (* n n)) 25 | 26 | (def sqr-c 27 | (contract sqr-contract 28 | "Defines the constraints on squaring." 29 | [n] [number? (not= 0 n) => pos? number?])) 30 | 31 | (contract/provide 32 | (sqr2 "Apply the contract for squaring" sqr-c)) 33 | 34 | (deftest test-apply-existing-contract-by-name 35 | (is (= 25 (sqr2 5))) 36 | (is (= 25 (sqr2 -5))) 37 | (is (thrown? AssertionError (sqr2 0)))) 38 | 39 | ;; Multi-arity 40 | 41 | (defn times2 42 | ([x] (* 2 x)) 43 | ([x y] (* y x 2))) 44 | 45 | (contract/provide 46 | (times2 "The constraining of times2" 47 | [n] [number? => number? (== % (* 2 n))] 48 | [x y] [(every? number? [x y]) => number? (== % (* x y 2))])) 49 | 50 | (deftest test-apply-provide-contract-arity2-syntax 51 | (is (= 10 (times2 5))) 52 | (is (= -10 (times2 -5))) 53 | (is (thrown? AssertionError (times2 :a))) 54 | (is (= 20 (times2 2 5))) 55 | (is (= -20 (times2 -5 2))) 56 | (is (thrown? AssertionError (times2 5 :a)))) 57 | -------------------------------------------------------------------------------- /docs/index.org: -------------------------------------------------------------------------------- 1 | #+TITLE: core.contracts 2 | #+AUTHOR: Fogus 3 | 4 | #+STYLE: 5 | #+INCLUDE: header.org org 6 | 7 | First add the following to your [[https://github.com/technomancy/leiningen][Leiningen]] /project.clj/ file in the ~:dependencies~ section: 8 | 9 | #+begin_src clojure 10 | [org.clojure/core.contracts "0.0.4"] 11 | #+end_src 12 | 13 | To include core.contracts, add it to your namespace declaration: 14 | 15 | #+begin_src clojure 16 | (ns my.awesome.lib 17 | (require 18 | [clojure.core.contracts :as contracts])) 19 | #+end_src 20 | 21 | Write your functions as you normally would: 22 | 23 | #+name: simple-example 24 | #+begin_src clojure :tangle ../examples/simple.clj :noweb yes 25 | (defn sqr [n] (* n n)) 26 | 27 | (sqr 10) 28 | ;=> 100 29 | 30 | (sqr 0) 31 | ;=> 0 32 | #+end_src 33 | 34 | Later, annotate your functions separately with the constraints: 35 | 36 | #+name: simple-example 37 | #+begin_src clojure :tangle ../examples/simple.clj :noweb yes 38 | (contracts/provide 39 | (sqr "Constraints for squaring" 40 | [x] [number? (not= 0 x) => number? pos?])) 41 | #+end_src 42 | 43 | The core.contracts validation will occur at run-time: 44 | 45 | #+begin_src clojure 46 | (sqr 10) 47 | ;=> 100 48 | 49 | (sqr 0) 50 | ; java.lang.AssertionError: 51 | ; Pre-condition failed: (not= 0 x) 52 | #+end_src 53 | 54 | To turn-off contracts for any given file, add the following to the top of the file in question before compiling: 55 | 56 | #+begin_src clojure 57 | (set! *assert* false) 58 | #+end_src 59 | 60 | 61 | #+INCLUDE: footer.org org 62 | -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4.0.0 4 | core.contracts 5 | 0.0.7-SNAPSHOT 6 | core.contracts 7 | A contracts programming library for Clojure 8 | jar 9 | 10 | 11 | 12 | Eclipse Public License 1.0 13 | http://opensource.org/licenses/eclipse-1.0.php 14 | repo 15 | 16 | 17 | 18 | 19 | org.clojure 20 | pom.contrib 21 | 1.3.0 22 | 23 | 24 | 25 | 26 | fogus 27 | Fogus 28 | http://fogus.me 29 | 30 | 31 | 32 | 33 | 34 | org.clojure 35 | core.unify 36 | 0.6.0 37 | 38 | 39 | 40 | 41 | scm:git:git://github.com/clojure/core.contracts.git 42 | http://github.com/clojure/core.contracts 43 | HEAD 44 | 45 | 46 | 47 | 48 | sonatype-oss-snapshots 49 | https://oss.sonatype.org/content/repositories/snapshots 50 | 51 | 52 | 53 | -------------------------------------------------------------------------------- /docs/provide.org: -------------------------------------------------------------------------------- 1 | * provide 2 | 3 | While defining contracts local to the constrained function is nice (see [[../defconstrainedfn/][defconstrainedfn]] for more information), very often you will find yourself in possession of an existing function that is not constrained: 4 | 5 | #+begin_src clojure 6 | (sqr 0) 7 | ;;=> 0 8 | #+end_src 9 | 10 | In this case, core.contracts provides the ~provide-contracts~ macro to define contracts and apply them dynamically to existing functions: 11 | 12 | #+begin_src clojure 13 | (provide-contracts 14 | [sqr "Constraints for squaring" 15 | [x] [number? (not= 0 x) => number? pos?]]) 16 | 17 | (sqr 0) 18 | ;; java.lang.AssertionError: 19 | ;; Assert failed: (not= 0 n) 20 | #+end_src 21 | 22 | As shown, the ~sqr~ function is dynamically modified with the contract defined in the body of ~provide-contracts~. This macro can take any number of vectors where each corresponds to a contract for a given function; including multiple arities embedded within. core.contracts also allows you to include existing *named* contracts (see [[./defcontract/][defcontract]] for more information) instead of the contract specification vector, as shown below: 23 | 24 | #+begin_src clojure 25 | (defcontract sqr-contract 26 | "Defines the constraints on squaring." 27 | [n] [number? (not= 0 n) => pos? number?]) 28 | 29 | (sqr 0) 30 | ;;=> 0 31 | 32 | (provide-contracts 33 | [sqr "Apply the contract for squaring" 34 | sqr-contract]) 35 | 36 | (sqr 0) 37 | ;; java.lang.AssertionError: 38 | ;; Assert failed: (not= 0 n) 39 | #+end_src 40 | 41 | ~provide-contracts~ gives you a lot of flexibilty in how to separate functions from their contracts and likewise apply them in domain-specific ways. 42 | 43 | [[../docs.html][return to documentation]] 44 | 45 | -------------------------------------------------------------------------------- /docs/references.org: -------------------------------------------------------------------------------- 1 | * clojure.core.contracts references 2 | 3 | - [[http://tecomp.sourceforge.net/index.php?file=doc/papers/proof/engine][A Proof Engine for Eiffel]] 4 | - [[http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.116.2392][An Axiomatic Basis for Computer Programming]] by C.A.R Hoare -- essential reading 5 | - [[http://eecs.northwestern.edu/~robby/pubs/papers/behavioral-software-contracts.pdf][Behavioral Software Contracts]] (PDF) by Robert Bruce Findler 6 | - [[http://www.digitalmars.com/d/2.0/dbc.html][Contract Programming in D]] 7 | - [[http://www.ccs.neu.edu/scheme/pubs/oopsla01-ff.pdf][Contract Soundness for Object-Oriented Languages]] by Robert Bruce Findler and Matthias Felleisen 8 | - [[http://www.ccs.neu.edu/racket/pubs/NU-CCIS-02-05.pdf][Contracts for Higher-order functions]] by Robert Bruce Findler and Matthias Felleisen 9 | - [[http://pre.plt-scheme.org/docs/html/guide/contracts.html][Contracts in Racket (A Scheme Descendent)]] 10 | - [[http://onestepback.org/index.cgi/Tech/Programming/DbcAndTesting.html][Design by Contract and Unit Testing]] 11 | - [[http://split-s.blogspot.com/2006/02/design-by-contract-for-ruby.html][Design by contract for Ruby]] 12 | - [[http://www.amazon.com/dp/0132479257][Eiffel: The Language]] by Bertrand Meyer 13 | - [[http://labs.oracle.com/projects/plrg/fortress.pdf][Fortress Language Specification]] (PDF) by Guy L. Steele Jr., et al. 14 | - [[http://htdp.org/][How to Deign Programs]] by Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram Krishnamurthi [here](http://www.htdp.org/2003-09-26/Book/) 15 | - [[http://www.eecs.northwestern.edu/~robby/contract-reading-list/jass.pdf][Jass - Java with Assertions]] (PDF) by Detlef Bartetzko, Clemens Fischer, Michael Moller and Heike Wehrheim 16 | - [[http://www.amazon.com/dp/0136291554][Object-oriented Software Construction]] by Bertrand Meyer 17 | - [[http://msdn.microsoft.com/en-us/library/system.diagnostics.contracts.aspx][System.Diagnostics.Contracts]] 18 | -------------------------------------------------------------------------------- /docs/wiki/references.markdown: -------------------------------------------------------------------------------- 1 | references 2 | ========== 3 | 4 | ## 1) clojure.core.contracts references 5 | 6 | * [A Proof Engine for Eiffel]([http://tecomp.sourceforge.net/index.php?file=doc/papers/proof/engine]) 7 | * [An Axiomatic Basis for Computer Programming]([http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.116.2392]) by C.A.R Hoare -- essential reading 8 | * [Behavioral Software Contracts]([http://eecs.northwestern.edu/~robby/pubs/papers/behavioral-software-contracts.pdf]) (PDF) by Robert Bruce Findler 9 | * [Contract Programming in D]([http://www.digitalmars.com/d/2.0/dbc.html]) 10 | * [Contract Soundness for Object-Oriented Languages]([http://www.ccs.neu.edu/scheme/pubs/oopsla01-ff.pdf]) by Robert Bruce Findler and Matthias Felleisen 11 | * [Contracts for Higher-order functions]([http://www.ccs.neu.edu/racket/pubs/NU-CCIS-02-05.pdf]) by Robert Bruce Findler and Matthias Felleisen 12 | * [Contracts in Racket (A Scheme Descendent)]([http://pre.plt-scheme.org/docs/html/guide/contracts.html]) 13 | * [Design by Contract and Unit Testing]([http://onestepback.org/index.cgi/Tech/Programming/DbcAndTesting.html]) 14 | * [Design by contract for Ruby]([http://split-s.blogspot.com/2006/02/design-by-contract-for-ruby.html]) 15 | * [Eiffel: The Language]([http://www.amazon.com/dp/0132479257]) by Bertrand Meyer 16 | * [Fortress Language Specification]([http://labs.oracle.com/projects/plrg/fortress.pdf]) (PDF) by Guy L. Steele Jr., et al. 17 | * [How to Deign Programs]([http://htdp.org/]) by Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram Krishnamurthi [here]([http://www.htdp.org/2003-09-26/Book/]) 18 | * [Jass - Java with Assertions]([http://www.eecs.northwestern.edu/~robby/contract-reading-list/jass.pdf]) (PDF) by Detlef Bartetzko, Clemens Fischer, Michael Moller and Heike Wehrheim 19 | * [Object-oriented Software Construction](ttp://www.amazon.com/dp/0136291554) by Bertrand Meyer 20 | * [System.Diagnostics.Contracts]([http://msdn.microsoft.com/en-us/library/system.diagnostics.contracts.aspx]) 21 | 22 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/contracts/impl/utils.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts.impl.utils 2 | (:require [clojure.core.unify :as unify])) 3 | 4 | (defn keys-apply [f ks m] 5 | (let [only (select-keys m ks)] 6 | (zipmap (keys only) (map f (vals only))))) 7 | 8 | 9 | (defn manip-map [f ks m] 10 | (conj m (keys-apply f ks m))) 11 | 12 | 13 | (defmacro assert-w-message 14 | [check message] 15 | `(when-not ~check 16 | (throw (new AssertionError (str "Assertion failure: " ~message "\n" 17 | (pr-str '~check)))))) 18 | 19 | (defn check-args! 20 | [name slots inv-description invariants] 21 | (assert-w-message (and inv-description (string? inv-description)) 22 | (str "Expecting an invariant description for " name)) 23 | (assert-w-message (and invariants (or (map? invariants) (vector? invariants))) 24 | (str "Expecting invariants of the form " 25 | "[pre-conditions => post-conditions] or " 26 | "{:pre [pre-conditions]}" 27 | "for record type " name))) 28 | 29 | ;; Currying 30 | 31 | (defn do-curried 32 | [name doc meta args body] 33 | (let [cargs (vec (butlast args))] 34 | `(defn ~name ~doc ~meta 35 | (~cargs (fn [x#] (~name ~@cargs x#))) 36 | (~args ~@body)))) 37 | 38 | (defmacro defcurried 39 | "Builds another arity of the fn that returns a fn awaiting the last 40 | param" 41 | [name doc meta args & body] 42 | (do-curried name doc meta args body)) 43 | 44 | (defmacro defcurry-from 45 | "Builds a pass-through curried fn for each name." 46 | [namespace & names] 47 | (->> (for [n names] 48 | (let [v (ns-resolve namespace n)] 49 | `(defcurried ~n 50 | ~(str "Curried version of " v) 51 | {:clojure.core.contracts/original ~v} 52 | [l# r#] 53 | (~v l# r#)))) 54 | (cons `do))) 55 | 56 | (defn constraint? 57 | "Determines if a symbol represents a 58 | core.contracts constraint." 59 | [sym] 60 | (-> sym 61 | resolve 62 | meta 63 | :clojure.core.contracts/original 64 | boolean)) 65 | 66 | (comment 67 | (macroexpand 68 | '(defcurry-from clojure.core 69 | == =)) 70 | 71 | 72 | 73 | ((== 1) 1) 74 | 75 | (defcurried === 76 | "test" 77 | {:added "1.5"} 78 | [l r] 79 | (== l r)) 80 | 81 | ((=== 1) 2) 82 | 83 | ) 84 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/contracts.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts 2 | "The public contracts programming functions and macros for clojure.core.contracts." 3 | (:use [clojure.core.contracts.impl.transformers :only (build-contract-fn-body)]) 4 | (:require [clojure.core.contracts.impl.utils :as tools])) 5 | 6 | (defmacro contract 7 | [name docstring & constraints] 8 | (tools/assert-w-message (string? docstring) "Sorry, but contracts require docstrings") 9 | 10 | `(with-meta 11 | ~(build-contract-fn-body name docstring constraints) 12 | {:docstring ~docstring 13 | ::constraints :TBD})) 14 | 15 | (defmacro _ 16 | [a b & body] 17 | (let [name (if (symbol? a) a (gensym "hoc")) 18 | args (if (symbol? a) b a) 19 | body (if (symbol? a) body (list* b body))] 20 | `(contract ~name "TBD" ~args ~(vec body)))) 21 | 22 | (comment 23 | 24 | (def C 25 | (contract 26 | foo 27 | "bar" 28 | [f n] 29 | [(integer? n) 30 | (_ f [n] [odd?]) 31 | => 32 | integer?])) 33 | 34 | (def foo (with-constraints 35 | (fn [f n] (+ (f n) n)) 36 | C)) 37 | 38 | (foo #(* 2 %) 11) 39 | 40 | ) 41 | 42 | (defn with-constraints 43 | "A contract combinator. 44 | 45 | Takes a target function and a number of contracts and returns a function with the contracts 46 | applied to the original. This is the preferred way to apply a contract previously created 47 | using `contract` as the use of `partial` may not work as implementation details change. 48 | " 49 | ([f] f) 50 | ([f c] (partial c f)) 51 | ([f c & more] 52 | (apply with-constraints (with-constraints f c) more))) 53 | 54 | (defmacro provide 55 | "Provides the Var manipulation macro offering ex post facto application of contracts 56 | to existing functions." 57 | [& kontracts] 58 | (let [fn-names (map first kontracts) 59 | kontracts (for [[n ds & more] kontracts] 60 | (if (vector? (first more)) 61 | (list* `contract n ds more) 62 | (first more)))] 63 | `(do 64 | ~@(for [[n# c#] (zipmap fn-names kontracts)] 65 | (list `alter-var-root (list `var n#) 66 | (list `fn '[f c] (list `with-constraints 'f 'c)) c#)) 67 | nil))) 68 | 69 | (defmacro require-with-constraints 70 | [name inv-description invariants] 71 | `(do 72 | (require ~(quote name)) 73 | (set-validator! (var ~name) (partial (contract ~(symbol (str "chk-" name)) 74 | ~inv-description 75 | [~name] 76 | ~invariants) 77 | (fn [x#] true))))) 78 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | clojure.core.contracts 2 | ======================================== 3 | 4 | Contracts programming for Clojure. 5 | 6 | Project status: [Inactive](https://clojure.org/community/contrib_libs). The author (fogus) considers this library to have been superseded by [clojure.spec](https://github.com/clojure/spec.alpha). 7 | 8 | Based on [Trammel](http://github.com/fogus/trammel) and [clojure-contracts](http://github.com/dnaumov/clojure-contracts). 9 | 10 | 11 | Releases and Dependency Information 12 | ======================================== 13 | 14 | Latest stable release: 0.0.6 15 | 16 | * [All Released Versions](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22core.contracts%22) 17 | 18 | * [Development Snapshot Versions](https://oss.sonatype.org/index.html#nexus-search;gav~org.clojure~core.contracts~~~) 19 | 20 | [CLI/`deps.edn`](https://clojure.org/reference/deps_and_cli) dependency information: 21 | ```clojure 22 | org.clojure/core.contracts {:mvn/version "0.0.6"} 23 | ``` 24 | 25 | [Leiningen](https://github.com/technomancy/leiningen) dependency information: 26 | 27 | [org.clojure/core.contracts "0.0.6"] 28 | 29 | [Maven](http://maven.apache.org/) dependency information: 30 | 31 | 32 | org.clojure 33 | core.contracts 34 | 0.0.6 35 | 36 | 37 | 38 | 39 | Example Usage 40 | ======================================== 41 | 42 | ```clojure 43 | (use 'clojure.core.contracts) 44 | 45 | (def secure-doubler 46 | (with-constraints 47 | (fn [n] (* 2 n)) 48 | (contract doubler 49 | "ensures doubling" 50 | [x] [number? => (= (* 2 x) %)] 51 | [x y] [(every? number? [x y]) 52 | => 53 | (= (* 2 (+ x y)) %)]))) 54 | 55 | (secure-doubler 10) 56 | ;=> 20 57 | ``` 58 | 59 | Refer to docstrings in the `clojure.core.contracts` namespace. 60 | 61 | Documentation 62 | ======================================== 63 | 64 | [core.contracts API](http://clojure.github.io/core.contracts/) 65 | 66 | See also the [wiki](/clojure/core.contracts/wiki) for some documentation and examples. 67 | 68 | Developer Information 69 | ======================================== 70 | 71 | * [GitHub project](https://github.com/clojure/core.contracts) 72 | * [Bug Tracker](https://clojure.atlassian.net/browse/CCONTRACTS) 73 | * [Continuous Integration](https://github.com/clojure/core.contracts/actions/workflows/test.yml) 74 | * [References](https://github.com/clojure/core.contracts/blob/master/References.md) 75 | 76 | Change Log 77 | ==================== 78 | 79 | * Release 0.0.6 on 2016.08.20 80 | * Bump dependency on newest version of core.unify, which fixes a compilation problem with Clojure 1.9.0-alpha11 81 | * Release 0.0.5 on 2013.06.28 82 | * Speedier constrained record perf. 83 | * Release 0.0.4 on 2013.03.07 84 | * Rolled in `defconstrainedrecord` 85 | * Rolled in associative checks 86 | * Release 0.0.1 on 2012.06.01 87 | * Rolled in `contract`, `with-constraints` and `provide` from Trammel 88 | 89 | 90 | Copyright and License 91 | ======================================== 92 | 93 | Copyright (c) Rich Hickey, Michael Fogus and contributors, 2023. All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) which can be found in the file epl-v10.html at the root of this distribution. By using this software in any fashion, you are agreeing to be bound bythe terms of this license. You must not remove this notice, or any other, from this software. 94 | -------------------------------------------------------------------------------- /docs/contract.org: -------------------------------------------------------------------------------- 1 | * contract 2 | 3 | As you saw in the description of [[./defconstrainedfn][defconstrainedfn]] core.contracts allows you to create functions with a localized and dependent contract. However, there may be circumstances where the separation of contract and constrained function is preferred. Take for example, a simple ~slope~ function: 4 | 5 | #+begin_src clojure 6 | (defn sqr [n] (* n n)) 7 | #+end_src 8 | 9 | Defining a separate contract for this function is a simple matter: 10 | 11 | #+begin_src clojure 12 | (def sqr-contract 13 | (contract sqr-constraints 14 | "Defines the constraints for squaring" 15 | [n] [number? (not= 0 n) => pos? number?])) 16 | #+end_src 17 | 18 | We can then define a constrained version of ~sqr~ using core.contracts's [[../with-constraints/][with-constraints]] macro: 19 | 20 | #+begin_src clojure 21 | (def constrained-sqr 22 | (with-constraints 23 | sqr 24 | sqr-contract)) 25 | #+end_src 26 | 27 | And it's use is as follows: 28 | 29 | #+begin_src clojure 30 | (constrained-sqr 5) 31 | ;;=> 25 32 | 33 | (constrained-sqr -5) 34 | ;;=> 25 35 | 36 | (constrained-sqr 0) 37 | ;; java.lang.AssertionError: Assert failed: (not= 0 num) 38 | 39 | (constrained-sqr :a) 40 | ;; java.lang.AssertionError: Assert failed: (number? num) 41 | #+end_src 42 | 43 | However, this constraint definition for ~sqr~, while accurate, is very broad. In fact, the software team developing software for the 8-bit Atari console would not be able to use ~constrained-sqr~ as it is far too liberal. Therefore, they can define their own contract that further constrains ~constrained-sqr~: 44 | 45 | #+begin_src clojure 46 | (def sqr-8bit-contract 47 | (contract atari-constraints 48 | "Defines the constraints for Atari 2600 sqr" 49 | [_] [number? => (< % 256)])) 50 | 51 | (def sqr-8bit 52 | (with-constraints 53 | constrained-sqr 54 | sqr-8bit-contract)) 55 | #+end_src 56 | 57 | TODO 58 | 59 | #+begin_src clojure 60 | (sqr-8bit 5) 61 | ;;=> 25 62 | 63 | (sqr-8bit 0) 64 | ;; java.lang.AssertionError: 65 | ;; Assert failed: (not= 0 num) 66 | #+end_src 67 | 68 | And all appears to be in order -- except: 69 | 70 | #+begin_src clojure 71 | (sqr-8bit 100) 72 | ;; java.lang.AssertionError: 73 | ;; Assert failed: (< % 256) 74 | #+end_src 75 | 76 | That is, calling the function ~sqr-8bit~ with ~100~ causes a *post-condition* failure! The reason for this is because the underlying ~sqr~ is the same old arbitrary-precision version when what we really want is a function that deals in only 8-bit values. There are two possible ways to do this: 77 | 78 | 1. Create a version of ~sqr-8bit~ that does in fact deal in 8-bit values 79 | 2. Tighten the constraint on ~constrained-sqr~ further by applying another contract 80 | 81 | #+begin_src clojure 82 | (def sqr-8bit-contract 83 | (contract atari-constraints 84 | "Defines the constraints for Atari 2600 sqr" 85 | [n] [(< n 16) integer? pos? => (< % 256)])) 86 | 87 | (def sqr-8bit 88 | (with-constraints 89 | constrained-sqr 90 | sqr-8bit-contract)) 91 | 92 | (sqr-8bit 15) 93 | ;=> 225 94 | 95 | (sqr-8bit -5) 96 | ; java.lang.AssertionError: 97 | ; Assert failed: (pos? n) 98 | 99 | (sqr-8bit 15.9687194) 100 | ; java.lang.AssertionError: 101 | ; Assert failed: (integer? n) 102 | 103 | (sqr-8bit 16) 104 | ; java.lang.AssertionError: 105 | ; Assert failed: (< n 16) 106 | #+end_src 107 | 108 | Using ~contract~ and ~with-constraints~ you were able to tighten the constraints on both the pre- and post-conditions of the ~sqr~ function. However, what if you wanted to relax the requirements? Stay tuned. 109 | 110 | [[../docs.html][return to documentation]] 111 | 112 | -------------------------------------------------------------------------------- /docs/styles/default.css: -------------------------------------------------------------------------------- 1 | a{text-decoration:none;color:#ddaba6;} 2 | body{background-color:#FFF;color:#222;padding-bottom:30px;} 3 | code{background-color:#f0f0f8; border: 1px solid #DEDEDE;} 4 | .citation{color:#8EA1C0;font-style:italic;text-align:center;} 5 | .description{color:#A3A3A3;font-style:italic;text-align:center;margin-bottom:2em;} 6 | .item .citation a{text-decoration:none;color:#A3A3A3;} 7 | .log{line-height:1.7em;width:400px;font-size:12px;font-family:"lucida grande", verdana;vertical-align:middle;text-align:left;margin:0 auto;} 8 | h3{text-transform:uppercase;margin-bottom:.3em;font-size:1em;text-align:center;letter-spacing:.2em;color:#a53307;} 9 | h5{text-transform:uppercase;margin-bottom:.3em;font-size:1em;text-align:center;color:#a53307;text-weight:bold;} 10 | h4{letter-spacing:.1em;color:#A3A3A3;margin-top:0;text-align:center;font-weight:400;font-style:italic;} 11 | .item h4 a{color:#ebdcdc;text-decoration:none;} 12 | .even{background-color:#f5f5f5;padding:5px;} 13 | .odd{padding:5px;} 14 | #rinich{text-align:center;} 15 | .item .more{line-height:1.7em;letter-spacing:.2em;font-size:.8em;float:right;font-weight:700;text-transform:uppercase;background-color:#a53307;color:#FFF;-moz-border-radius-topleft:15px;-webkit-border-top-left-radius:15px;text-decoration:none;position:relative;left:10px;opacity:0;-webkit-transition:all .15s;padding:5px 10px;} 16 | .item{margin-bottom:20px;border-color:#ffebf1;border-style:solid;border-width:1px;padding:20px 20px 36px;} 17 | .item a{color:#510000;text-decoration:underline;} 18 | .item a:active{color:#a53307;} 19 | h1{letter-spacing:.03em;text-transform:uppercase;margin-top:1em;font-size:4em;text-align:center;font-family:"League Gothic";margin-bottom:.4em;} 20 | h1 a{color:#444;} 21 | img{text-align:center;width:358px;position:relative;top:-10px;} 22 | .video{text-align:center;position:relative;left:-21px;} 23 | .audio{position:relative;left:70px;width:210px;text-align:center;border-color:#eee;border-style:solid;border-width:1px;padding:5px;} 24 | .back{font-weight:700;letter-spacing:.2em;color:#FFF;background-color:#a53307;float:left;display:block;text-align:center;text-transform:lowercase;width:174px;margin:-10px 5px 20px 11px;padding:5px;} 25 | .forward{font-weight:700;letter-spacing:.2em;color:#FFF;background-color:#a53307;float:right;display:block;text-align:center;text-transform:uppercase;width:174px;margin:-10px 11px 20px 5px;padding:5px;} 26 | .button{font-weight:700;letter-spacing:.2em;color:#FFF;background-color:#ddaba6;float:right;display:block;text-align:center;text-transform:lowercase;width:368px;margin:5px 11px;padding:5px;} 27 | .footer{margin-top:169px;color:#ccc;text-align:center;border-color:#ffebf1;border-style:solid;border-width:1px;padding:5px;} 28 | .footer a{color:#ccc;font-weight:700;} 29 | .item:hover .more{opacity:1.0;} 30 | .search{font-size:12px;font-weight:700;letter-spacing:.2em;color:#FFF;background-color:#ddaba6;float:right;display:block;text-align:center;text-transform:uppercase;width:368px;border-style:none;margin:-10px 11px 5px;padding:7px 5px;} 31 | input.search::-webkit-input-placeholder{color:#FFF;} 32 | .search:focus{letter-spacing:0;text-transform:none;background-color:#FFF;color:#ddaba6;outline:none;border-color:#ddaba6;border-style:solid;border-width:3px;padding:4px 2px;} 33 | .tagspace{float:left;margin-left:410px;} 34 | .tag{line-height:1.7em;letter-spacing:.2em;font-size:.8em;font-weight:700;text-transform:uppercase;background-color:#ddaba6;color:#FFF;text-decoration:none;text-align:center;margin-bottom:10px;display:block;padding:5px 10px;} 35 | .spacer{margin-top:-610px;} 36 | ol.notes{color:#c3c3c3;list-style-type:none;border-bottom:solid 1px #ffebf1;margin:50px 0;padding:0;} 37 | ol.notes li.note{color:#c3c3c3;border-top:solid 1px #ffebf1;padding:10px;} 38 | ol.notes li.notes a{color:#ddaba6;} 39 | ol.notes li.note blockquote{border-color:#ffebf1;margin:10px 0 0 25px;padding:4px 10px;} 40 | ol.notes li.note blockquote a{text-decoration:none;} 41 | .src {border:1px solid #e3a5b1;font-family:Monaco, "Courier New", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", monospace;margin-bottom:1em; font-size:100%} 42 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/contracts/impl/transformers.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts.impl.transformers 2 | (:require [clojure.core.contracts.impl.funcify :as funcification]) 3 | (:require [clojure.core.unify :as unify] 4 | [clojure.core.contracts.impl.utils :as utils])) 5 | 6 | 7 | (defn- divide-pre-post 8 | "'[odd? pos? => int?] 9 | => 10 | {:pre (odd? pos?) :post (int?)} 11 | " 12 | [cnstr] 13 | (if (vector? cnstr) 14 | (let [[L M R] (partition-by #{'=>} cnstr)] 15 | {:pre (when (not= L '(=>)) L) 16 | :post (if (= L '(=>)) M R)}) 17 | cnstr)) 18 | 19 | ;; HoC support 20 | 21 | (declare build-constraints-description 22 | build-contract-body) 23 | 24 | (defrecord Hoc [field desc]) 25 | 26 | (defmethod funcification/funcify* Hoc [e args] e) 27 | 28 | (def hoc? #(= Hoc (type %))) 29 | 30 | (defn- tag-hocs 31 | [cnstr] 32 | (let [ret 33 | (mapcat (fn [form] 34 | (if (and (seq? form) (= '_ (first form))) 35 | [(list 'fn? (second form)) 36 | (Hoc. (second form) 37 | (apply build-constraints-description (-> form nnext vec (conj "foo"))))] 38 | [form])) 39 | cnstr)] 40 | ret)) 41 | 42 | (defn- build-constraints-description 43 | "'[n] '[odd? pos? => int?] \"foo\" 44 | => 45 | [[n] {:pre [(pos? n) (int? n)], :post [(neg? %)]} \"foo\"]" 46 | [args cnstr docstring] 47 | (let [cnstr (vec (tag-hocs cnstr))] 48 | [args 49 | (->> (divide-pre-post cnstr) 50 | (utils/manip-map (partial funcification/funcify '[%]) [:post]) 51 | (utils/manip-map (partial funcification/funcify args) [:pre])) 52 | docstring])) 53 | 54 | (defn- build-condition-body 55 | [constraint-map body prefix-msg] 56 | (unify/subst 57 | '(try 58 | ((fn [] 59 | ?CNSTR 60 | ?BODY)) 61 | (catch AssertionError ae 62 | (throw (AssertionError. (str ?PREFIX ?MSG \newline (.getMessage ae)))))) 63 | 64 | {'?CNSTR constraint-map 65 | '?PREFIX prefix-msg 66 | '?BODY body})) 67 | 68 | (comment 69 | 70 | (build-contract-body 71 | (build-constraints-description '[f n] '[number? (_ f [n] [odd?]) => pos?] "foo")) 72 | 73 | (build-contract-body 74 | (build-constraints-description '[n] '[number? => odd?] "foo")) 75 | 76 | 77 | (prepare-args '[f b c] '{f {:desc [[n] {:pre [(odd? n)], :post []} "bar"]}}) 78 | ) 79 | 80 | (defn prepare-args [args hocs] 81 | (let [vargs? #{'&} 82 | has-vargs (boolean (some vargs? args))] 83 | (with-meta 84 | (vec 85 | (map (fn [arg] 86 | (if-let [hoc (get hocs arg)] 87 | (list `partial (list* `fn (build-contract-body (:desc hoc))) arg) 88 | (if (map? arg) 89 | (:as arg) 90 | arg))) 91 | (->> args (remove vargs?)))) 92 | {::vargs has-vargs}))) 93 | 94 | (defn- build-contract-body 95 | [[args cnstr descr :as V]] 96 | (let [vargs? #{'&} 97 | fun-name (gensym "fun") 98 | hocs (apply merge (map #(hash-map (:field %) %) 99 | (filter hoc? (concat (:pre cnstr) (:post cnstr))))) 100 | cnstr {:pre (vec (filter (complement hoc?) (:pre cnstr))) 101 | :post (vec (filter (complement hoc?) (:post cnstr)))} 102 | prep-args (prepare-args args hocs) 103 | callsite (if (::vargs (meta prep-args)) 104 | (list* `apply '?F prep-args) 105 | '(apply ?F ?ARGS))] 106 | (unify/subst 107 | '(?PARMS 108 | (let [ret ?PRE-CHECK] 109 | ?POST-CHECK)) 110 | 111 | {'?ARGS prep-args 112 | '?F fun-name 113 | '?PARMS (vec (list* fun-name args)) 114 | '?MSG descr 115 | '?PRE-CHECK (build-condition-body 116 | {:pre (:pre cnstr)} 117 | callsite 118 | "Pre-condition failure: ") 119 | '?POST-CHECK (build-condition-body 120 | {:post (:post cnstr)} 121 | 'ret 122 | "Post-condition failure: ")}))) 123 | 124 | (defn- build-contract-bodies 125 | [constraint-descriptions] 126 | (for [cnstr constraint-descriptions] 127 | (build-contract-body cnstr))) 128 | 129 | ;; # Public API 130 | 131 | (defn build-contract-fn-body 132 | [name docstring raw-constraints] 133 | (let [raw-cnstr (partition 2 raw-constraints) 134 | cnstr-descrs (for [[a c] raw-cnstr] 135 | (build-constraints-description a c docstring))] ;; needs work 136 | (->> cnstr-descrs 137 | build-contract-bodies 138 | (list* `fn name)))) 139 | -------------------------------------------------------------------------------- /docs/wiki/provide.markdown: -------------------------------------------------------------------------------- 1 | provide 2 | ======= 3 | 4 | While defining contracts local to the constrained function is nice 5 | (see [defconstrainedfn] for more information), very often you will find 6 | yourself in possession of an existing function that is not 7 | constrained: 8 |
9 |
10 |
11 |
12 | 
(sqr 0)
;=> 0
16 |
17 |
18 |
19 |
20 | In this case, core.contracts provides the provide-contracts macro to 21 | define contracts and apply them dynamically to existing functions: 22 |
23 |
24 |
25 |
26 | 
(provide-contracts 
  [sqr "Constraints for
 30 |   squaring" 
    [x] [number? (not= 0 x)
 36 |   => number? pos?]])

(sqr 0)
; java.lang.AssertionError:
 42 |   
;   Assert
 43 |   failed: (not= 0 n)
44 |
45 |
46 |
47 |
48 | As shown, the sqr function is dynamically modified with the contract 49 | defined in the body of provide-contracts. This macro can take any 50 | number of vectors where each corresponds to a contract for a given 51 | function; including multiple arities embedded within. core.contracts 52 | also allows you to include existing named contracts (see [defcontract] 53 | for more information) instead of the contract specification vector, as 54 | shown below: 55 |
56 |
57 |
58 |
59 | 
(defcontract sqr-contract
  "Defines the constraints on
 63 |   squaring."
  [n]
 65 |   [number? (not= 0 n)
 68 |   => pos? number?])

(sqr 0)
;=> 0

(provide-contracts
  [sqr "Apply the contract for
 78 |   squaring" 
       sqr-contract])

(sqr 0)
; java.lang.AssertionError:
 85 |   
;   Assert
 86 |   failed: (not= 0 n)
87 |
88 |
89 |
90 |
91 | provide-contracts gives you a lot of flexibilty in how to separate 92 | functions from their contracts and likewise apply them in 93 | domain-specific ways. 94 | [return to documentation] 95 | 96 | [defconstrainedfn]: ../defconstrainedfn/ 97 | [defcontract]: ./defcontract/ 98 | [return to documentation]: ../docs.html 99 | 100 | -------------------------------------------------------------------------------- /src/test/clojure/clojure/core/contracts_tests.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts-tests 2 | (:use [clojure.test :only [deftest is]] 3 | clojure.core.contracts.impl.transformers 4 | clojure.core.contracts)) 5 | 6 | (defn defer [desc] 7 | (is (nil? (println (str "DEFERING TEST: " desc))))) 8 | 9 | 10 | (deftest test-simple-contract 11 | (let [doubler-contract (contract doubler 12 | "ensures dublig" 13 | [x] [number? => (= (* 2 x) %)] 14 | [x y] [(every? number? [x y]) 15 | => 16 | (= (* 2 (+ x y)) %)]) 17 | 18 | x2 (fn f 19 | ([n] (* 2 n)) 20 | ([n x] (+ (f n) (f x)))) 21 | 22 | good-doubler (partial doubler-contract x2) 23 | bad-doubler (partial doubler-contract (comp dec x2))] 24 | 25 | (is (= 4 (good-doubler 2))) 26 | (is (= 10 (good-doubler 2 3))) 27 | (is (thrown? AssertionError (bad-doubler 2))) 28 | (is (thrown? AssertionError (bad-doubler 2 3))))) 29 | 30 | (deftest test-full-contract-on-isolated-fn 31 | (let [doubler-contract-full-and-isolated-fn 32 | (contract doubler 33 | "Test" 34 | [x] [pos? => (= (* 2 x) %)] 35 | [x y] [(pos? x) (pos? y) => (= (* 2 (+ x y)) %)])] 36 | 37 | (is (= 10 ((partial doubler-contract-full-and-isolated-fn #(* 2 (+ %1 %2))) 2 3))) 38 | (is (= 10 ((partial doubler-contract-full-and-isolated-fn #(+ %1 %1 %2 %2)) 2 3))) 39 | (is (= 10 ((partial doubler-contract-full-and-isolated-fn #(* 2 %)) 5))) 40 | (is (thrown? Error ((partial doubler-contract-full-and-isolated-fn #(* 3 (+ %1 %2))) 2 3))))) 41 | 42 | (deftest test-contract-arity1 43 | (let [doubler-contract-arity1 44 | (contract doubler 45 | "Test" 46 | [x] [(pos? x) => (= (* 2 x) %)])] 47 | 48 | (is (= 10 ((partial doubler-contract-arity1 #(* 2 %)) 5))) 49 | (is (= 10 ((partial doubler-contract-arity1 #(* 2 %)) 5))) 50 | (is (thrown? Error ((partial doubler-contract-arity1 #(* 3 %)) 5))) 51 | (is (thrown? Error ((partial doubler-contract-arity1 #(* 2 %)) -5))))) 52 | 53 | (deftest test-contract-arity1-and-isolated-fn 54 | (let [doubler-contract-arity1-and-isolated-fn 55 | (contract doubler 56 | "Test" 57 | [x] [pos? => (= (* 2 x) %)])] 58 | 59 | (is (= 10 ((partial doubler-contract-arity1-and-isolated-fn #(* 2 %)) 5))) 60 | (is (= 10 ((partial doubler-contract-arity1-and-isolated-fn #(* 2 %)) 5))) 61 | (is (thrown? Error ((partial doubler-contract-arity1-and-isolated-fn #(* 3 %)) 5))) 62 | (is (thrown? Error ((partial doubler-contract-arity1-and-isolated-fn #(* 2 %)) -5))))) 63 | 64 | (deftest test-partial-contract-no-requires 65 | (let [doubler-contract-no-requires 66 | (contract doubler 67 | "Test" 68 | [x] [=> (= (* 2 x) %)])] 69 | 70 | (is (= 10 ((partial doubler-contract-no-requires #(* 2 %)) 5))) 71 | (is (= -10 ((partial doubler-contract-no-requires #(* 2 %)) -5))) 72 | (is (thrown? Error ((partial doubler-contract-no-requires #(* 3 %)) 5))))) 73 | 74 | (deftest test-partial-contract-no-requires-and-isolated-fn 75 | (let [doubler-contract-no-requires-and-isolated-fn 76 | (contract doubler 77 | "Test" 78 | [x] [=> pos? (= (* 2 x) %)])] 79 | 80 | (is (= 10 ((partial doubler-contract-no-requires-and-isolated-fn #(* 2 %)) 5))) 81 | (is (thrown? Error ((partial doubler-contract-no-requires-and-isolated-fn #(* 2 %)) -5))) 82 | (is (thrown? Error ((partial doubler-contract-no-requires-and-isolated-fn #(* 3 %)) 5))))) 83 | 84 | (deftest test-partial-contract-no-ensures 85 | (let [doubler-contract-no-ensures 86 | (contract doubler 87 | "Test" 88 | [x] [(pos? x)])] 89 | 90 | (is (= 10 ((partial doubler-contract-no-ensures #(* 2 %)) 5))) 91 | (is (= 15 ((partial doubler-contract-no-ensures #(* 3 %)) 5))) 92 | (is (thrown? Error ((partial doubler-contract-no-ensures #(* 2 %)) -5))))) 93 | 94 | (deftest test-partial-contract-no-ensures-and-isolated-fn 95 | (let [doubler-contract-no-ensures-and-isolated-fn 96 | (contract doubler 97 | "Test" 98 | [x] [pos?])] 99 | 100 | (is (= 10 ((partial doubler-contract-no-ensures-and-isolated-fn #(* 2 %)) 5))) 101 | (is (= 15 ((partial doubler-contract-no-ensures-and-isolated-fn #(* 3 %)) 5))) 102 | (is (thrown? Error ((partial doubler-contract-no-ensures-and-isolated-fn #(* 2 %)) -5))))) 103 | 104 | #_(deftest test-map-version-of-contract 105 | (let [doubler-contract-full-mappy 106 | (contract doubler 107 | "Test" 108 | [x] {:pre [(pos? x)] 109 | :post [(= (* 2 x) %)]} 110 | [x y] {:pre [(pos? x) (pos? y)] 111 | :post [(= (* 2 (+ x y)) %)]})] 112 | 113 | (is (= 10 ((partial doubler-contract-full-mappy #(* 2 (+ %1 %2))) 2 3))) 114 | (is (= 10 ((partial doubler-contract-full-mappy #(+ %1 %1 %2 %2)) 2 3))) 115 | (is (= 10 ((partial doubler-contract-full-mappy #(* 2 %)) 5))) 116 | (is (thrown? Error ((partial doubler-contract-full-mappy #(* 3 (+ %1 %2))) 2 3))))) 117 | 118 | (deftest test-regressions 119 | (defer "regression testing")) 120 | -------------------------------------------------------------------------------- /src/main/clojure/clojure/core/contracts/constraints.clj: -------------------------------------------------------------------------------- 1 | (ns clojure.core.contracts.constraints 2 | (:refer-clojure :exclude [== = not=]) 3 | (:use [clojure.core.contracts.impl.utils :only (defcurry-from)]) 4 | (:require [clojure.set :as set] 5 | clojure.core.contracts 6 | clojure.core.contracts.impl.transformers)) 7 | 8 | ;; # constraint functions and multimethods 9 | 10 | (def all-numbers? #(boolean (every? number? %&))) 11 | (def all-positive? #(boolean (and (apply all-numbers? %&) (every? pos? %&)))) 12 | (def all-negative? #(boolean (and (apply all-numbers? %&) (every? (complement pos?) %&)))) 13 | (defn anything [& _] true) 14 | 15 | (defn in 16 | "Takes an item and determines if it falls in the listed args. This can be 17 | used most effectively for numbers since any numbers in a vector represent 18 | a range of values determined by the same arguments as given to `range`." 19 | [e & args] 20 | (boolean 21 | (some #{e} 22 | (mapcat #(if (vector? %) 23 | (apply range %) 24 | [%]) 25 | args)))) 26 | 27 | (def truthy #(when % true)) 28 | (def falsey #(not (truthy %))) 29 | 30 | (defn whitelist 31 | "Takes a thing with keys (i.e. maps or sets) and checks if it contains only 32 | the keys listed in the given whitelist." 33 | [wl things] 34 | (set/subset? (set (keys things)) 35 | (set wl))) 36 | 37 | (defn implies 38 | "Logical implication" 39 | [p q] 40 | (or (not p) q)) 41 | 42 | (defn <- 43 | "Converse implication" 44 | [p q] 45 | (implies q p)) 46 | 47 | (defn except 48 | "P except Q" 49 | [p q] 50 | (not (implies p q))) 51 | 52 | (defn <=> 53 | "Logical equality" 54 | [p q] 55 | (and (implies p q) 56 | (<- p q))) 57 | 58 | (defn xor 59 | "Exclusive or" 60 | [p q] 61 | (not (<=> p q))) 62 | 63 | 64 | (defcurry-from clojure.core 65 | == = not=) 66 | 67 | (comment 68 | 69 | (defn sqr [n] (* n n)) 70 | 71 | (def sqr_ (with-constraints 72 | sqr 73 | #(not= 0 %))) 74 | 75 | (sqr_ 100) 76 | (sqr_ 0) 77 | ) 78 | 79 | (defmacro defconstrainedfn 80 | "Defines a function using the `contract` vector appearing after the arguments. 81 | 82 | (defconstrainedfn sqr 83 | [n] [number? (not= 0 n) => pos? number?] 84 | (* n n)) 85 | 86 | Like the `contract` macro, multiple arity functions can be defined where each argument vector 87 | is immediately followed by the relevent arity expectations. This macro will also detect 88 | if a map is in that constraints position and use that instead under the assumption that 89 | Clojure's `:pre`/`:post` map is used instead. 90 | " 91 | [name & body] 92 | (let [mdata (if (string? (first body)) 93 | {:doc (first body)} 94 | {}) 95 | body (if (:doc mdata) 96 | (next body) 97 | body) 98 | body (if (vector? (first body)) 99 | (list body) 100 | body) 101 | body (for [[args cnstr & bd] body] 102 | (list* args 103 | (if (vector? cnstr) 104 | (second (#'clojure.core.contracts.impl.transformers/build-constraints-description args cnstr (:doc mdata))) 105 | cnstr) 106 | bd))] 107 | `(defn ~name 108 | ~(str (:doc mdata)) 109 | ~@body))) 110 | 111 | (defn- build-positional-factory 112 | "Used to build a positional factory for a given type/record. Because of the 113 | limitation of 20 arguments to Clojure functions, this factory needs to be 114 | constructed to deal with more arguments. It does this by building a straight 115 | forward type/record ctor call in the <=20 case, and a call to the same 116 | ctor pulling the extra args out of the & overage parameter. Finally, the 117 | arity is constrained to the number of expected fields and an ArityException 118 | will be thrown at runtime if the actual arg count does not match." 119 | [nom classname fields invariants chk] 120 | (let [fn-name (symbol (str '-> nom)) 121 | [field-args over] (split-at 20 fields) 122 | field-count (count fields) 123 | arg-count (count field-args) 124 | over-count (count over)] 125 | `(defconstrainedfn ~fn-name 126 | [~@field-args ~@(if (seq over) '[& overage] [])] 127 | ~invariants 128 | (with-meta 129 | ~(if (seq over) 130 | `(if (= (count ~'overage) ~over-count) 131 | (new ~nom 132 | ~@field-args 133 | ~@(for [i (range 0 (count over))] 134 | (list `nth 'overage i))) 135 | (throw (clojure.lang.ArityException. (+ ~arg-count (count ~'overage)) (name '~fn-name)))) 136 | `(new ~nom ~@field-args)) 137 | {:contract ~chk})))) 138 | 139 | (defmacro defconstrainedrecord 140 | [name slots inv-description invariants & etc] 141 | (let [fields (vec slots) 142 | ns-part (namespace-munge *ns*) 143 | classname (symbol (str ns-part "." name)) 144 | ctor-name (symbol (str name \.)) 145 | positional-factory-name (symbol (str "->" name)) 146 | map-arrow-factory-name (symbol (str "map->" name)) 147 | pred-arg (gensym) 148 | chk `(clojure.core.contracts/contract 149 | ~(symbol (str "chk-" name)) 150 | ~inv-description 151 | [{:keys ~fields :as m#}] 152 | ~invariants)] 153 | `(do 154 | (defrecord ~name ~fields ~@etc) 155 | (defn ~(symbol (str name \?)) [~pred-arg] 156 | (instance? ~name ~pred-arg)) 157 | 158 | ~(build-positional-factory name classname fields invariants chk) 159 | 160 | (defconstrainedfn ~map-arrow-factory-name 161 | ([{:keys ~fields :as m#}] 162 | ~invariants 163 | (with-meta 164 | (merge (new ~name ~@(for [e fields] nil)) m#) 165 | {:contract ~chk}))) 166 | ~name))) 167 | 168 | (defn- apply-contract 169 | [f] 170 | (if (:hooked (meta f)) 171 | f 172 | (with-meta 173 | (fn [& [m & args]] 174 | (if-let [contract (and m (-> m meta :contract))] 175 | ((partial contract identity) (apply f m args)) 176 | (apply f m args))) 177 | {:hooked true 178 | :original f}))) 179 | 180 | (when *assert* 181 | (alter-var-root (var assoc) apply-contract) 182 | (alter-var-root (var dissoc) apply-contract) 183 | (alter-var-root (var merge) apply-contract) 184 | (alter-var-root (var merge-with) (fn [f] (let [mw (apply-contract f)] (fn [f & maps] (apply mw f maps))))) 185 | (alter-var-root (var into) apply-contract) 186 | (alter-var-root (var conj) apply-contract) 187 | (alter-var-root (var assoc-in) apply-contract) 188 | (alter-var-root (var update-in) apply-contract)) 189 | -------------------------------------------------------------------------------- /docs/wiki/contract.markdown: -------------------------------------------------------------------------------- 1 | contract 2 | ======== 3 | 4 | As you saw in the description of [defconstrainedfn] core.contracts 5 | allows you to create functions with a localized and dependent 6 | contract. However, there may be circumstances where the separation of 7 | contract and constrained function is preferred. Take for example, a 8 | simple slope function: 9 |
10 |
11 |
12 |
13 | 
(defn sqr [n]
 16 |   (* n n))
19 |
20 |
21 |
22 |
23 | Defining a separate contract for this function is a simple matter: 24 |
25 |
26 |
27 |
28 | 
(def sqr-contract
  (contract sqr-constraints
    "Defines the
 34 |   constraints for squaring"
    [n] [number? (not= 0 n)
 40 |   => pos? number?]))
42 |
43 |
44 |
45 |
46 | We can then define a constrained version of sqr using 47 | core.contracts's [with-constraints] macro: 48 |
49 |
50 |
51 |
52 | 
(def constrained-sqr
 54 |   
  (with-constraints
    sqr
    sqr-contract))

(constrained-sqr 5)
;=> 25

(constrained-sqr -5)
;=> 25

(constrained-sqr 0)
; java.lang.AssertionError: Assert failed:
 72 |   
    (not= 0 num)

(constrained-sqr :a)
; java.lang.AssertionError: Assert failed:
 77 |   
    (number? num)
78 |
79 |
80 |
81 |
82 | However, this constraint definition for sqr, while accurate, is very 83 | broad. In fact, the software team developing software for the 8-bit 84 | Atari console would not be able to use constrained-sqr as it is far 85 | too liberal. Therefore, they can define their own contract that 86 | further constrains constrained-sqr: 87 |
88 |
89 |
90 |
91 | 
(def sqr-8bit-contract
  (contract atari-constraints
    "Defines the
 98 |   constraints for Atari 2600 sqr"
    [_] [number? => (<
103 |   % 256)]))

(def
106 |   sqr-8bit
  (with-constraints
    constrained-sqr 
    sqr-8bit-contract))

(sqr-8bit 5)
;=> 25

(sqr-8bit 0)
; java.lang.AssertionError:
121 |   
;   Assert
122 |   failed: (not= 0 num)
123 |
124 |
125 |
126 |
127 | And all appears to be in order -- except: 128 |
129 |
130 |
131 |
132 | 
(sqr-8bit 100)
;
135 |   java.lang.AssertionError:
;   Assert failed: (< % 256)
137 |
138 |
139 |
140 |
141 | That is, calling the function sqr-8bit with 100 causes a 142 | post-condition failure! The reason for this is because the 143 | underlying sqr is the same old arbitrary-precision version when what 144 | we really want is a function that deals in only 8-bit values. There 145 | are two possible ways to do this: 146 | 1. Create a version of sqr-8bit that does in fact deal in 8-bit 147 | values 148 | 2. Tighten the constraint on constrained-sqr further by applying 149 | another contract 150 |
151 |
152 |
153 |
154 | 
(def sqr-8bit-contract
  (contract atari-constraints
    "Defines the
161 |   constraints for Atari 2600 sqr"
    [n] [(< n 16)
166 |   integer? pos? => (<
168 |   % 256)]))

(def
171 |   sqr-8bit
  (with-constraints
    constrained-sqr 
    sqr-8bit-contract))

(sqr-8bit 15)
;=> 225

(sqr-8bit -5)
; java.lang.AssertionError:
186 |   
;   Assert
187 |   failed: (pos? n)

(sqr-8bit 15.9687194)
; java.lang.AssertionError:
192 |   
;   Assert
193 |   failed: (integer? n)

(sqr-8bit 16)
; java.lang.AssertionError:
198 |   
;   Assert
199 |   failed: (< n 16)
200 |
201 |
202 |
203 |
204 | Using contract and with-constraints you were able to tighten the 205 | constraints on both the pre- and post-conditions of the sqr 206 | function. However, what if you wanted to relax the requirements? 207 | Stay tuned. 208 | [return to documentation] 209 | 210 | [defconstrainedfn]: ./defconstrainedfn 211 | [with-constraints]: ../with-constraints/ 212 | [return to documentation]: ../docs.html 213 | 214 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Eclipse Public License - v 1.0 2 | 3 | THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC 4 | LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM 5 | CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 6 | 7 | 1. DEFINITIONS 8 | 9 | "Contribution" means: 10 | 11 | a) in the case of the initial Contributor, the initial code and documentation 12 | distributed under this Agreement, and 13 | b) in the case of each subsequent Contributor: 14 | i) changes to the Program, and 15 | ii) additions to the Program; 16 | 17 | where such changes and/or additions to the Program originate from and are 18 | distributed by that particular Contributor. A Contribution 'originates' 19 | from a Contributor if it was added to the Program by such Contributor 20 | itself or anyone acting on such Contributor's behalf. Contributions do not 21 | include additions to the Program which: (i) are separate modules of 22 | software distributed in conjunction with the Program under their own 23 | license agreement, and (ii) are not derivative works of the Program. 24 | 25 | "Contributor" means any person or entity that distributes the Program. 26 | 27 | "Licensed Patents" mean patent claims licensable by a Contributor which are 28 | necessarily infringed by the use or sale of its Contribution alone or when 29 | combined with the Program. 30 | 31 | "Program" means the Contributions distributed in accordance with this 32 | Agreement. 33 | 34 | "Recipient" means anyone who receives the Program under this Agreement, 35 | including all Contributors. 36 | 37 | 2. GRANT OF RIGHTS 38 | a) Subject to the terms of this Agreement, each Contributor hereby grants 39 | Recipient a non-exclusive, worldwide, royalty-free copyright license to 40 | reproduce, prepare derivative works of, publicly display, publicly 41 | perform, distribute and sublicense the Contribution of such Contributor, 42 | if any, and such derivative works, in source code and object code form. 43 | b) Subject to the terms of this Agreement, each Contributor hereby grants 44 | Recipient a non-exclusive, worldwide, royalty-free patent license under 45 | Licensed Patents to make, use, sell, offer to sell, import and otherwise 46 | transfer the Contribution of such Contributor, if any, in source code and 47 | object code form. This patent license shall apply to the combination of 48 | the Contribution and the Program if, at the time the Contribution is 49 | added by the Contributor, such addition of the Contribution causes such 50 | combination to be covered by the Licensed Patents. The patent license 51 | shall not apply to any other combinations which include the Contribution. 52 | No hardware per se is licensed hereunder. 53 | c) Recipient understands that although each Contributor grants the licenses 54 | to its Contributions set forth herein, no assurances are provided by any 55 | Contributor that the Program does not infringe the patent or other 56 | intellectual property rights of any other entity. Each Contributor 57 | disclaims any liability to Recipient for claims brought by any other 58 | entity based on infringement of intellectual property rights or 59 | otherwise. As a condition to exercising the rights and licenses granted 60 | hereunder, each Recipient hereby assumes sole responsibility to secure 61 | any other intellectual property rights needed, if any. For example, if a 62 | third party patent license is required to allow Recipient to distribute 63 | the Program, it is Recipient's responsibility to acquire that license 64 | before distributing the Program. 65 | d) Each Contributor represents that to its knowledge it has sufficient 66 | copyright rights in its Contribution, if any, to grant the copyright 67 | license set forth in this Agreement. 68 | 69 | 3. REQUIREMENTS 70 | 71 | A Contributor may choose to distribute the Program in object code form under 72 | its own license agreement, provided that: 73 | 74 | a) it complies with the terms and conditions of this Agreement; and 75 | b) its license agreement: 76 | i) effectively disclaims on behalf of all Contributors all warranties 77 | and conditions, express and implied, including warranties or 78 | conditions of title and non-infringement, and implied warranties or 79 | conditions of merchantability and fitness for a particular purpose; 80 | ii) effectively excludes on behalf of all Contributors all liability for 81 | damages, including direct, indirect, special, incidental and 82 | consequential damages, such as lost profits; 83 | iii) states that any provisions which differ from this Agreement are 84 | offered by that Contributor alone and not by any other party; and 85 | iv) states that source code for the Program is available from such 86 | Contributor, and informs licensees how to obtain it in a reasonable 87 | manner on or through a medium customarily used for software exchange. 88 | 89 | When the Program is made available in source code form: 90 | 91 | a) it must be made available under this Agreement; and 92 | b) a copy of this Agreement must be included with each copy of the Program. 93 | Contributors may not remove or alter any copyright notices contained 94 | within the Program. 95 | 96 | Each Contributor must identify itself as the originator of its Contribution, 97 | if 98 | any, in a manner that reasonably allows subsequent Recipients to identify the 99 | originator of the Contribution. 100 | 101 | 4. COMMERCIAL DISTRIBUTION 102 | 103 | Commercial distributors of software may accept certain responsibilities with 104 | respect to end users, business partners and the like. While this license is 105 | intended to facilitate the commercial use of the Program, the Contributor who 106 | includes the Program in a commercial product offering should do so in a manner 107 | which does not create potential liability for other Contributors. Therefore, 108 | if a Contributor includes the Program in a commercial product offering, such 109 | Contributor ("Commercial Contributor") hereby agrees to defend and indemnify 110 | every other Contributor ("Indemnified Contributor") against any losses, 111 | damages and costs (collectively "Losses") arising from claims, lawsuits and 112 | other legal actions brought by a third party against the Indemnified 113 | Contributor to the extent caused by the acts or omissions of such Commercial 114 | Contributor in connection with its distribution of the Program in a commercial 115 | product offering. The obligations in this section do not apply to any claims 116 | or Losses relating to any actual or alleged intellectual property 117 | infringement. In order to qualify, an Indemnified Contributor must: 118 | a) promptly notify the Commercial Contributor in writing of such claim, and 119 | b) allow the Commercial Contributor to control, and cooperate with the 120 | Commercial Contributor in, the defense and any related settlement 121 | negotiations. The Indemnified Contributor may participate in any such claim at 122 | its own expense. 123 | 124 | For example, a Contributor might include the Program in a commercial product 125 | offering, Product X. That Contributor is then a Commercial Contributor. If 126 | that Commercial Contributor then makes performance claims, or offers 127 | warranties related to Product X, those performance claims and warranties are 128 | such Commercial Contributor's responsibility alone. Under this section, the 129 | Commercial Contributor would have to defend claims against the other 130 | Contributors related to those performance claims and warranties, and if a 131 | court requires any other Contributor to pay any damages as a result, the 132 | Commercial Contributor must pay those damages. 133 | 134 | 5. NO WARRANTY 135 | 136 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN 137 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR 138 | IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, 139 | NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each 140 | Recipient is solely responsible for determining the appropriateness of using 141 | and distributing the Program and assumes all risks associated with its 142 | exercise of rights under this Agreement , including but not limited to the 143 | risks and costs of program errors, compliance with applicable laws, damage to 144 | or loss of data, programs or equipment, and unavailability or interruption of 145 | operations. 146 | 147 | 6. DISCLAIMER OF LIABILITY 148 | 149 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 150 | CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 151 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION 152 | LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 153 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 154 | ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE 155 | EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY 156 | OF SUCH DAMAGES. 157 | 158 | 7. GENERAL 159 | 160 | If any provision of this Agreement is invalid or unenforceable under 161 | applicable law, it shall not affect the validity or enforceability of the 162 | remainder of the terms of this Agreement, and without further action by the 163 | parties hereto, such provision shall be reformed to the minimum extent 164 | necessary to make such provision valid and enforceable. 165 | 166 | If Recipient institutes patent litigation against any entity (including a 167 | cross-claim or counterclaim in a lawsuit) alleging that the Program itself 168 | (excluding combinations of the Program with other software or hardware) 169 | infringes such Recipient's patent(s), then such Recipient's rights granted 170 | under Section 2(b) shall terminate as of the date such litigation is filed. 171 | 172 | All Recipient's rights under this Agreement shall terminate if it fails to 173 | comply with any of the material terms or conditions of this Agreement and does 174 | not cure such failure in a reasonable period of time after becoming aware of 175 | such noncompliance. If all Recipient's rights under this Agreement terminate, 176 | Recipient agrees to cease use and distribution of the Program as soon as 177 | reasonably practicable. However, Recipient's obligations under this Agreement 178 | and any licenses granted by Recipient relating to the Program shall continue 179 | and survive. 180 | 181 | Everyone is permitted to copy and distribute copies of this Agreement, but in 182 | order to avoid inconsistency the Agreement is copyrighted and may only be 183 | modified in the following manner. The Agreement Steward reserves the right to 184 | publish new versions (including revisions) of this Agreement from time to 185 | time. No one other than the Agreement Steward has the right to modify this 186 | Agreement. The Eclipse Foundation is the initial Agreement Steward. The 187 | Eclipse Foundation may assign the responsibility to serve as the Agreement 188 | Steward to a suitable separate entity. Each new version of the Agreement will 189 | be given a distinguishing version number. The Program (including 190 | Contributions) may always be distributed subject to the version of the 191 | Agreement under which it was received. In addition, after a new version of the 192 | Agreement is published, Contributor may elect to distribute the Program 193 | (including its Contributions) under the new version. Except as expressly 194 | stated in Sections 2(a) and 2(b) above, Recipient receives no rights or 195 | licenses to the intellectual property of any Contributor under this Agreement, 196 | whether expressly, by implication, estoppel or otherwise. All rights in the 197 | Program not expressly granted under this Agreement are reserved. 198 | 199 | This Agreement is governed by the laws of the State of New York and the 200 | intellectual property laws of the United States of America. No party to this 201 | Agreement will bring a legal action under this Agreement more than one year 202 | after the cause of action arose. Each party waives its rights to a jury trial in 203 | any resulting litigation. 204 | 205 | 206 | -------------------------------------------------------------------------------- /epl-v10.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Eclipse Public License - Version 1.0 8 | 25 | 26 | 27 | 28 | 29 | 30 |

Eclipse Public License - v 1.0

31 | 32 |

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE 33 | PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR 34 | DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS 35 | AGREEMENT.

36 | 37 |

1. DEFINITIONS

38 | 39 |

"Contribution" means:

40 | 41 |

a) in the case of the initial Contributor, the initial 42 | code and documentation distributed under this Agreement, and

43 |

b) in the case of each subsequent Contributor:

44 |

i) changes to the Program, and

45 |

ii) additions to the Program;

46 |

where such changes and/or additions to the Program 47 | originate from and are distributed by that particular Contributor. A 48 | Contribution 'originates' from a Contributor if it was added to the 49 | Program by such Contributor itself or anyone acting on such 50 | Contributor's behalf. Contributions do not include additions to the 51 | Program which: (i) are separate modules of software distributed in 52 | conjunction with the Program under their own license agreement, and (ii) 53 | are not derivative works of the Program.

54 | 55 |

"Contributor" means any person or entity that distributes 56 | the Program.

57 | 58 |

"Licensed Patents" mean patent claims licensable by a 59 | Contributor which are necessarily infringed by the use or sale of its 60 | Contribution alone or when combined with the Program.

61 | 62 |

"Program" means the Contributions distributed in accordance 63 | with this Agreement.

64 | 65 |

"Recipient" means anyone who receives the Program under 66 | this Agreement, including all Contributors.

67 | 68 |

2. GRANT OF RIGHTS

69 | 70 |

a) Subject to the terms of this Agreement, each 71 | Contributor hereby grants Recipient a non-exclusive, worldwide, 72 | royalty-free copyright license to reproduce, prepare derivative works 73 | of, publicly display, publicly perform, distribute and sublicense the 74 | Contribution of such Contributor, if any, and such derivative works, in 75 | source code and object code form.

76 | 77 |

b) Subject to the terms of this Agreement, each 78 | Contributor hereby grants Recipient a non-exclusive, worldwide, 79 | royalty-free patent license under Licensed Patents to make, use, sell, 80 | offer to sell, import and otherwise transfer the Contribution of such 81 | Contributor, if any, in source code and object code form. This patent 82 | license shall apply to the combination of the Contribution and the 83 | Program if, at the time the Contribution is added by the Contributor, 84 | such addition of the Contribution causes such combination to be covered 85 | by the Licensed Patents. The patent license shall not apply to any other 86 | combinations which include the Contribution. No hardware per se is 87 | licensed hereunder.

88 | 89 |

c) Recipient understands that although each Contributor 90 | grants the licenses to its Contributions set forth herein, no assurances 91 | are provided by any Contributor that the Program does not infringe the 92 | patent or other intellectual property rights of any other entity. Each 93 | Contributor disclaims any liability to Recipient for claims brought by 94 | any other entity based on infringement of intellectual property rights 95 | or otherwise. As a condition to exercising the rights and licenses 96 | granted hereunder, each Recipient hereby assumes sole responsibility to 97 | secure any other intellectual property rights needed, if any. For 98 | example, if a third party patent license is required to allow Recipient 99 | to distribute the Program, it is Recipient's responsibility to acquire 100 | that license before distributing the Program.

101 | 102 |

d) Each Contributor represents that to its knowledge it 103 | has sufficient copyright rights in its Contribution, if any, to grant 104 | the copyright license set forth in this Agreement.

105 | 106 |

3. REQUIREMENTS

107 | 108 |

A Contributor may choose to distribute the Program in object code 109 | form under its own license agreement, provided that:

110 | 111 |

a) it complies with the terms and conditions of this 112 | Agreement; and

113 | 114 |

b) its license agreement:

115 | 116 |

i) effectively disclaims on behalf of all Contributors 117 | all warranties and conditions, express and implied, including warranties 118 | or conditions of title and non-infringement, and implied warranties or 119 | conditions of merchantability and fitness for a particular purpose;

120 | 121 |

ii) effectively excludes on behalf of all Contributors 122 | all liability for damages, including direct, indirect, special, 123 | incidental and consequential damages, such as lost profits;

124 | 125 |

iii) states that any provisions which differ from this 126 | Agreement are offered by that Contributor alone and not by any other 127 | party; and

128 | 129 |

iv) states that source code for the Program is available 130 | from such Contributor, and informs licensees how to obtain it in a 131 | reasonable manner on or through a medium customarily used for software 132 | exchange.

133 | 134 |

When the Program is made available in source code form:

135 | 136 |

a) it must be made available under this Agreement; and

137 | 138 |

b) a copy of this Agreement must be included with each 139 | copy of the Program.

140 | 141 |

Contributors may not remove or alter any copyright notices contained 142 | within the Program.

143 | 144 |

Each Contributor must identify itself as the originator of its 145 | Contribution, if any, in a manner that reasonably allows subsequent 146 | Recipients to identify the originator of the Contribution.

147 | 148 |

4. COMMERCIAL DISTRIBUTION

149 | 150 |

Commercial distributors of software may accept certain 151 | responsibilities with respect to end users, business partners and the 152 | like. While this license is intended to facilitate the commercial use of 153 | the Program, the Contributor who includes the Program in a commercial 154 | product offering should do so in a manner which does not create 155 | potential liability for other Contributors. Therefore, if a Contributor 156 | includes the Program in a commercial product offering, such Contributor 157 | ("Commercial Contributor") hereby agrees to defend and 158 | indemnify every other Contributor ("Indemnified Contributor") 159 | against any losses, damages and costs (collectively "Losses") 160 | arising from claims, lawsuits and other legal actions brought by a third 161 | party against the Indemnified Contributor to the extent caused by the 162 | acts or omissions of such Commercial Contributor in connection with its 163 | distribution of the Program in a commercial product offering. The 164 | obligations in this section do not apply to any claims or Losses 165 | relating to any actual or alleged intellectual property infringement. In 166 | order to qualify, an Indemnified Contributor must: a) promptly notify 167 | the Commercial Contributor in writing of such claim, and b) allow the 168 | Commercial Contributor to control, and cooperate with the Commercial 169 | Contributor in, the defense and any related settlement negotiations. The 170 | Indemnified Contributor may participate in any such claim at its own 171 | expense.

172 | 173 |

For example, a Contributor might include the Program in a commercial 174 | product offering, Product X. That Contributor is then a Commercial 175 | Contributor. If that Commercial Contributor then makes performance 176 | claims, or offers warranties related to Product X, those performance 177 | claims and warranties are such Commercial Contributor's responsibility 178 | alone. Under this section, the Commercial Contributor would have to 179 | defend claims against the other Contributors related to those 180 | performance claims and warranties, and if a court requires any other 181 | Contributor to pay any damages as a result, the Commercial Contributor 182 | must pay those damages.

183 | 184 |

5. NO WARRANTY

185 | 186 |

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS 187 | PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 188 | OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, 189 | ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY 190 | OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely 191 | responsible for determining the appropriateness of using and 192 | distributing the Program and assumes all risks associated with its 193 | exercise of rights under this Agreement , including but not limited to 194 | the risks and costs of program errors, compliance with applicable laws, 195 | damage to or loss of data, programs or equipment, and unavailability or 196 | interruption of operations.

197 | 198 |

6. DISCLAIMER OF LIABILITY

199 | 200 |

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT 201 | NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, 202 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING 203 | WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF 204 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 205 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR 206 | DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED 207 | HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

208 | 209 |

7. GENERAL

210 | 211 |

If any provision of this Agreement is invalid or unenforceable under 212 | applicable law, it shall not affect the validity or enforceability of 213 | the remainder of the terms of this Agreement, and without further action 214 | by the parties hereto, such provision shall be reformed to the minimum 215 | extent necessary to make such provision valid and enforceable.

216 | 217 |

If Recipient institutes patent litigation against any entity 218 | (including a cross-claim or counterclaim in a lawsuit) alleging that the 219 | Program itself (excluding combinations of the Program with other 220 | software or hardware) infringes such Recipient's patent(s), then such 221 | Recipient's rights granted under Section 2(b) shall terminate as of the 222 | date such litigation is filed.

223 | 224 |

All Recipient's rights under this Agreement shall terminate if it 225 | fails to comply with any of the material terms or conditions of this 226 | Agreement and does not cure such failure in a reasonable period of time 227 | after becoming aware of such noncompliance. If all Recipient's rights 228 | under this Agreement terminate, Recipient agrees to cease use and 229 | distribution of the Program as soon as reasonably practicable. However, 230 | Recipient's obligations under this Agreement and any licenses granted by 231 | Recipient relating to the Program shall continue and survive.

232 | 233 |

Everyone is permitted to copy and distribute copies of this 234 | Agreement, but in order to avoid inconsistency the Agreement is 235 | copyrighted and may only be modified in the following manner. The 236 | Agreement Steward reserves the right to publish new versions (including 237 | revisions) of this Agreement from time to time. No one other than the 238 | Agreement Steward has the right to modify this Agreement. The Eclipse 239 | Foundation is the initial Agreement Steward. The Eclipse Foundation may 240 | assign the responsibility to serve as the Agreement Steward to a 241 | suitable separate entity. Each new version of the Agreement will be 242 | given a distinguishing version number. The Program (including 243 | Contributions) may always be distributed subject to the version of the 244 | Agreement under which it was received. In addition, after a new version 245 | of the Agreement is published, Contributor may elect to distribute the 246 | Program (including its Contributions) under the new version. Except as 247 | expressly stated in Sections 2(a) and 2(b) above, Recipient receives no 248 | rights or licenses to the intellectual property of any Contributor under 249 | this Agreement, whether expressly, by implication, estoppel or 250 | otherwise. All rights in the Program not expressly granted under this 251 | Agreement are reserved.

252 | 253 |

This Agreement is governed by the laws of the State of New York and 254 | the intellectual property laws of the United States of America. No party 255 | to this Agreement will bring a legal action under this Agreement more 256 | than one year after the cause of action arose. Each party waives its 257 | rights to a jury trial in any resulting litigation.

258 | 259 | 260 | 261 | 262 | --------------------------------------------------------------------------------