here is a spec that should at least be a good starting point 🙂

(ns foo.foo
  (:require [clojure.spec.alpha :as s]
            [clojure.spec.gen.alpha :as gen]))

(defn validate-height [{:keys [height extent] :as m}]
 (if height
    (>= height (+ (* extent 2)))
    true))

(defn validate-width [{:keys [width extent]}]
 (if width
  (>= width (+ (* extent 2)))
  true))

(s/def ::width (s/and pos-int? odd?))
(s/def ::height (s/and pos-int? odd?))
(s/def ::seed pos-int?)
(s/def ::density (s/double-in :min 0.1 :max 1.0))
(s/def ::meander-rate (s/double-in :min 0.0 :max 1.0))
(s/def ::door-rate (s/double-in :min 0.0 :max 1.0))
(s/def ::stage
  (s/and
    (s/keys :req-un [::seed ::density ::extent ::meander-rate ::door-rate]
            :opt-un [::width ::heigt])
    #(validate-height %)
    #(validate-width %)))

(def stage-defaults
  {:seed 12419
   :density 0.65
   :extent 5
   :meander-rate 0.0
   :door-rate 0.5})

(defn make-stage [options]
  (s/valid? ::stage options))
  ;; or (s/explain ::stage options))

Hmm, I've never seen a lot of this stuff like the double colon keywords

the double colon keyword is called a "namespace qualified keyword"

if you're in namespace foo, then ::bar expands to foo/bar. this is used to avoid name collisions when merging keys from different sources

so in this case ::width expands to foo.foo/width, and another namespace can define a ::width spec but since they're qualified there's no risk of collision

Interesting.

So basically I shouldn't use preconditions for most things

I sort of liked the concision, but oh well

you could do something like this:

(defn make-stage [options]
  {:pre [(s/valid? ::stage (merge stage-defaults options))]}
  "do the thing") 

spec can work in tandem with pre and post

what is :req-un and :opt-un?

the default in spec is to require namespaced keywords for the inputs as well, so if you use req and opt here it means that the input map must have keys like foo.foo/meander-rate etc.

req-un and opt-un means `'allow unqualified keywords as inputs"

I don't understand what spec is doing at all from this code. I'll have to read about spec first I think

here's a very nice introduction: https://clojure.org/guides/spec#_getting_started

it's long but of course you don't have to learn everything in one sitting

Ok, I'll read. Thanks for your help

you're welcome, hope it helps you solve your problem

Wow spec is very nice. Clojure just keeps on impressing me. Thanks so much

glad I could help! 🙂

I can't understand how :opt or :opt-un affect validation. If I pass an argument not specified, it doesn't raise an error

that's a deliberate design in spec, all maps are open. you can only specify what is required, you can't forbid keys. opt is just for documentation purposes. IIRC, all keys in the map are validated if they have a spec registered, regardless of whether they are specified in keys or not.

this has proved to be a somewhat controversial design decision 😉

Ok. So the only issue I now have is I'm forced to merge twice

in the pre-condition, and in a let binding for the body

in that case I'd just skip the :pre and do the check in a conditional in the body that reuses the let binding

Actually, that's not the issue:

my parameters are destructured, because these will eventually map to command line arguments: [& {:keys [width height seed density extent meander-rate door-rate] :as options}]

then i do (:pre [(s/explain ::stage options)]}

But the body needs all the merged map values...so I need to also destructure a let binding which seems repetitious

can you post the complete function?

Only using seed so far in the let binding, but there will be more: https://gist.github.com/mfiano/b46007fdbc4ae59130b1bd132e91424f

Which is optional, so needs to be merged

here's how I would write that function:

(defn make-stage [user-options]
  (let [{:keys [width height seed density extent meander-rate door-rate] :as options} (merge stage-defaults user-options)]
    (if (not (s/valid? ::stage options))
       (throw (ex-info "Invalid options" (s/explain-data ::stage options)))     
       (do
         (rng/set-seed! seed)         
         "more stuff here"))))              

note that I use a map instead of keyword arguments, since IMO those tend to complicate things for little benefit

somewhere in the http://clojure.org docs I read that outer user api functions should use keyword args and stuff not for the user should just be regular maps, so i was following that advice

This function here is going to eventually be the main entry point to be exposed for running the jar on the command line with those required and optional parameters. is that going to be a problem?

huh, that seems like outdated advice to me. Note that I'm not saying that they're bad and should never be used, just that my experience has been that it's easier and more flexible to use maps instead 🙂

won't be a problem as far as I can tell!

The use of keyword arguments has fallen in and out of fashion in the Clojure community over the years. They are now mostly used when presenting interfaces that people are expected to type at the REPL or the outermost layers of an API. In general, inner layers of the code find it easier to pass options as an explicit map.

from https://clojure.org/guides/destructuring

not bad advice by any means, feel free to use whatever you like 🙂 my version uses maps cause I think it's easier when you're merging multiple arg maps

Thanks again. I like your version.

The only thing I dislike is how specs with an external dependency have to have a separate function, and then added in the aggregate. In your example at the top of this thread, it's disappointing that validate-height and validate-width are nearly the same, and that they are invoked in the aggregate ::stage spec, so the whole map is given as input and difficult to figure out the problem in the case of an exception.

yeah, it can make it harder to find errors for sure, but I'm not sure how it could be done differently. that the methods are nearly the same is just sloppy coding from my side, you could easily modify the function to take a parameter for the key and reuse that function for both cases 🙂

Yeah I was able to translate your sloppy coding. No worries. On a side note those validation function are always truthy 🙂

I have some other issues too, like re-validating a hashmap as keys are assocd to it later efficiently, but optimizations for another day I suppose.

Appreciate all your help. I am definitely having fun with spec

glad to hear it! 🙂

nah

the problem with + used that way is that it gets inlined

not direct linked

and there's no disabling for that

not sure I follow. is var redefinition contingent on JVM optimizations? or do you mean inlined by the Clojure compiler?

inlined by the clojure compiler

I thought that was what direct linking was 😄

look at the metadata for #'+

you'll see :inline and :inline-arities

ooohhh right!

I forgot about those

I see, that makes sense, thanks for correcting me :thumbsup:

np! figuring whats at play between inline/dl/compiler intrinsics can get tricky :)

nat-int?