The Bitumen Framework Handbook

Random numeric and string values may be required for various purposes while programming. The random-number and random-string functions cater for these.

(random-number)

(str "invoices-2011-02-20-" (random-number))

;; return a random number between 10 (included) and 20 (excluded)
(random-number 10 20)

(let [v [1 2 3 4 5 6 7 8 9]]
  (v (int (random-number 0 (count v)))))

(random-string)     ; string of random 11-13 characters

(random-string 20)  ; string of 20 random characters

(random-charseq)     ; lazy seq of infinite random characters

(random-charseq 10)  ; lazy seq of 10 random characters

Clojure core has some built in functions to determine the types of values, such as number?, string?, map? etc. Additional such functions not available in Clojure core are below:

(boolean? false)       ; returns true
(boolean? "hello")     ; returns false

(not-boolean? "hello") ; returns true
(not-boolean? true)    ; returns false

(date? (java.util.Date.))      ; returns true
(date? "hello")                ; returns false

(not-date? (java.util.Date.))  ; returns false
(not-date? "hello")            ; returns true

These are some pretty printing functions that you can use:

with-stringwriter

This macro is used to assign a StringWriter to specified symbol in a let binding and execute body of code in that context. Returns the string from StringWriter . Example:

(with-stringwriter s
  (.append s "Hello")
  (.append s "World"))  ; returns "HelloWorld"

with-err-str

This macro is like with-out-str but for *err* instead of *out*.

pprint-str

This function (accepts one argument) prints anything that you pass to it using clojure.pprint/pprint and returns the result as string.

comma-sep-str

This function accepts a collection as argument and returns a comma separated string representation.

echo

This function is a simple diagnostic tool that pretty-prints anything (single argument) you pass to it and returns the same argument.

Detecting sign of numbers may be tricky. (pos? 34) returns true as expected, but (pos? "Hello") throws ClassCastException. The alternatives below return false in event of exceptions.

(zeronum? 0)        ; return true
(zeronum? 36)       ; return false
(zeronum? "hello")  ; returns false

(posnum? 378)       ; returns true
(posnum? -32)       ; returns false
(posnum? :pqrs)     ; returns false

(negnum? 378)       ; returns false
(negnum? -32)       ; returns true
(negnum? :pqrs)     ; returns false

Printing tables of data is useful for many scenarios. The data to be printed as a table is generally a collection of rows, optionally with a header row. You can use the print-table function to print a table of data to *out*.

(print-table [{:a 10 :b 20 :c 30}
              {:a 40 :b 50 :c 60}
              {:a 70 :b 80 :c 90}])  ; with titles "a", "b" and "c"

(print-table [[10 20 30]
              [40 50 60]
              [70 80 90]])           ; without any titles

(print-table  [:a :b :c]
             [[10 20 30]
              [40 50 60]
              [70 80 90]])           ; with titles "a", "b" and "c"

The examples above use the defaults to print the tables. You can override the defaults to alter the way tables are printed. For example, every column width is computed by default, if you want to specify width of columns you can use something like this:

(binding [*pt-cols-width* [5 -1 7]]
  (print-table [{:id 1001 :name "Harry"    :gender :male}
                {:id 2997 :name "Samantha" :gender :female}
                {:id 8328 :name "Christie" :gender :female}]))

Other options you can override are as follows:

*pt-column-delim*   -- column delimiter string
*pt-min-cols-width* -- collection of minimum width for each column
*pt-max-cols-width* -- collection of maximum width for each column
*pt-cols-width*     -- collection of numeric width for each column

Note: One notable feature of *pt-cols-width* is that a non-positive number implies that the width would be automatically computed.

Details about vars can be very useful during debugging, diagnostics or error reporting. You can find out the name (string) of a var using the macro var-name, fn-body of the var using var-body function and type/value of a value using the val-dump function.

(var-name map?)  ; returns "map?"

(var-body map?)  ; returns source code for map? function

(val-dump #"[a-z0-9]")  ; returns type and value as string

Throwing exceptions with sufficient diagnostic context in them is very important for meaningful error reporting. The functions shown below let you throw exceptions with relevant context:

Examples of these functions are as follows:

(illegal-arg "name should not have more than 3 vowels")

(try (get-fname empname)
  (catch Exception e
    (illegal-arg-wrap e (str "bad empname: " empname))))

(illegal-argval "empname" "string having 3 vowels or less" empname)

(illegal-state "Value of x cannot be > " max-x)

;; assuming e is an exception
(illegal-state-wrap e "Fahrenheit cannot be more than 98.4 degrees")

(unsupported-op "Not yet implemented")

;; assuming e is an exception
(unsupported-op e "Attempt to carry out activity failed")

When executing code that might throw an exception we generally wrap it in a try/catch block as we want to deal with the breakage in execution flow. Dealing with execution breakage in-place makes the code imperative and often brittle.

(maybe (pos? 648)) ; returns [true nil]
(maybe (pos? nil)) ; returns [nil <NullPointerException instance>]

(doseq [[ret ex] (map #(maybe (process-order %)) orders)]
  (or ret (log/success ret))
  (or ex  (do (log/error ex)
            (trigger-alert ex))))

(maybe-ret (Integer/parseInt "45"))    ; returns 45
(maybe-ret (Integer/parseInt "hello")) ; returns nil

(maybe-ex (Integer/parseInt "45"))     ; returns nil
(maybe-ex (Integer/parseInt "hello"))  ; returns NumberFormatException

(filter-exception #(instance? ClassCastException %)
  (pos? "hello"))  ; returns nil

;; throws exception
(with-exceptions [IllegalArgumentException IllegalStateException]
                 [RuntimeException]
  "foo" ; non-effective return value
  (throw (IllegalArgumentException. "dummy")))

;; swallows exception
(with-exceptions [IllegalArgumentException IllegalStateException]
                 [RuntimeException]
  "foo" ; non-effective return value
  (throw (NullPointerException. "dummy")))

Type conversion is one of the most frequent needs during data processing. The table below describes which function converts to which type. All functions in this section accept input in various formats and try to coerce the input into desired type.

Quite often we use a (not ..) version of a boolean function, e.g. (not (map? foo)) while checking for conditions. The functions listed below are shorthand of using with not:

Transforming collections can be easily done using map or for. However, transforming maps always involves destructuring the key and value and then apply any transformation. The functions map-keys and map-vals let you simply transform either the keys or the values of a map. When using map-keys you must ensure that the transformed set of keys are unique.

(map-keys inc (array-map 1 2 3 4 5 6)) ; returns {2 2 4 4 6 6}

(map-vals dec (array-map 1 2 3 4 5 6)) ; returns {1 1 3 3 5 5}

Dealing with arrays may become unavoidable when working with Java libraries. The following functions may help:

array-type

array-type returns the common type (class) of elements that can be contained in the array.

array?

array? returns true if the argument is an array, false otherwise.

not-array?

not-array? is same as (not (array? foo)).

The contains? function in clojure.core looks for a key in a collection. For a vector the keys are the indices, for sets they are the elements and for maps they are keys. The contains-val? function looks for values instead of keys.

(contains?     [:a :b :c] :b) ; returns false
(contains-val? [:a :b :c] :b) ; returns true

(contains?     {:a 10 :b 20} 20) ; returns false
(contains-val? {:a 10 :b 20} 20) ; returns true

Exception stack trace for Clojure code usually includes quite some unwanted entries, which are not very useful while debugging and rather clutter the view. The function print-exception-stacktrace can be used to print an exception stack trace with reduced clutter. It falls back to the following as stack trace elements (in that order):

When trying this on the REPL with Clojure core/contrib libraries, you may not encounter #1 in the stack trace.

There are two convenience macros - ! and !! that accept a body of code and print friendly stack trace if there is any exception. The difference between the two is that ! prints only required columns of the stack trace and !! prints an additional IDE Reference column to generate filenames clickable within the IDE (tested on Eclipse and IDEA). Example is below:

(! (foo arg))   ; prints normal stack-trace columns

(!! (foo arg))  ; prints extra IDE reference column

verify-arg

Throws IllegalArgumentException if body of code does not return true.

(verify-arg (map? arg)) ; verifies arg is a map

verify-type

Throws IllegalArgumentException if argument does not match expected type.

(verify-type java.util.Date join-date)

verify-cond

This macro is same as verify-arg but throws IllegalStateException instead of IllegalArgumentException.

verify-opt

This function ensures that only permitted optional arguments are passed as optional arguments to a function or macro.

(defn foo
  [arg & {:keys [a b] :as opt}] {:pre [(verify-opt [:a :b] opt)]}
  ...)

Type annotation is a way to inject type metadata into regular objects without altering their content. The type metadata can be read back later to act upon them in different ways.

(typed [:argentina :spain]
  :speaks-spanish)                 ; tag the object with one type

(typed {:name "Henry"
        :age   23
        :place "Connecticut"}
  :person-data :has-age :has-name) ; tag object with multiple types

(typed 65 :average-weight)         ; throws exception - 65 is not object

(ftyped 65 :average-weight)        ; this works fine

(let [d (ftyped 60 :retirement-age)] (d))

(type-meta (typed {:order-id 34}
             :pending))              ; returns :pending

(type-meta (typed [:france :germany]
             :european :countries))  ; returns [:european :countries]

(type-meta (typed (typed [10 20]
                    :numbers)
             :sample))               ; returns [:numbers :sample]

(type-meta (untyped (typed {:a 10 :b 20} :abc))) ; returns nil

(derive ::employee ::salaried) ; employee is salaried
(derive ::salaried ::person)   ; salaried is a person

;; returns true because ::employee is both ::salaried and ::person
(every? #(typed? (typed {:id 3964 :name "Joe"}
                   ::employee) %)
  [::salaried ::person])

;; returns true because ::employee is at least ::person
(some   #(typed? (typed {:id 9604 :name "Cher"}
                   ::employee) %)
  [::freelancer ::person])

The keyword/string conversion functions would be best shown with examples:

(k-to-camelstr :to-do) ; returns "toDo"
(camelstr-to-k "toDo") ; returns :to-do

(k-to-methodname :to-do ["add"]) ; returns "addToDo" (now see k-to-camelstr)
(k-to-setter :price)       ; returns "setPrice"
(k-to-setter :set-price)   ; returns "setPrice" (detects "set", no repeat)
(k-to-getter :price)       ; returns "getPrice"
(k-to-getter :get-price)   ; returns "getPrice"  (detects "get", no repeat)
(k-to-getter :is-in-stock) ; returns "isInStock" (detects "is" too)

(coll-as-string [:a :b :c])    ; returns ["a" "b" "c"]
(coll-as-keys   ["a" "b" "c"]) ; returns [:a :b :c]
(keys-to-str {:a 10 :b 20})    ; returns {"a" 10 "b" 20}
(str-to-keys {"a" 10 "b" 20})  ; returns {:a 10 :b 20}

The examples below show how to use the API:

(method "Hello" :char-at 0) ; .charAt(0) - returns \H

(method (call-specs "Hello"
          [:char-at 0]     ; .charAt(0)       - returns \H
          [:substring 3 4] ; .substring(3, 4) - returns "l"
          [:to-string]     ; .toString()      - returns "Hello"
          ))

(map #((apply pojo-fn "Hello" %))
  [[:char-at 0]     ; returns primitive char
   [:substring 3 4] ; returns string
   [:to-string]     ; no-arg method
   ]) ; returns lazy (\H "l" "Hello")

(setter (StringBuilder.)
  :length 0) ; .setLength(0) - returns void, 'setter' returns nil

(setter (call-specs sb
          [:length 4]     ; .setLength(4)      - returns void
          [:char-at 0 \C] ; .setCharAt(0, 'C') - returns void
          )) ; 'setter' returns [nil nil]

(map #((apply setter-fn sb %))
  [[:length 4]     ; .setLength(4)      - returns void
   [:char-at 0 \C] ; .setCharAt(0, 'C') - returns void
   ]) ; returns lazy (nil nil)

(let [lst (java.util.LinkedList.)
      _   (.add lst 1)
      _   (.add lst 2)]
  (getter lst :first) ; .getFirst() - returns 1
  (getter (call-specs lst :first ; .getFirst() - returns 1
                          :last  ; .getLast()  - returns 2
                          )) ; returns [1 2]
  (map (getter-fn lst) [:first ; .getFirst() - returns 1
                        :last  ; .getLast()  - returns 2
                        ])) ; returns lazy (1 2)

Assuming that the file sample.properties has the following content:

a=10
b=20
c=true

Properties can be transformed into maps:

(let [ps (read-properties "src/test/conf/sample.properties")]
  (property-map ps)     ; returns {"a" "10" "b" "20" "c" "true"}
  (strkey-to-keyword
    (property-map ps))) ; returns {:a "10" :b "20" :c "true"}

(is-true? "true") ; returns true (useful to test bool values in properties)

These JNDI tree-printing functions can be used to debug the JNDI configuration:

(print-jndi-tree) ; print the JNDI tree referring initial context

(find-jndi-subcontext (javax.naming.InitialContext.)
         "java:comp") ; returns javax.naming.Context (if configured)

(jndi-lookup
  "java:comp/env/myDataSource") ; returns javax.sql.DataSource (if configured)