From 75aa59494b90df92cae342ff6c8d89e4a48e2b1d Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Wed, 6 Mar 2024 14:27:34 +0100 Subject: [PATCH] [doc] Update examples to match other projects --- README.md | 2 +- examples/truss_examples.cljc => examples.cljc | 41 ++++--------------- wiki/1-Getting-started.md | 12 +++--- 3 files changed, 15 insertions(+), 40 deletions(-) rename examples/truss_examples.cljc => examples.cljc (93%) diff --git a/README.md b/README.md index a3a2769..c3d0fd1 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ See for intro and usage: ;; {:ns truss-examples, ;; :line 9, ;; :column 11, -;; :file "examples/truss_examples.cljc"}} +;; :file "examples.cljc"}} ``` That's everything most users will need to know, but see the [documentation](#documentation) below for more! diff --git a/examples/truss_examples.cljc b/examples.cljc similarity index 93% rename from examples/truss_examples.cljc rename to examples.cljc index 8af0820..24c0bdf 100644 --- a/examples/truss_examples.cljc +++ b/examples.cljc @@ -1,10 +1,9 @@ -(ns truss-examples - {:author "Peter Taoussanis (@ptaoussanis)"} +(ns examples + "Some basic Truss usage examples." (:require [taoensso.truss :as truss :refer [have have! have?]])) ;;;; First API example -(comment (defn square [n] (let [n (have integer? n)] (* n n))) @@ -23,13 +22,10 @@ ;; {:ns truss-examples, ;; :line 9, ;; :column 11, -;; :file "examples/truss_examples.cljc"}} -) +;; :file "examples.cljc"}} ;;;; Inline assertions and bindings -(comment - ;; You can add an assertion inline (println (have string? "foo")) @@ -48,7 +44,7 @@ ;; {:ns truss-examples, ;; :line 41, ;; :column 1, -;; :file "examples/truss_examples.cljc"}} +;; :file "examples.cljc"}} ;; Truss also automatically traps and handles exceptions (have string? (/ 1 0)) ; => @@ -66,7 +62,7 @@ ;; {:ns truss-examples, ;; :line 54, ;; :column 1, -;; :file "examples/truss_examples.cljc"}, +;; :file "examples.cljc"}, ;; :err ;; #error ;; {:cause "Divide by zero" @@ -76,11 +72,9 @@ ;; :at [clojure.lang.Numbers divide "Numbers.java" 190]}] ;; :trace ;; [<...>]}} -) ;;;; Destructured bindings -(comment ;; You can assert against multipe args at once (let [[x y z] (have string? "foo" "bar" "baz")] (str x y z)) ; => "foobarbaz" @@ -97,12 +91,10 @@ ;; {:ns truss-examples, ;; :line 89, ;; :column 15, -;; :file "examples/truss_examples.cljc"}} -) +;; :file "examples.cljc"}} ;;;; Attaching debug data -(comment (defn my-handler [ring-req x y] (let [[x y] (have integer? x y :data {:ring-req ring-req})] (* x y))) @@ -117,13 +109,11 @@ ;; {:ns truss-examples, ;; :line 107, ;; :column 15, -;; :file "examples/truss_examples.cljc"}, +;; :file "examples.cljc"}, ;; :data {:dynamic nil, :arg {:ring-req {:foo :bar}}}} -) ;;;; Attaching dynamic debug data -(comment (defn wrap-ring-dynamic-assertion-data "Returns Ring handler wrapped so that assertion violation errors in handler will include `(data-fn )` as debug data." @@ -153,23 +143,17 @@ ;; {:ns truss-examples, ;; :line 136, ;; :column 3, -;; :file "examples/truss_examples.cljc"}, +;; :file "examples.cljc"}, ;; :data {:dynamic {:ring-session {:user-name "Stu"}}, :arg nil}} -) ;;;; Assertions within data structures -(comment - ;;; Compare (have vector? [:a :b :c]) ; => [:a :b :c] (have keyword? :in [:a :b :c]) ; => [:a :b :c] -) ;;;; Assertions within :pre/:post conditions -(comment - (defn square [n] ;; Note the use of `have?` instead of `have` {:pre [(have? #(or (nil? %) (integer? %)) n)] @@ -179,12 +163,9 @@ (square 5) ; => 25 (square nil) ; => 1 -) ;;;; Special predicates -(comment - ;; A predicate can be anything (have #(and (integer? %) (odd? %) (> % 5)) 7) ; => 7 @@ -212,12 +193,9 @@ ;; Non-nil keys (have [:ks-nnil? #{:a :b}] {:a "A" :b nil :c "C"}) ; => Error -) ;;;; Writing custom validators -(comment - ;; A custom predicate: (defn pos-int? [x] (and (integer? x) (pos? x))) @@ -233,15 +211,12 @@ (have-person {:name "Steve" :age 33}) ; => {:name "Steve", :age 33} (have-person {:name "Alice" :age "33"}) ; => Error -) ;;;; Assertions without elision -(comment (defn get-restricted-resource [ring-session] ;; This is an important security check so we'll use `have!` here instead of ;; `have` to make sure the check is never elided (skipped): (have! string? (:auth-token ring-session)) "return-restricted-resource-content") -) diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md index 86db25c..77803c5 100644 --- a/wiki/1-Getting-started.md +++ b/wiki/1-Getting-started.md @@ -70,7 +70,7 @@ What varies is the return value, and whether elision is possible. # Examples -> All examples are from [`/examples/truss_examples.cljc`](../blob/master/examples/truss_examples.cljc) +> All examples are from [`/examples.cljc`](../blob/master/examples.cljc) Truss's sweet spot is often in longer, complex code (difficult to show here). So these examples are mostly examples of **syntax**, not **use case**. In particular, they mostly focus on simple **argument type assertions** since those are the easiest to understand. @@ -99,7 +99,7 @@ A Truss `(have )` form will either throw or return the given argumen ;; {:ns truss-examples, ;; :line 41, ;; :column 1, -;; :file "examples/truss_examples.cljc"}} +;; :file "examples.cljc"}} ;; Truss also automatically traps and handles exceptions (have string? (/ 1 0)) ; => @@ -117,7 +117,7 @@ A Truss `(have )` form will either throw or return the given argumen ;; {:ns truss-examples, ;; :line 54, ;; :column 1, -;; :file "examples/truss_examples.cljc"}, +;; :file "examples.cljc"}, ;; :err ;; #error ;; {:cause "Divide by zero" @@ -148,7 +148,7 @@ A Truss `(have )` form will either throw or return the given argumen ;; {:ns truss-examples, ;; :line 89, ;; :column 15, -;; :file "examples/truss_examples.cljc"}} +;; :file "examples.cljc"}} ``` ## Attaching debug data @@ -170,7 +170,7 @@ You can attach arbitrary debug data to be displayed on violations: ;; {:ns truss-examples, ;; :line 107, ;; :column 15, -;; :file "examples/truss_examples.cljc"}, +;; :file "examples.cljc"}, ;; :data {:dynamic nil, :arg {:ring-req {:foo :bar}}}} ``` @@ -208,7 +208,7 @@ And you can attach shared debug data at the `binding` level: ;; {:ns truss-examples, ;; :line 136, ;; :column 3, -;; :file "examples/truss_examples.cljc"}, +;; :file "examples.cljc"}, ;; :data {:dynamic {:ring-session {:user-name "Stu"}}, :arg nil}} ```