<< Back to previous view

[CCONTRACTS-7] Readme: Add link to API, wiki Created: 13/May/14  Updated: 14/May/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: None

Attachments: File add-docs-section2readme.diff     JPEG File screnshot-no-patch-attribute.jpg    

 Description   

Add links to the API docs and wiki to the README so that people can actualy find them



 Comments   
Comment by Jakub Holy [ 13/May/14 2:56 AM ]

PAtch is attached. I cannot find the "Edit button near the top left of the page" to set the patch atrtribute appropriately as described at http://dev.clojure.org/display/community/Developing+Patches

Comment by Andy Fingerhut [ 13/May/14 12:01 PM ]

Jakub, please check again. I have verified you are on the contributor's list, and have bumped up the permissions on your account so you should be able to see that button now.

Comment by Jakub Holy [ 14/May/14 7:49 AM ]

Thank you, Andy. I can edit the issue but cannot find "Patch" anywhere on the page - pls see the attached screenshot.





[CCONTRACTS-6] Add/improve docs of contract, clojure.core.contracts, etc. Created: 30/Apr/14  Updated: 30/Apr/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

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.

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

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.

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!






[CCONTRACTS-5] Fix links in and display of documentation Created: 30/Apr/14  Updated: 30/Apr/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

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 ./docs/wiki/*.markdown 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. [defconstrainedfn](/clojure/core.contracts/wiki/defconstrainedfn) on f.ex. contract; [with-constraints](/clojure/core.contracts/with-constraints/) (missing /wiki/), [defcontract](/clojure/core.contracts/wiki/defcontract/)

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

Thank you






[CCONTRACTS-4] provide macro fails for multiple constraints Created: 28/Jan/14  Updated: 28/Jan/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Major
Reporter: joerupen Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: None
Environment:

clojure 1.5
core.contracts 0.5



 Description   

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 '[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 [x] x)
(defn bar [x] x)

;; define 2 contracts
(def c1 (ccc/contract c1-cx "should be odd"
[x]
[(odd? x)]))

(def c2 (ccc/contract c2-cx "should have one digit"
[x]
[(= 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 [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






[CCONTRACTS-3] & for additional arguments does not seem to work when declaring a contract Created: 07/Sep/13  Updated: 07/Sep/13

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Major
Reporter: Stephen Cagle Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: None


 Description   

user> (use '[clojure.core.contracts :only [contract]])
nil
user> (contract
silly
"Silly reporting for duty sir!"
[[a & b :as c]]
[])
CompilerException java.lang.RuntimeException: Unable to resolve symbol: & in this context, compiling:(NO_SOURCE_PATH:1:1)

the & in "a & b" is unresolved.






[CCONTRACTS-2] Does clojurescript support work for core.contracts? Created: 06/Sep/13  Updated: 06/Sep/13

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Major
Reporter: Stephen Cagle Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: None
Environment:

Clojurescript



 Description   

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 [clojure.string :as string]
[io.pedestal.app.messages :as msg]
[clojure.zip :as z])
(:use [clojure.core.contracts :only [contract with-constraints]]
[clojure.core.contracts.constraints :only [defconstrainedfn]]
[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.






[CCONTRACTS-1] Make defconstrainedrecord's predicate fast Created: 06/Jun/13  Updated: 28/Jun/13  Resolved: 28/Jun/13

Status: Resolved
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Trivial
Reporter: Ambrose Bonnaire-Sergeant Assignee: Fogus
Resolution: Completed Votes: 0
Labels: None

Attachments: File fast-predicate2.diff     File fast-predicate.diff    

 Description   

Instead of using the slow `clojure.core/type`, use an inlining function calling `instance?`. I have not tested the performance, but it's probably much faster.



 Comments   
Comment by Ambrose Bonnaire-Sergeant [ 16/Jun/13 11:17 AM ]

These are the kinds of numbers I'm seeing between using type vs. instance? (220ms vs. 15ms).

Crude tests, but it should be obvious the inlining version is much faster.

user=> (time (dotimes [_ 1e6] (instance? Integer 1)))
"Elapsed time: 13.839681 msecs"
nil
user=> (time (dotimes [_ 1e6] (instance? Integer 1)))
"Elapsed time: 19.862729 msecs"
nil
user=> (time (dotimes [_ 1e6] (instance? Integer 1)))
"Elapsed time: 15.176552 msecs"
nil
user=> (time (dotimes [_ 1e6] (= Integer (type 1))))
"Elapsed time: 220.796493 msecs"
nil
user=> (time (dotimes [_ 1e6] (= Integer (type 1))))
"Elapsed time: 220.6573 msecs"
nil
user=> (time (dotimes [_ 1e6] (= Integer (type 1))))
"Elapsed time: 224.051327 msecs"
nil
Comment by Ambrose Bonnaire-Sergeant [ 17/Jun/13 12:38 AM ]

Attached new patch: fast-predicate2.diff

Ensure instance? inlines. Needs to be put in a fn rather than definline.

There's a little benchmark. I noticed a speedup to 17ms for 1e6 iterations, from 185ms.

Comment by Fogus [ 28/Jun/13 8:11 AM ]

Applied on master. I will push a point-version out later today. Thanks.





Generated at Wed Jul 23 10:31:02 CDT 2014 using JIRA 4.4#649-r158309.