speculate: discovery of properties about Haskell functions

[ bsd3, library, testing ] [ Propose Tags ]

Speculate automatically discovers laws about Haskell functions. Give Speculate a bunch of Haskell functions and it will discover laws like:

equations, such as id x == x ;
inequalities, such as 0 <= x * x ;
conditional equations, such as x <= 0 ==> x + abs x == 0 .

[Skip to Readme]

Versions	0.2.0, 0.2.1, 0.2.2, 0.2.3, 0.2.4, 0.2.5, 0.2.6, 0.2.7, 0.2.8, 0.2.9, 0.2.10, 0.3.0, 0.3.1, 0.3.2, 0.3.3
Dependencies	base (==4.*), cmdargs, containers, leancheck (>=0.7) [details]
License	BSD-3-Clause
Author	Rudy Matela, Colin Runciman
Maintainer	Rudy Matela <rudy@matela.com.br>
Category	Testing
Home page	https://github.com/rudymatela/speculate#readme
Source repo	head: git clone https://github.com/rudymatela/speculate this: git clone https://github.com/rudymatela/speculate(tag v0.3.3)
Uploaded	by rudymatela at Sat Aug 18 19:50:49 UTC 2018
Distributions	LTSHaskell:0.3.2, NixOS:0.3.2, Stackage:0.3.2
Downloads	2623 total (243 in the last 30 days)
Rating	(no votes yet) [estimated by rule of succession]
Your Rating	λ λ λ
Status	Docs uploaded by user Build status unknown [no reports yet] Hackage Matrix CI

Downloads

speculate-0.3.3.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

For package maintainers and hackage trustees

edit package information

Readme for speculate-0.3.3

[back to package description]

Speculate

Speculate automatically discovers laws about Haskell functions. Give Speculate a bunch of Haskell functions and it will discover laws like:

equations, such as id x == x;
inequalities, such as 0 <= x * x;
conditional equations, such as x <= 0 ==> x + abs x == 0.

Speculate is similar to, and inspired by, QuickSpec.

Installing Speculate

To install the latest Speculate version from Hackage, just:

$ cabal update
$ cabal install speculate

Pre-requisites are cmdargs and leancheck. They should be automatically resolved and installed by Cabal.

Using Speculate

Speculate is used as a library: import it, then call the function speculate with relevant arguments. The following program Speculates about the functions (+) and abs:

import Test.Speculate

main :: IO ()
main = speculate args
  { constants =
      [ showConstant (0::Int)
      , showConstant (1::Int)
      , constant "+"   ((+)  :: Int -> Int -> Int)
      , constant "abs" (abs  :: Int -> Int)
      ]
  }

when run, it prints the following:

_ :: Int  (holes: Int)
0 :: Int
1 :: Int
(+) :: Int -> Int -> Int
abs :: Int -> Int

    abs (abs x) == abs x
          x + 0 == x
          x + y == y + x
    (x + y) + z == x + (y + z)
abs (x + abs x) == x + abs x
  abs x + abs x == abs (x + x)
abs (1 + abs x) == 1 + abs x

x <= abs x
0 <= abs x
x <= x + 1

Now, if we add <= and < as background constants on args

  , constants =
      [ showConstant (0::Int)
      , showConstant (1::Int)
      , constant "+"   ((+)  :: Int -> Int -> Int)
      , constant "abs" (abs  :: Int -> Int)
      , background
      , constant "<="  ((<=) :: Int -> Int -> Bool)
      , constant "<"   ((<)  :: Int -> Int -> Bool)
      ]

then run again, we get the following as well:

    y <= x ==> abs (x + abs y) == x + abs y
    x <= 0 ==>       x + abs x == 0
abs x <= y ==>     abs (x + y) == x + y
abs y <= x ==>     abs (x + y) == x + y

For more examples, see the eg folder.

Similarities and Differences to QuickSpec

Speculate is inspired by QuickSpec. Like QuickSpec, Speculate uses testing to speculate equational laws about given Haskell functions. There are some differences:

Speculate tests enumeratively using LeanCheck, QuickSpec tests randomly using QuickCheck;
Speculate is able to report inequalities directly;
QuickSpec allows polymorphism, Speculate does not;
For most examples, Speculate runs slower than QuickSpec 2 but faster than QuickSpec 1.