Clojure Q&A - Recent questions in core.contracts

Add/improve docs of contract, clojure.core.contracts, etc.

Wed, 30 Apr 2014 13:45:32 +0000

Even though {{contract}} is a key thing in the library, it lacks a docstring.
The docstring of the ns could also have a few words pointing to the main functions
and how to use them.

h3. contract

For contract, st. like would be nice (excuse my poor understanding of the lib):

Define a named and documented contract.

constraints => signature-constraint*
signature-constraint => argument-vector constraint-vector
constraint-vector => functions and expressions [=> functions and expressions]

The functions are applied to the arguments, an expressions is executed as-is.
Constraint following `=>` are post-conditions and may use `%` to refer to the return value.

Ex.:

(contract doubler
  "ensures doubling (sometimes)"
  [x] [number? => integer?]
  [x y] [(every? number? [x y])
           =>
         integer? (= (* 2 (+ x y)) %)])))

See also: with-constraints, defconstrainedfn, and clojure.core.contracts.constraints

h3. ns

The ns docstring could be improved f.ex. like this

The public contracts programming functions and macros for clojure.core.contracts.
Primary usage: defconstrainedfn or contract and with-constraints.
Use provide for functions you don't control.

h3. Other

There are other undocumented or too lightly documented fns/macros that would benefit
from improvements, f.ex.
* what does _ do?
* provide would benefit from a (even brief) example
* require-with-constraints - what is it, when to use?
* in - an example would be nice
* whitelist - the argument should be 'thing' not 'things' to be consistent with the docstring and the fact that it is a single map/set
* an example of using implies, <=>, etc. would be nice - currently I don't really know when/why to use it (not mentioning how) [perhaps in the ns docstring, all this functions docstring having "... see the ns docstring")
* why is defconstrainedfn in constraints.clj and not contracts.clj as the other main fns?
Why does provide use "kontracts" instead of "c" as with-constraints does? (The mismatch of "constraint" and "contract" - fn is with-constraints but takes contracts - is in itself confusing but that is another story.)
* defconstrainedrecord has no doc

I would be really happy if at least some of these improvements were applied. I believe it would help to spread contract programming more.

Thank you!

Fix links in and display of documentation

Wed, 30 Apr 2014 12:37:14 +0000

There is a number of problems with the way the documentation is made available and interlinked:

Currently most people likely arrive to https://github.com/clojure/core.contracts and read the README - but it does not point to the docs in {{./docs/}} => add link to it there
It is not clear how the docs are expected to be browsed; I suppose that the .org
files should be exported to * } yet not all of them are. I also
suppose that the exported markdown files should be available under https://github.com/clojure/core.contracts/wiki, i.e. pushed to git@github.com:clojure/core.contracts.wiki.git
Some of the problems:
```
 *  the link "return to documentation" on e.g. "with-constraints" should point to /clojure/core.contracts/wiki, not /clojure/core.contracts/docs.html
```
- if wiki is really exported, the main page should mention it is immutable
- links on the home page had one more 'wiki' in them (fixed manually in the wiki - will be overriden by the next export)
- some links are broken, f.ex. (link: defconstrainedfn)(/clojure/core.contracts/wiki/defconstrainedfn) on f.ex. {{contract}}; (link: with-constraints)(/clojure/core.contracts/with-constraints/) (missing /wiki/), (link: defcontract)(/clojure/core.contracts/wiki/defcontract/)

It would certainly help the project if the documentation was easier to access and browse :-)

Thank you

provide macro fails for multiple constraints

Tue, 28 Jan 2014 20:04:47 +0000

The following code shows 2 ways for defining a function with constraints.

=> it works as expected using the with-constraints macro
=> it fails on the second contract using the provide macro

(require '(link: clojure.core.contracts :as ccc))

;; because the provide macro alters the var-root, let's keep two separate identical functions for the test.

(defn qux (link: x) x)
(defn bar (link: x) x)

;; define 2 contracts
(def c1 (ccc/contract c1-cx "should be odd"

            (link: x) 
            (link: (odd? x))))

(def c2 (ccc/contract c2-cx "should have one digit"

			(link: x)
            (link: (= 1 (count (str x))))))

;; using the provide macro => c1 is asserted, c2 never. When we swap around c2 c1, then c2 is asserted, c1 never
(ccc/provide (link: qux "qux" c1 c2))

;; on the other hand, using with-constraints works as expected.
(def qux-g
(ccc/with-constraints bar c1 c2))

(qux 2) ;; expected assertion "should be odd"
(qux 3) ;; expected 3
(qux 23) ;; expected assertion "only one digit", but we get 23

(qux-g 2) ;; should be odd
(qux-g 3) ;; OK
(qux-g 23) ;; should be positive

& for additional arguments does not seem to work when declaring a contract

Sun, 08 Sep 2013 04:29:48 +0000

user> (use '(link: clojure.core.contracts :only [contract)])
nil
user> (contract

   silly
   "Silly reporting for duty sir!"
   (link: [a & b :as c])
   (link: ))

CompilerException java.lang.RuntimeException: Unable to resolve symbol: & in this context, compiling:(NO_SOURCE_PATH:1:1)

the & in "a & b" is unresolved.

Does clojurescript support work for core.contracts?

Fri, 06 Sep 2013 23:55:42 +0000

I have a pedestal app I am working on. I have made some really helpful (at least to me) use of core.contracts in testing my clojure/clojurescript shared code (in clojure) using test.generative. When I open my code in the browser though and try to bring a namespace that makes use of core.contracts into clojurescript, I get the following error. None of the constraints I wrote actually make use of any native java types (at least I don't think). I am mostly just checking that the values of things align with what I expect in the inputs and outputs.

In my behavior.clj I have

(ns ^:shared com.samedhi.contracts.app.behavior

(:require (link: clojure.string :as string)
             (link: io.pedestal.app.messages :as msg)
             (link: clojure.zip :as z))
(:use (link: clojure.core.contracts :only [contract with-constraints)]
        (link: clojure.core.contracts.constraints :only [defconstrainedfn])
        (link: clojure.test :only [is])))

which compiles into cljs as
...
goog.require('clojure.core.contracts.constraints');
goog.require('com.samedhi.quizry.app.quiz');
goog.require('clojure.core.contracts');
goog.require('clojure.test');
...

which throws a javascript exception at goog.require('clojure.core.contracts.constraints') when I look in the data-ui view, saying:

errorMessage: "goog.require could not find: clojure.core.contracts.constraints"
name: "clojure.core.contracts.constraints"

Is there some sort of special way I need to import things within clojurescript to use core.contracts?

BTW, I really appreciate core contracts, it is really neato. Thanks for you work.