puppetlabs.kitchensink.core — puppetlabs/kitchensink 3.2.0

absolute-path clj

(absolute-path path)

Replacement for raynes.fs/absolute-path, which was removed in raynes.fs 1.4.6. Returns string representation of absolute path, as opposed to fs/absolute, which returns a File object.

add-shutdown-hook! clj

(add-shutdown-hook! f)

Adds a shutdown hook to the JVM runtime.

f is a function that takes 0 arguments; the return value is ignored. This function will be called if the JVM receiveds an interrupt signal (e.g. from kill or CTRL-C); you can use it to log shutdown messages, handle state cleanup, etc.

array? clj

(array? x)

Returns true if x is an array

as-collection clj

(as-collection item)

(as-collection item constructor)

Returns the item wrapped in a collection, if it's not one already. Returns a list by default, or you can use a constructor func as the second arg.

ascii-character-sets clj

assoc-if-new clj macro

(assoc-if-new map key val & kvs)

Assocs the provided values with the corresponding keys if and only if the key is not already present in map.

base-type clj

(base-type content-type)

Parse a base type out of a Content-Type, returns nil if there's no match. Does not validate any parameters.

boolean? clj

(boolean? value)

Returns true if the value is a boolean

bounded-memoize clj

(bounded-memoize f bound)

Similar to memoize, but the cache will be reset if the number of entries exceeds the specified bound.

cli! clj

(cli! args specs)

(cli! args specs required-args)

Validates that required command-line arguments are present. If they are not, throws a map** with an error message that is intended to be displayed to the user. Also checks to see whether the user has passed the --help flag.

Input:

• args : the command line arguments passed in by the user
• specs : an array of supported argument specifications, as accepted by clojure.tools.cli
• required : an array of keywords (using the long form of the argument spec) specifying which of the specs are required. If any of the required options are not present, the function will cause the program to exit and display the help message.

** The map is thrown using 'slingshot' (https://github.com/scgilardi/slingshot). It contains a :kind and :msg, where type is either :error or :help, and the message is either the error message or a help banner.

Returns a three-item vector, containing:

• a map of the parsed options
• a vector containing the remaining cli arguments that were not parsed
• a string containing a summary of all of the options that are available; for use in printing help messages if the user detects that the arguments are still invalid in some way.

cn-for-cert clj

(cn-for-cert cert)

Deprecated. Use functions from jvm-certificate-authority.

Extract the CN from the DN of an x509 certificate. See cn-for-dn for details on how extraction is performed.

If no CN exists in the certificate DN, nil is returned.

cn-for-dn clj

(cn-for-dn dn)

Deprecated. Use functions from jvm-certificate-authority.

Extracts the CN (common name) from an LDAP DN (distinguished name).

If more than one CN entry exists in the given DN, we return the most-specific one (the one that comes last, textually). If no CN is present in the DN, we return nil.

Example:

(cn-for-dn "CN=foo.bar.com,OU=meh,C=us")
"foo.bar.com"

(cn-for-dn "CN=foo.bar.com,CN=baz.goo.com,OU=meh,C=us")
"baz.goo.com"

(cn-for-dn "OU=meh,C=us")
nil

cn-whitelist->authorizer clj

(cn-whitelist->authorizer whitelist)

Given a 'whitelist' file containing allowed CNs (one per line), build a function that takes a Ring request and returns true if the CN contained in the client certificate appears in the whitelist.

whitelist can be either a local filename or a File object.

This makes use of the :ssl-client-cn request parameter. See com.puppetlabs.middleware/wrap-with-certificate-cn.

compare-jvm-versions clj

(compare-jvm-versions a b)

Same behavior as compare, but specifically for JVM version strings. Because Java versions don't follow semver or anything, we need to do some massaging of the input first:

http://www.oracle.com/technetwork/java/javase/versioning-naming-139433.html

compose-comparators clj

(compose-comparators comp-fn1 comp-fn2)

Composes two comparator functions into a single comparator function which will call the first comparator and return the result if it is non-zero; otherwise it will call the second comparator and return its result.

cond-let clj macro

(cond-let bindings & clauses)

Takes a binding-form and a set of test/expr pairs. Evaluates each test one at a time. If a test returns logical true, cond-let evaluates and returns expr with binding-form bound to the value of test and doesn't evaluate any of the other tests or exprs. To provide a default value either provide a literal that evaluates to logical true and is binding-compatible with binding-form, or use :else as the test and don't refer to any parts of binding-form in the expr. (cond-let binding-form) returns nil.

contains-some clj

(contains-some coll ks)

If coll contains? any of the keys in ks, returns the first such key. Otherwise returns nil.

create-section-map clj

(create-section-map section)

Given an INI section, create a clojure map of it's key/values

datetime? clj

(datetime? x)

Predicate returning whether or not the supplied object is convertible to a Joda DateTime

deep-merge clj

(deep-merge & vs)

Deeply merges maps so that nested maps are combined rather than replaced.

For example: (deep-merge {:foo {:bar :baz}} {:foo {:fuzz :buzz}}) ;;=> {:foo {:bar :baz, :fuzz :buzz}}

;; contrast with clojure.core/merge (merge {:foo {:bar :baz}} {:foo {:fuzz :buzz}}) ;;=> {:foo {:fuzz :quzz}} ; note how last value for :foo wins

deep-merge-with clj

(deep-merge-with f & vs)

Deeply merges like deep-merge, but uses f to produce a value from the conflicting values for a key in multiple maps.

deep-merge-with-keys clj

(deep-merge-with-keys f & vs)

Deeply merges like deep-merge, but uses f to produce a value from the conflicting values for a key path ks that appears in multiple maps, by calling (f ks val-in-result val-in-latter).

deep-merge-with-keys* clj

(deep-merge-with-keys* f ks & vs)

Helper function for deep-merge-with-keys

delete-on-exit clj

(delete-on-exit f)

Will delete f on shutdown of the JVM

demarcate clj macro

(demarcate msg & body)

Executes body, but logs msg to info before and after body is executed. body is executed in an implicit do, and the last expression's return value is returned by demarcate.

user> (demarcate "reticulating splines" (+ 1 2 3)) "Starting reticulating splines" "Finished reticulating splines" 6

deref-swap! clj

(deref-swap! atom f & args)

Like swap! but returns the old value. Adapted from http://stackoverflow.com/a/15442107.

dissoc-if-nil clj

(dissoc-if-nil m k)

(dissoc-if-nil m k & ks)

Given a map and a key, checks to see if the value for the key is nil; if so, returns a modified map with the specified key removed. If the value is not nil, simply returns the original map.

dissoc-in clj

(dissoc-in m [k & ks])

Dissociates an entry from a nested map. ks is a sequence of keys. Any empty maps that result will not be present in the new map.

enumerate clj

(enumerate coll)

Returns a lazy sequence consisting of 0 and the first item of coll, followed by 1 and the second item in coll, etc, until coll is exhausted.

error-map clj

(error-map kind message)

excludes-some clj

(excludes-some coll ks)

If coll excludes? any of the keys in ks, returns the first such key. Otherwise returns nil.

excludes? clj

Inverse of contains?. Returns false if key is present in the given collectoin, otherwise returns true.

fetch-int clj

(fetch-int section key)

Fetch a key from the INI section and convert it to an integer if it parses, otherwise return the string

file->sha256 clj

(file->sha256 file)

Compute a SHA-256 hash for the given java.io.File object. Uses an InputStream to read the file, so it doesn't load all the contents into memory at once.

filter-map clj

(filter-map pred m)

Like 'filter', but works on maps. Returns a map containing the key-value pairs in 'm' for which 'pred' returns a truth-y value. 'pred' must be a function which takes two arguments.

ini-to-map clj

(ini-to-map filename)

Takes a .ini filename and returns a nested map of fully-interpolated values. Strings that look like integers are returned as integers, and all section names and keys are returned as symbols.

inis-to-map clj

(inis-to-map path)

(inis-to-map path glob-pattern)

Takes a path and converts the pointed-at .ini files into a nested map (see ini-to-map for details). If path is a file, the behavior is exactly the same as ini-to-map. If path is a directory, we return a merged version of parsing all the .ini files in the directory (we do not do a recursive find of .ini files).

java-version clj

Returns a string of the currently running java version

keep-going clj macro

(keep-going on-error & body)

Executes body, repeating the execution of body even if an exception is thrown

keep-going* clj

(keep-going* f on-error)

Executes the supplied fn repeatedly. Execution may be stopped with an InterruptedException.

key->str clj

(key->str kw)

Convert a keyword to a string, stripping the leading : character. This is distinct from the name function as it will preserve the 'namespace' portion before a slash. If the key is already a string, it is returned unmodified.

keyset clj

(keyset m)

Returns the set of keys from the supplied map

keywordize clj

Normalize INI keys by ensuring they're lower-case and keywords

lines clj

(lines filename)

Returns a sequence of lines from the given filename

mapkeys clj

(mapkeys f m)

Return map m, with each key transformed by function f

maptrans clj

(maptrans keys-fns m)

Return map m, with values transformed according to the key-to-function mappings specified in keys-fns. keys-fns should be a map whose keys are lists of keys from m, and whose values are functions to apply to those keys.

Example: (maptrans {[:a, :b] inc [:c] dec} {:a 1 :b 1 :c 1}) yields {:a 2, :c 0, :b 2}

mapvals clj

(mapvals f m)

(mapvals f ks m)

Return map m, with each value transformed by function f.

You may also provide an optional list of keys ks; if provided, only the specified keys will be modified.

merge-with-key clj

(merge-with-key f & maps)

Returns a map that consists of the rest of the maps conj-ed onto the first. If a key k occurs in more than one map, the mapping(s) from the latter (left-to-right) will be combined with the mapping in the result by calling (f k val-in-result val-in-latter).

missing? clj

(missing? coll & keys)

Inverse of contains? that supports multiple keys. Will return true if all items are missing from the collection, false otherwise.

Example:

;; Returns true, as :z :f :h are all missing
(missing? {:a 'a' :b 'b' :c 'c'} :z :f :h)

;; Returns false, as :a is in the collection
(missing? {:a 'a' :b 'b' :c 'c'} :z :b)

mkdirs! clj

(mkdirs! path)

Given a path (may be a File or a string), creates a directory (including any missing parent directories). Throws a slingshot exception with a meaningful error message if the directory cannot be created.

(The reason for the existence of this function is that the Java File.mkdirs method only returns a boolean indicating whether the directory was created; if you get back a false, you have no idea whether it failed due to permission errors, or the path being invalid in some way, or the directory already exists.)

The slingshot exception will look like this:

{:kind :puppetlabs.kitchensink.core/io-error :msg "Parent directory '/foo/bar' is not writable"}

normalized-path clj

(normalized-path path)

Replacement for raynes.fs/normalized-path, which was removed in raynes.fs 1.4.6. Returns string representation of absolute path, as opposed to fs/normalized, which returns a File object.

num-cpus clj

(num-cpus)

Grabs the number of available CPUs for the local host

open-port-num clj

(open-port-num)

Returns a currently open port number in the port range 16384 through 32767. Note that on Linux, anything above 32767 lies in the ephemeral port range, which is the range that the system uses to allocate ports upon user request. Thus, we choose from a different range to prevent possible port conflicts caused by various services (e.g. database connection pools).

order-by clj

(order-by order-bys coll)

Sorts a collection based on a sequence of 'order by' expressions. Each expression is a tuple containing a fn followed by either :ascending or :descending; returns a collection that is sorted based on the values of the 'order by' fns being applied to the elements in the original collection. If multiple 'order by' expressions are passed in, their precedence is determined by their order in the argument list.

order-by-expr? clj

(order-by-expr? x)

Predicate that returns true if the argument is a valid expression for use with the order-by function; in other words, returns true if the argument is a 2-item vector whose first element is an ifn and whose second element is either :ascending or :descending.

ordered-comparator clj

(ordered-comparator f order)

Given a function and an order (:ascending or :descending), return a comparator function that takes two objects and compares them in ascending or descending order based on the value of applying the function to each.

parse-bool clj

(parse-bool s)

Parse a string and return its boolean value.

parse-float clj

(parse-float s)

Parse a string s as a float, returning nil if the string doesn't contain a float

parse-ini clj

(parse-ini ini-reader)

Takes a io/reader that contains an ini file, and returns an Ini object containing the parsed results

parse-int clj

(parse-int s)

Parse a string s as an integer, returning nil if the string doesn't contain an integer.

parse-interval clj

(parse-interval time-str)

Given a time string of the form "<number>", or "<number><unit>", this function parses this time amount and returns a joda time Period instance. If the unit is left off, the units are assumed to be time/seconds

Example: "12h" -> (clj-time.core/hours 12) Example: "12" -> (clj-time.core/seconds 12)

Possible units: s(econds), m(inutes), h(ours), d(ays), y(ears)

Returns nil if the time string cannot be parsed.

parse-number clj

(parse-number s)

Converts a string s to a number, by attempting to parse it as an integer and then as a float. Returns nil if the string isn't numeric.

pprint-to-string clj

(pprint-to-string x)

quotient clj

(quotient dividend divisor)

(quotient dividend divisor default)

Performs division on the supplied arguments, substituting default when the divisor is 0

rand-str clj

(rand-str n)

(rand-str characters n)

Produces a random string of length n, drawn from the given collection of characters. The following keywords may be used in place of a character collection: :alpha - [a-zA-Z] :alpha-lower - [a-z] :alpha-upper - [A-Z] :alpha-digits - [a-zA-Z0-9] :alpha-digits-symbols - all printable ASCII characters besides space :symbols - all visible, non-alpha-numeric ASCII characters (no space) :digits - [0-9] If no character collection or keyword is provided, :alpha-digits-symbols is used by default.

rand-weighted-selection clj

(rand-weighted-selection & weights-and-values)

Given alternating numeric weights and values, produces a randomly-selected value according to the weights, which should sum to one. If the weights sum to less than one, then the last value will have its weight adjusted upwards accordingly. If the weights sum to more than one, then values after the cumulative sum of the weights exceeds one will never be selected.

regexp? clj

(regexp? regexp)

Returns true if the type is a regexp pattern

select-values clj

Returns the sequence of values from the map for the entries with the specified keys

seq-contains? clj

(seq-contains? seq elm)

True if seq contains elm

some-pred->> clj macro

(some-pred->> pred expr & forms)

When expr does not satisfy pred, threads it into the first form (via ->>), and when that result does not satisfy pred, through the next etc

sort-nested-maps clj

(sort-nested-maps data)

For a data structure, recursively sort any nested maps and sets descending into map values, lists, vectors and set members as well. The result should be that all maps in the data structure become explicitly sorted with natural ordering. This can be used before serialization to ensure predictable serialization.

The returned data structure is not a transient so it is still able to be modified, therefore caution should be taken to avoid modification else the data will lose its sorted status.

spit-ini clj

(spit-ini file ini-map)

Writes the ini-map to the Ini file at file. ini-map should a map similar to the ones created by ini-to-map. The keys are keywords for the sections and their values are maps of config keypairs.

stream->sha256 clj

(stream->sha256 stream)

Compute a SHA-256 hash for the given java.io.InputStream object.

strict-parse-bool clj

(strict-parse-bool s)

Parse a string and return its boolean value; throws an exception if the String does not match "true" or "false" (case-insensitive).

string-contains? clj

(string-contains? substring s)

Returns true if s has the substring in it

symmetric-difference clj

(symmetric-difference s1 s2)

Computes the symmetric set/difference between 2 sets

temp-dir clj

(temp-dir & args)

Creates a temporary directory that will be deleted on JVM shutdown.

Supported arguments are the same as for me.raynes.fs/temp-dir: [prefix] [prefix suffix] [prefix suffix tries]

You may also call with no arguments, in which case the prefix string will be empty.

temp-file clj

(temp-file & args)

Creates a temporary file that will be deleted on JVM shutdown.

Supported arguments are the same as for me.raynes.fs/temp-file: [prefix] [prefix suffix] [prefix suffix tries]

You may also call with no arguments, in which case the prefix string will be empty.

temp-file-name clj

(temp-file-name file-name-prefix)

Returns a unique name to a temporary file, but does not actually create the file.

timestamp clj

(timestamp)

(timestamp time)

Returns a timestamp string for the given time, or the current time if none is provided. The format of the timestamp is eg. 2012-02-23T22:01:39.539Z.

to-bool clj

(to-bool val)

Converts the argument to a boolean. The behavior is as follows:

• If the argument is a Boolean, it is simply returned.
• If the argument is a String, returns the Boolean true if the String matches "true" (case insensitive), or false if the String matches "false" (case insensitive). Throws an exception otherwise.
• If the argument is nil, returns false.

to-sentence clj

(to-sentence strings)

Join the given strings as they would be listed in a sentence (using an Oxford comma if there are three or more strings). Examples: ["apple"] => "apple" ["apple" "orange"] => "apple and orange" ["apple" "orange" "banana"] => "apple, orange, and banana"

true-str? clj

(true-str? s)

Return true if the string contains true

utf8-string->sha1 clj

(utf8-string->sha1 s)

Compute a SHA-1 hash for the UTF-8 encoded version of the supplied string

utf8-string->sha256 clj

(utf8-string->sha256 s)

Compute a SHA-256 hash for the UTF-8 encoded version of the supplied string

uuid clj

(uuid)

Generate a random UUID and return its string representation

uuid? clj

(uuid? uuid)

Verifies whether a string is a valid UUID

valset clj

(valset m)

Returns the set of values from the supplied map

walk-leaves clj

(walk-leaves m f)

Walk a map applying a function to all leaf nodes

while-let clj macro

(while-let bindings & body)

Repeatedly executes body while test expression is true, evaluating the body with binding-form bound to the value of test.

with-error-delivery clj macro

(with-error-delivery error & body)

Executes body, and delivers an exception to the provided promise if one is thrown.

with-timeout clj macro

(with-timeout timeout-s default & body)

without-ns clj

(without-ns kw)

Given a clojure keyword that is optionally namespaced, returns a keyword with the same name but with no namespace.

zipper? clj

(zipper? obj)

Checks to see if the object has zip/make-node metadata on it (confirming it to be a zipper.