hegel-clj.generator — com.aphyr/hegel-clj 0.1.1

Composable generators. These functions return a schema, which can be used with hegel-clj.test/gen to produce an actual value. We generally follow Hegel's protocol, but with a Clojure flavor: we use vec instead of list, because it generates vectors, and bytes instead of binary, and so on. Option names use :kebab-case keywords and the usual :flag? for boolean options.

bind clj

(bind f gen)

Transforms generators. Takes a function (f x) -> gen, and a generator of xs. Produces a generator which uses gen to generate an x, calls (f x), and draws a value from the resulting generator.

For example, to build a generator which generates two vectors wth the same size, one with ints, the other with floats:

(bind (fn [size]
        (tuple (vector {:size size} (integers))
               (vector {:size size} (floats))))
      (integers))

Hegel calls this flatMap.

boolean clj

(boolean)

(boolean p)

Generates a boolean, optionally with the given probability.

bytes clj

(bytes)

(bytes {:keys [min-size max-size]})

Generates a byte array. Hegel calls this bytes. Options:

:min-size Minimum size :max-size Maximum size

clj-sym-basic-pattern clj

A partial regular expression pattern for the basic characters that can make up a Clojure symbol.

clj-sym-initial-pattern clj

A partial regular expression pattern for the basic characters that can start a Clojure symbol

composite clj macro

(composite & body)

Wrapper for composite-fn. Takes a body which returns a value, presumably through calls to hegel.core/draw! or let, and returns a Generator which evaluates that body to produce values.

composite-fn clj

(composite-fn f)

A generator which builds a value by making imperative draws from a test case. Takes a function (f test-case) -> x, and returns a Generator that returns xs.

deferred clj

(deferred)

Like a promise for Generators. Constructs a forward reference for building self-recursive or mutually-recursive generators. Use (set-deferred! deferred some-gen) to provide the generator later.

domain clj

(domain)

Generates a domain name as a string, per RFC 1035.

double clj

(double)

(double {:keys [infinity? nan? min max exclude-min? exclude-max?]})

(double min max)

Generates a 64-bit Double. Options:

:min Minimum value :max Maximum value (ditto) :exclude-min? Exclude the minimum value :exclude-max? Exclude the maximum value :nan? Whether to allow NaNs :infinity? Whether to allow infinity

email clj

(email)

Generates an email address as a string, per RFC 5322 section 3.4.1

filter clj

(filter f gen)

Filters a generator to produce only values which pass (f x).

float clj

(float)

(float {:keys [infinity? nan? min max exclude-min? exclude-max?]})

(float min max)

Generates a 32-bit Float. Options:

:min Minimum value :max Maximum value (ditto) :exclude-min? Exclude the minimum value :exclude-max? Exclude the maximum value :nan? Whether to allow NaNs :infinity? Whether to allow infinity

fmap clj

(fmap f gen)

Transforms generated values. Takes a function which takes one generated value to another, and a Generator. Returns a Generator which applies f to those values. For example, to generate even integers:

(fmap (partial * 2) (integers))

Hegel calls this map.

for-type clj

(for-type class)

Produces a generator for the given JVM datatype, using reflection. Supports scalars like Integer, Long, Boolean, Float, Double, String, Byte[], etc. Also supports JVM enums, records (recursively), and collections like List, Set, Optional, and Map, though I don't know how to actually use that feature yet.

hmap clj

(hmap m)

Generates a heterogenous map. Takes a map of keys (any objects) to generators, and returns a generator which produces maps with those keys, and values drawn from their corresponding generators. For example:

(g/hmap {:name (g/string)
         :age  (g/integer)})

integer clj

(integer)

(integer {:keys [min max]})

(integer min max)

Generates a 32-bit Integer. Options:

:min Minimum value, inclusive :max Minimum value, inclusive

ip-address-str clj

(ip-address-str)

(ip-address-str version)

Generates an IP address; version should be either 4 for ipv4, or 6 for ipv6. With no version, generates both kinds.

just clj

(just x)

A Generator which always returns the provided object.

keyword clj

(keyword)

A Clojure keyword, either simple or qualified.

list clj

(list elements)

(list opts elements)

Like vector, but returns Clojure lists.

local-date clj

(local-date)

Generator of java.time.LocalDate.

local-date-str clj

(local-date-str)

Generates an ISO 8601 date string, like 1987-02-16

local-date-time clj

(local-date-time)

Generates a java.time.LocalDateTime.

local-date-time-str clj

(local-date-time-str)

Generates an ISO 8601 datetime string, like 2024-03-15T14:30:00

local-time clj

(local-time)

Generates a java.time.LocalTime.

local-time-str clj

(local-time-str)

Generates an ISO 8601 time string, like 14:30:00.123

long clj

(long)

(long {:keys [min max]})

(long min max)

Generates a 64-bit Long. Options:

:min Minimum value, inclusive :max Minimum value, inclusive

map clj

(map keys values)

(map {:keys [size min-size max-size]} keys values)

Generates a map of keys to values, given a generator for keys and another for values. Options:

:size Shorthand for {:min-size size, :max-size size} :min-size The minimum number of elements, inclusive :max-size The maximum number of elements, inclusive

Note that Hegel does not seem to be able to generate keys with some types--you can't, for instance, generate keys which are vectors of integers.

one-of clj

(one-of gens)

A generator which returns a value drawn from one of several generators.

qualified-keyword clj

(qualified-keyword)

An unqualified Clojure keyword, e.g. :foo/bar

qualified-symbol clj

(qualified-symbol)

A qualified Clojure symbol, e.g. 'foo/bar

regex-str clj

(regex-str pattern)

(regex-str pattern {:keys [full-match?]})

Generator of strings matching the given regular expression, which can be either a regex or string. The regex language used to be Python; with the Rust rewrite I'm not sure what it is.

It used to be that #"^\d$" would produce digits like "߄". The Python syntax for enabling ASCII mode was illegal in Java patterns, so you had to fall back to [0-9] or a string if you want to generate the usual ASCII digits:

(regex "(?a)^\d+$") ; => 5, 2, 0, 3, ...

Options:

:full-match? Whether the pattern must match the full string, or if a substring match is allowed. Default false.

sampled-from clj

(sampled-from xs)

A generator which returns one of several values.

set clj

(set elements)

(set {:keys [min-size max-size]} elements)

Generates sets of elements. Options:

:size Shorthand for {:min-size size, :max-size size} :min-size The minimum number of elements, inclusive :max-size The maximum number of elements, inclusive

set-deferred! clj

(set-deferred! d gen)

Sets the value of a Deferred generator to the provided gen. Returns the deferred.

simple-keyword clj

(simple-keyword)

An unqualified Clojure keyword, e.g. :foo

simple-symbol clj

(simple-symbol)

A unqualified Clojure symbol, e.g. 'foo

sorted-map clj

(sorted-map keys values)

(sorted-map opts keys values)

Like map, but generates sorted maps.

sorted-set clj

(sorted-set elements)

(sorted-set opts elements)

Like set, but generates sorted sets.

string clj

(string)

(string {:keys [min-size max-size]})

Generates a Unicode string. Options:

:min-size Minimum size, in code points :max-size Maximum size, in code points

TODO: fill in other options from https://javadoc.io/static/dev.hegel/hegel/0.4.0/dev.hegel/dev/hegel/generators/TextGenerator.html

symbol clj

(symbol)

Generates a Clojure symbol, either simple or qualified.

tuple clj

(tuple)

(tuple a)

(tuple a b)

(tuple a b c)

(tuple a b c d)

(tuple a b c d e)

(tuple a b c d e f)

(tuple a b c d e f g)

(tuple a b c d e f g h)

(tuple a b c d e f g h & more)

Takes any number of generators and generates a fixed-size vector of that size, where each element is drawn from the corresponding generator.

tuple* clj

(tuple* gens)

Takes a vector of generators and returns a generator of vectors whose first element is drawn from the first generator, second element from the second, and so on.

url-str clj

(url-str)

Generates a URL as a string, per RFC 3986.

vector clj

(vector elements)

(vector {:keys [size min-size max-size unique?]} elements)

Generates a vector of elements. Takes options and a Generator of elements.

:size Shorthand for {:min-size size, :max-size size} :min-size The minimum number of elements, inclusive :max-size The maximum number of elements, inclusive :unique? If set, picks unique elements