Skip to content
This repository was archived by the owner on Apr 16, 2021. It is now read-only.

Commit 603cc60

Browse files
coconutpalmcoconutpalm
authored
Merge pull request #22 from shopsmart/err-to-warn
Fix dangling test dependencies; add codox.
2 parents 739dcb3 + b20cbf2 commit 603cc60

17 files changed

+284
-33
lines changed

‎doc/intro.md

+169-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,171 @@
11
# Introduction to clj-foundation
22

3-
TODO: write [great documentation](http://jacobian.org/writing/what-to-write/)
3+
Clojure has a great standard library. Even so, some things could be easier than they are.
4+
5+
## Why clj-foundation?
6+
7+
clj-foundation supplies namespaces making additional simple things easy and hard things possible in Clojure for functions needed across all Clojure projects at Brad's Deals.
8+
9+
The following describe our core goals/values for clj-foundation:
10+
11+
* Enhances the core language in resonable, useful, and conservative ways.
12+
* Not a framework. Rather, a conservative set of generally-useful functions that may be used together or separately.
13+
* Makes it easy to create new transducers (or pipelines of transducers) from any regular function.
14+
* Where applicable, enables programming using a monadic style without requiring explicit monad types.
15+
* Clojure already polymorphically supports mapcat over most core data types. The missing thing is an implementation of the monadic zero as a separate and distinct thing from nil.
16+
* Describes, specifies, and illustrates best practices at Brad's Deals for working in Clojure.
17+
* The only dependencies are Clojure.*, Potemkin, io.aviso/pretty (for better stack traces), and Schema in order to minimize adoption friction. In the near future we will migrate from Schema to Specs.
18+
19+
20+
## Other Clojure foundational libraries that compliment this one
21+
22+
* Immutant: http://immutant.org/
23+
* Hara: http://docs.caudate.me/hara/index.html
24+
25+
26+
## High-quality domain-specific libraries complimenting this
27+
28+
* Cassandra as a mutable, versioned map: https://github.com/MyPost/cassius
29+
* Git from the Clojure REPL: https://github.com/zcaudate/gita
30+
31+
32+
## Curated directories of Clojure libraries
33+
34+
* http://clojurewerkz.org
35+
* http://blog.takipi.com/the-top-100-clojure-libraries-in-2016-after-analyzing-30000-dependencies/
36+
* https://github.com/razum2um/awesome-clojure
37+
* http://www.clojure-toolbox.com/
38+
39+
40+
# Features
41+
42+
The folowing is a small sample of clj-foundation's features:
43+
44+
## Math
45+
46+
* A Mixed Number type
47+
* Time conversions to/from milliseconds
48+
* (str (millis/->dmhs elapsed-time)) => e.g.: "5 days 2 hours 3 minutes 2 seconds"
49+
* A Nothing type that behaves like the identity value for Maps, Seqs, and Strings and is distinct from nil.
50+
* Functions converting identity values of various types/operations to and from nil.
51+
52+
53+
## Ever had to declare a map containing the result of let variable bindings? Now you can do that in one step with let-map.
54+
55+
```clojure
56+
(let-map [meaning 42
57+
secrets (io/read-file "/etc/passwd")])
58+
==>
59+
{:meaning 42
60+
:secrets "nobody:*:-2:-2:Unprivileged User:/var/empty:/usr/bin/false\nroot:*:0:0:System Administrator:/var/root:/bin/sh\n...."}
61+
```
62+
63+
## Data/error processing enhancements and timeout handling.
64+
65+
```clojure
66+
;; Replace a nil value with a default
67+
(replace-nil (:first-name customer) "John")
68+
69+
;; Returns value if non-nil else throws IllegalArgumentException naming the nil value
70+
(not-nil (:first-name customer) "First name")
71+
72+
;; Expect a condition specified by a predicate to become true within timeout-millis.
73+
;; Throws IllegalStateException on failure with the specified message.
74+
(expect-within
75+
(millis/<-seconds 5)
76+
(fn [] (= (meaning-of-life) 42))
77+
"Couldn't compute the meaning of life.")
78+
79+
;; Retry x times, with millis puase interval a specified function that is failure-prone
80+
(retry 5 (millis/<-seconds 10) some-unreliable-io-operation)
81+
```
82+
83+
## A string interpolation language that is intentionally dumb about the syntax of its hosting language.
84+
85+
```clojure
86+
;; Given:
87+
(def content "Say hello to ${NAME}")
88+
89+
;; Then:
90+
(templates/subst<- content :NAME "Jack")
91+
==>
92+
"Say hello to Jack"
93+
94+
(subst<- content :ZIP "46989")
95+
==>
96+
ExceptionInfo Not found: '${NAME}' clojure.core/ex-info
97+
98+
(interpolation-vars content)
99+
==>
100+
(:NAME)
101+
```
102+
103+
* Interpolation variables are resolved from the following places with the following precedence:
104+
* Java system variables (e.g.: java -DNAME='Jack' com.foo.bar.YourMainProgram)
105+
* Operating system environment variables
106+
* Any key/value variables specified in code.
107+
108+
## Extensions to Clojure's file input functions
109+
110+
```clojure
111+
;; Return a Jar resource as a string
112+
(resource-as-string "config.txt")
113+
114+
;; Return a Jar resource as a string, but allow the ALT_CONFIG_LOCATION Java system or O/S environment
115+
;; variable to redirect reading to an external configuration file instead.
116+
(resource-as-string "ALT_CONFIG_LOCATION" "config.txt")
117+
118+
;; Return a Jar resource as a string, interpolating any template variables inside the Jar resource
119+
;; using the supplied interpolation variables and the override rules defined by the template language.
120+
(read-template "config.properties" :NAME "Jack")
121+
122+
;; Return a Jar resource as a string, possibly overridden by the environment variable ALT_CONFIG_LOCATION
123+
;; per the template engine's precedence rules. Any template variables in the file will also be substuted
124+
;; using the supplied key/value pairs and/or matching environment variables per the template engine's
125+
;; precedence rules.
126+
(read-template "ALT_CONFIG_LOCATION" "config.properties" :NAME "Jack")
127+
```
128+
129+
## And more...
130+
131+
* Easier serialization / deserialization in various formats. Currently supports binary and EDN formats. Optionally can use the template language to support substitution variables inside EDN files.
132+
* A let-map form similar to "let" that returns its names and values as a Map--for those times the values of subsequent keys in a Map depend on the values of prior ones.
133+
* Simple named implementations of design patterns familiar to Java developers, particularaly Singleton.
134+
135+
# Deployment/usage
136+
137+
## Leiningen coordinates
138+
139+
```clojure
140+
:user {:repositories [["jitpack" "https://jitpack.io"]]
141+
142+
:dependencies [[com.github.shopsmart/clj-foundation "version"]]}
143+
```
144+
145+
where "version" currently is "[![Release](http://jitpack.io/v/com.github.shopsmart/clj-foundation.svg)](https://jitpack.io/#shopsmart/clj-foundation)".
146+
147+
## Maven coordinates
148+
149+
```xml
150+
<repositories>
151+
<repository>
152+
<id>jitpack.io</id>
153+
<name>Jitpack repo</name>
154+
<url>https://jitpack.io</url>
155+
</repository>
156+
</repositories>
157+
```
158+
159+
* GroupId: com.github.shopsmart
160+
* ArtifactId: clj-foundation
161+
* Version: [![Release](http://jitpack.io/v/com.github.shopsmart/clj-foundation.svg)](https://jitpack.io/#shopsmart/clj-foundation)
162+
163+
## Manual build/test
164+
165+
```bash
166+
# Build
167+
$ lein jar
168+
169+
# Test
170+
$ lein with-profile test test
171+
```

‎project.clj

+13-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
1-
(defproject com.github.shopsmart/clj-foundation "0.9.22"
2-
:description "Common patterns enabling simpler to be easier and harder to be possibler."
1+
(defproject com.github.shopsmart/clj-foundation "0.9.23"
2+
:description "Guiding opinions: Enhance the core language in resonable, useful, and conservative ways.
3+
Don't be a framework. Rather, be a conservative set of generally-useful functions that may be used
4+
together or separately. Make advanced topics like transducers and monads so easy that you don't have
5+
to know when you're using them. Use a small set of common-sense dependencies to minimize adoption friction.
6+
7+
The library is hosted on jitpack.io, so you will need: :repositories [[\"jitpack\" \"https://jitpack.io\"]]"
8+
39
:url "https://github.com/shopsmart/clj-foundation"
410

511
:license {:name "Eclipse Public License"
@@ -9,11 +15,16 @@
915
[lein-ancient "0.6.10"] ; lein ancient - Check for outdated dependencies
1016
[lein-auto "0.1.2"] ; e.g.: lein auto kbit or lein auto test
1117
[lein-kibit "0.1.2"] ; lein kibit - Linter that suggests more idiomatic forms
18+
[lein-codox "0.10.1"] ; lein codox - Generate documentation
1219
]
1320

1421
;; Used in clj-foundation.config unit tests
1522
:jvm-opts ["-DCONFIG-PROD=/tmp/_test-config-prod.edn"]
1623

24+
:codox {:metadata {:doc/format :markdown}
25+
:output-path "docs"
26+
:exclude-vars nil
27+
:source-uri "https://github.com/shopsmart/clj-foundation/blob/{version}/{filepath}#L{line}"}
1728

1829
:dependencies [[org.clojure/clojure "1.8.0"]
1930
[io.aviso/pretty "0.1.30"]

‎src/clj_foundation/caller.clj

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
(ns clj-foundation.caller
2-
"Unified api for making synchronous and asynchronous requests.")
2+
"Unified api for making synchronous and asynchronous requests. The intent is to
3+
unify calls to actor libraries along with other kinds of calls.")
34

45
(def method-missing ::method-missing)
56

‎src/clj_foundation/config.clj

+8
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
11
(ns clj-foundation.config
2+
"Read configuration from an EDN file. The EDN file's location is specified using an environment
3+
variable (for specifying its location during test, staging or production deployments) as well as
4+
a literal path or URL for specifying its location during development. If the environment variable
5+
is present, it overrides any absolute path.
6+
7+
In addition, the EDN file being used for configuration may contain template variables as defined
8+
by the [[templates]] namespace. Template variables may be resolved through the environment or through
9+
keys and values specified in code."
210
(:require [clojure.string :as str]
311
[clojure.edn :as edn]
412
[clojure.pprint :refer [pprint]]

‎src/clj_foundation/conversions.clj

+2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
(ns clj-foundation.conversions
2+
"A 'convert' multimethod that can convert between arbitrary types. Default implementations
3+
are supplied for Clojure's built-in types."
24
(:require [clj-foundation.errors :refer [failure? must-be]]
35
[clj-foundation.patterns :as patterns]))
46

‎src/clj_foundation/data.clj

+6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
(ns clj-foundation.data
2+
"Convert data between various forms; provide useful guard functions. For example:
3+
* any? - Return coll if any element in coll satisfies predicate
4+
* replace-nil - If value is not nil, return it, otherwise return replacement
5+
* keywordize - Turn string or named value into an idiomatic Clojure :keyword
6+
* ->SNAKE_CASE - Turn string or named value into a string in SNAKE_CASE form
7+
* Various functions for parsing and processing XML"
28
(:require [clojure.data.xml :as xml]
39
[clojure.string :as str]
410
[clj-foundation.patterns :as p :refer [types f]]

‎src/clj_foundation/errors.clj

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
(ns clj-foundation.errors
2+
"What is an error? Is nil an error? (Not always, but...) How can we describe functions
3+
that might return a result or that might fail? What about exceptions--they break referential
4+
transparency, but lots of code throws them anyway. What about functions that might need to
5+
retry because some external actor (e.g.: the network) might have intermittent failures?
6+
7+
Error handling is rarely clean, but this namespace provides some handy utilities to
8+
centralize some of the concerns and solve them once, reliably. ;-)"
29
(:require [clojure.string :as str]
310
[io.aviso.exception :as prettyexception]
4-
[io.aviso.ansi :as ansi]
511
[clj-foundation.patterns :refer :all]
612
[clj-foundation.millis :as millis]
713
[schema.core :as s :refer [=> =>*]])

‎src/clj_foundation/grep.clj

+4-4
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44
55
Examples:
66
7-
(grep 42 {:1 {:a 11} :2 {:b 42}}) ==> {:b 42}
8-
(grep #\"[0-9]\" [{:a \"42\"} {:b \"Hello, world\"}]) ==> {:a \"42\"}
9-
(grep \"world\" [{:1 \"Hello\"} {:1 \"Hello, world\"}]) ==> {:1 \"Hello, world\"}
10-
(grep zero? [[1 2 3] [4 5 6] [7 8 9] [0 1 2]]) ==> [0 1 2]"
7+
(grep 42 {:1 {:a 11} :2 {:b 42}}) => {:b 42}
8+
(grep #\"[0-9]\" [{:a \"42\"} {:b \"Hello, world\"}]) => {:a \"42\"}
9+
(grep \"world\" [{:1 \"Hello\"} {:1 \"Hello, world\"}]) => {:1 \"Hello, world\"}
10+
(grep zero? [[1 2 3] [4 5 6] [7 8 9] [0 1 2]]) => [0 1 2]"
1111
(:require [clojure.zip :as zip]
1212
[clojure.set :as set]
1313
[clojure.string :as str]

‎src/clj_foundation/io.clj

+4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
(ns clj-foundation.io
2+
"io address three primary concerns:
3+
* Smoothing necessary Java interop for IO operations, particularly between strings and streams/writers
4+
* Extending clojure.java.io to allow specifying an environment variable to use as the input source
5+
* (de)Serializing Clojure data structures"
26
(:require [schema.core :as s :refer [=> =>*]]
37
[clj-foundation.errors :as err]
48
[clj-foundation.templates :as template]

‎src/clj_foundation/math.clj

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
(ns clj-foundation.math
2-
"Math abstractions. Currently defines a protocol for numbers that can be decomposed into constituant parts.
2+
"Math abstractions. Currently defines a protocol and type for mixed numbers. Provides a sane
3+
replacement for clojure.core.rationalize! that always returns a rational number.
34
4-
This is then used to define a schema for Mixed Numbers and a MixedNumber type. The MixedNumber can
5-
more rationally render Clojure's Rational type as strings, but can also be used to decompose
6-
decimals or rationals > 1 into mixed numbers with easy access to the whole and fractional parts."
5+
MixedNumber can then more rationally render Clojure's Rational type as strings, but can also be
6+
used to decompose decimals or rationals > 1 into mixed numbers with easy access to the whole and
7+
fractional parts."
78

89
(require [clj-foundation.patterns :refer [let-map]]
910
[schema.core :as s :refer [=> =>* defschema]])

‎src/clj_foundation/millis.clj

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
(ns clj-foundation.millis
2-
"Convert various time values to milliseconds and back"
2+
"Convert various time values to milliseconds and back. Decompose millis to days, hours, minutes, and seconds."
33
(:require [schema.core :as s :refer [=> =>*]]
44
[clojure.string :as str :refer [trimr]]
55
[clj-foundation.patterns :refer [let-map]]

‎src/clj_foundation/oo.clj

+14-6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
(ns clj-foundation.oo
2-
"Simplify Java interop"
2+
"Simplify Java object interop"
33
(:require [clojure.string :as str]
44
[clj-foundation.data :refer [keywordize getter]]))
55

@@ -45,17 +45,17 @@
4545

4646

4747
#_(defmacro object
48-
"Create the Java object specified by clazz using the specified (optional) ctor-args vector as
49-
constructor arguments and the field-values map to initialize JavaBean style properties.
48+
"Create the Java object specified by clazz using the symbol in the map as the class name
49+
and the vector it maps to as the constructor arguments. Keyword/value elements in the map
50+
are mapped to JavaBean style property setters.
5051
5152
Wherever literal values are supplied, they are type checked by the macro at compile time.
5253
5354
e.g.:
5455
55-
(object Customer [1] {:first-name \"John\" :last-name \"Doe\"})"
56+
(object {Customer [ctor-parm-1 ctorm-param-n] :first-name \"John\" :last-name \"Doe\"})"
5657

57-
([clazz field-values])
58-
([clazz ctor-args field-values]))
58+
[obj-map])
5959

6060

6161
#_(defmacro set-fields!
@@ -65,3 +65,11 @@
6565
The keys in field-values may be :camelCase (without \"set\" at the beginning) or
6666
Clojure-style :hyphenated-words."
6767
[object field-values])
68+
69+
70+
#_(defmacro set-obj-map
71+
[a & r]
72+
"Close... But code would look like:
73+
74+
(set-obj-map TransactionRequest. .amount 10.00 .orderId \"user42\")"
75+
`(doto (~a) ~@(partition 2 r)))

‎src/clj_foundation/patterns.clj

+6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
(ns clj-foundation.patterns
2+
"Patterns DRY up code and provide a vocabulary for conversation. This package helps Clojure deal with
3+
types from Java, makes it easier to build maps that represent abstract data types, provides functional
4+
programming utilities, and adds a Nothing type that behaves as an identity value for maps, sequences,
5+
and strings under their various concatination operations. (For Category theorists, it's a monadic zero
6+
for these types under concatination and mapcat.) It also provides Nothing constants for cases where
7+
Nothing means 'error', 'no result', or simply 'use default settings'."
28
(:require [schema.core :as s :refer [=> =>*]]
39
[clojure.string :as str]
410
[potemkin :refer [def-map-type]])

‎src/clj_foundation/pipe.clj

+28-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,32 @@
11
(ns clj-foundation.pipe
2-
(:require [clj-foundation.transducers :as transducer]))
2+
"A Unix pipe function for Clojure that is implemented by converting regular Clojure
3+
functions into transducers over the input.
4+
5+
Input can be any container or a simple type. For a container, the output will
6+
be the same type as the input. If the input is a simple type, it will be wrapped
7+
in a vector before being processed and the result will be a vector. Supported
8+
container types include Map, List, Vector, and Set.
9+
10+
fns may include any of the following:
11+
12+
* An arity 1 function is treated as a mapcat function with the following relaxed
13+
rules: If it returns a value of a simple type, the value is appended to the output.
14+
A nil result is considered an empty result. Otherwise, mapcat semantics are followed.
15+
e.g.: if you want the result to be a collection of collections, the sub-collection
16+
must first be wrapped in another collection so the sub-collection itself will be
17+
concatinated onto the result.
18+
19+
* An arity 2 function is treated as a reducing function where the initial two
20+
collection elements specify the initial two elements in the reduction. The reducer
21+
supports the 'reduced' function in the standard library so that a single input
22+
collection can produce multiple reduced outputs.
23+
24+
* A vector containing an arity 2 function and a second value treats the function as
25+
a reducer and the second value as the initial value in the reduction.
26+
27+
The input is processed through fns, a single element at a time, without creating
28+
intermediate collections, in the order in which fns are specified."
29+
(:require [clj-foundation.transducers :as transducer]))
330

431

532
(defn |

0 commit comments

Comments
 (0)