Uniform library settings

[schmudde]

Wikidata's User-Agent enforcement necessitated a Mundaneum patch, #19.

We should refactor to using a map for all the parameters we might want to thread through the various operations (#19 (comment)).

Requirements

1. User-Agent
2. Move the format from the URL query string to the dynamically-defined request header to allow users of Mundaneum easy overwrite.
3. Updating the management of *default-language*.

Our defaults have two different ergonomic requirements.

1. Language

Language should be flexible enough to change per-query OR per-session. From the original documentation:

In addition to these affordances, there is also a dynamic variablemundaneum.query/*default-language* which is an atom containing an ISO language code keyword like :en that controls which language will be used by default for labels and description input/output. If you are planning to enjoy an interactive session in French you could set [a global default] [...] On the other hand, if you want to mix languages freely, you can [set/pass a local ISO keyword].

2. HTTP Headers

HTTP Headers really only need to change per-session - i.e. a global default.

Solution

A backwards-compatible solution with optional per-thread bindings would look like this:

(def defaults (atom {:language  :en
                     :http-headers   {"User-Agent" "Mundaneum (+https://github.com/jackrusher/mundaneum)"
                                      "Accept"     "application/sparql-results+json"}}))

(def ^:dynamic *default-language* defaults)

(defn default-language
  "Returns the unwrapped value of the in-scope binding of `*default-language*`, which can be an atom containing a keyword representing the current default language (like `:en`) or an atom containing such a keyword."
  []
  (if (instance? clojure.lang.IDeref *default-language*)
    (:language (deref *default-language*))
    *default-language*))

And the documentation can be updated to something like (swap! defaults assoc :language :fr) to suggest runtime state changes.

[schmudde]

@jackrusher - not sure if this is what you meant by "thread through the various operations." Not a lot of threading happening. It's more of the same (i.e. fully backwards compatible). The most awkward part is that *default-langauge* returns the full atom (not the :language) if not bound per thread. Otherwise coherent and I could update the HTTP call sites.

[jackrusher]

If I were moving the runtime config into a map, I would probably also provide a few helper functions to set those values. It's what I should have done in the first place for *default-language* because then changing the underlying implementation wouldn't be a breaking change for downstream consumers. Mea culpa.