https://github.com/siili-core/humanize
Translate computer produced garble into human readable form
https://github.com/siili-core/humanize
clojure humanize schema translator
Last synced: about 1 month ago
JSON representation
Translate computer produced garble into human readable form
- Host: GitHub
- URL: https://github.com/siili-core/humanize
- Owner: siili-core
- License: epl-1.0
- Created: 2018-02-28T14:53:40.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-09-14T09:57:13.000Z (over 7 years ago)
- Last Synced: 2025-08-06T20:56:16.699Z (6 months ago)
- Topics: clojure, humanize, schema, translator
- Language: Clojure
- Homepage:
- Size: 23.4 KB
- Stars: 17
- Watchers: 7
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🤖 `(humanize ex)` 😊
Library for translating errors into human readable form.
[](https://opensource.org/licenses/EPL-1.0) [](https://circleci.com/gh/siilisolutions/humanize) [](https://cljdoc.xyz/d/siili/humanize/CURRENT)
## Installation
Add `siili/humanize` to your project:
[](https://clojars.org/siili/humanize)
> Not sure if humanize is for you? We recommend testing it with [`lein try`](https://github.com/rkneufeld/lein-try)!
## Usage
Base usage is very simple:
1. Require namespace you need
1. Use `ex->err` function from humanize's namespace to convert exceptions into translated error data
1. Use that data in any way you please
### Translated error data format
- The main data structure is always a map
- There are three keywords which describe where the error(s) occurred:
- `:in` input to function is faulty
- `:out` function's output is faulty
- `:unknown` faulty data occurred in unspecified location
- `:in` is a vector where each entry describes one argument to function in the same order as they are defined in function signature
- `:out` is a single value
- `:unknown` is unspecified
### Example: with [Plumatic Schema](https://github.com/plumatic/schema)
```clojure
;; require needed namespaces
(require '[schema.core :as s]
'[humanize.schema :as h])
;; humanize is meant for interop with s/defn functions
(s/defn broken :- s/Str
[x :- s/Int]
x)
;; boilerplate for calling the broken function in invalid way
(defn check [f]
(try
(f)
(catch clojure.lang.ExceptionInfo e
(if (= (-> e ex-data :type)
:schema.core/error)
(h/ex->err e)))))
(check #(broken "two"))
=> {:in ([x "'two' is not an integer."])}
```
## Extending
Humanize can only handle the built-in types and structures. For user defined types an additional translator function can be provided to utilize humanize's internal resolver logic.
For example, assuming the following regular expression checking variant schema has been defined by user:
```clojure
(ns my.ns
(:require [schema.core :as s]
[schema.spec.variant :as variant]
[schema.spec.core :as spec]))
(defrecord RegexString [regex]
s/Schema
(spec [this]
(variant/variant-spec
spec/+no-precondition+
[{:schema s/Str}]
nil
;; take special note of this line, the list at the end is important
(spec/precondition this (partial re-matches regex) #(list 'not-matching regex %))))
(explain [this]
(list 'regex-constrained (s/explain s/Str) regex)))
```
which is then used to define a custom validator:
```clojure
(def AtoZ (RegexString. #"[AZ]+"))
(s/defn yelling-alphas :- s/Any
[aagh :- AtoZ]
aagh)
```
running this through humanize in same manner as above would produce unresolved translation:
```clojure
(check #(yelling-alphas "123"))
=> {:in ([aagh [not [not-matching #"[AZ]+" "123"]]])}
```
which isn't that useful. To resolve this, simply provide a additional translations function to `ex->err`:
```clojure
(defn check [f additional-translations]
(try
(f)
(catch clojure.lang.ExceptionInfo e
(if (= (-> e ex-data :type)
:schema.core/error)
(h/ex->err e additional-translations)))))
```
and call it with your own logic (we recommend [clojure/core.match](https://github.com/clojure/core.match)) to get the desired result:
```clojure
(defn my-translate [x]
(clojure.core.match/match
x
;; this matches with the spec/precondition list in variant spec
['not ['not-matching regex-pattern value]]
(str value " does not match regex pattern " regex-pattern)
:else
x))
(check #(yelling-alphas "123") my-translate)
=> {:in ([aagh "123 does not match regex pattern [AZ]+"])}
```
## Acknowledgements
[André Rauh](https://gist.github.com/rauhs/cfdb55a8314e0d3f4862) for the original Plumatic Schema exception unroller.
## Related Work
- For [`spec.alpha`](https://github.com/clojure/spec.alpha) see [bhb/expound](https://github.com/bhb/expound)
- For older versions of Schema and additionally Avro, datomic, etc. see [cddr/integrity](https://github.com/cddr/integrity)
It is possible some of the features of this library will find their way to humanize eventually
## License
Copyright © 2018 Siili Solutions
Distributed under the Eclipse Public License either version 1.0 or (at
your option) any later version.