Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 302d743

Browse files
kkinnearkkinnear
committed
Clean up style processing and enhance community examples.
1 parent 1b00e53 commit 302d743

10 files changed

Lines changed: 636 additions & 44 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,32 @@ All notable changes to this project will be documented in this file.
55

66
### Added
77

8+
* You can now define a style by changing the `:style-map` and invoke
9+
(i.e. utilize) the style in the same `.zprintrc` or the same call
10+
to `set-options!`.
11+
812
### Changed
913

10-
* In Issue #124 I added the ability to have inline functions defined
14+
* In Issue #124 we added the ability to have inline functions defined
1115
in some `.zprintrc` files, but not all of them. In addition, the
1216
graalVM binarie didn't support function definitions at all in any
1317
`.zprintrc` files. Now you can define functions in any `.zprintrc`
1418
files, regardless of the binary you are using. This is not a
1519
security issue because the inline function definitions are defined
16-
and executed with the "Small Clojure Interpreter", `sci`. In addition
20+
and executed with the "Small Clojure Interpreter", `sci`. In addition,
1721
these `.zprintrc` files will work in the pre-built graalVM binaries.
1822

23+
* The `:flow` function type (in the `:fn-map`) now supports constant
24+
pairing.
25+
26+
* The `:moustache` style has been split into two part and changed to
27+
include justification for the pairs.
28+
1929
### Fixed
2030

31+
* Error found but not reported in `.zprintrc` and `.zprint.edn` files
32+
found with `:search-config? true`. Issue #167.
33+
2134
* Fixed two subtle hang flow problems, Issue #163.
2235

2336
* Cleaned up `:fn-map` entries for `->` and `->>` to not allow constant

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,15 @@ a number of major source code formattng approaches.
99

1010
### *Recent Additions!*
1111

12-
* Functions in options maps now safely supported in all `.zprintrc` files, using `sci`
13-
* Functions in options maps now supported in all prebuilt graalVM binaries.
12+
* [Functions in options maps now safely supported in all `.zprintrc` files, using `sci`.](./doc/options/optionfns.md)
13+
* Functions in options maps now supported in all distributed graalVM binaries!
14+
* [You can now define a style and use it in the same `.zprintrc`.](./doc/reference.md#style-and-style-map) You can also define one style in terms of another.
1415
* [In-place formatting by file name](./doc/using/files.md), `$ zprint -w file.clj` and `$ zprint -w *.clj`
1516
* Output colorized, formatted source to terminal: `$ zprint '{:color? true}' <file.clj`
1617
* [More flexible constant-pairing](./doc/reference.md#constant-pair-fn-nil)
1718
* [Format babashka scripts](./doc/using/babashka.md)
1819
* [Format ranges of lines in files](./doc/using/range.md)
19-
* [More colors allowed in `:color-map`, and more elements can be colored](./doc/options/colors.md)
20+
* [{`:style :dark-color-map`} when using dark terminals](./doc/reference.md#dark-color-map)
2021
* [Keep blank lines from input](./doc/types/respectbl.md)
2122
* [All changes](./CHANGELOG.md)
2223

‎doc/options/community.md‎

Lines changed: 162 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,9 @@ This difference is reflected in the `:style :community`:
4040
```
4141
This change to the defaults for zprint does several things:
4242

43-
* Do not indent the second element of a pair when you have to flow
44-
the pair.
43+
* Do not indent the second element of a pair when the second element
44+
of the pair does not fit on the same line as the first and must be
45+
started on the line under the first element.
4546

4647
* Do not format some functions specially to make them more understandable.
4748

@@ -52,7 +53,83 @@ This change to the defaults for zprint does several things:
5253

5354
You can read lots about this [here](./pairs.md).
5455

55-
Here is an example of the difference:
56+
Here is a simple example of the difference, where the width has been narrowed
57+
in order to force the second element onto the next line in each case:
58+
```clojure
59+
; Here is what you get with the default zprint format with a normal width.
60+
61+
(czprint-fn pair-indent {:width 80})
62+
63+
(defn pair-indent
64+
"An exmple showing how pairs are indented."
65+
[a b c d]
66+
(cond (nil? a) (list d)
67+
(nil? b) (list c d a b)
68+
:else (list a b c d)))
69+
70+
; Here is what you get with the community formatting and a normal width.
71+
; There is no difference between these two.
72+
73+
(czprint-fn pair-indent {:style :community :width 80})
74+
75+
(defn pair-indent
76+
"An exmple showing how pairs are indented."
77+
[a b c d]
78+
(cond (nil? a) (list d)
79+
(nil? b) (list c d a b)
80+
:else (list a b c d)))
81+
82+
; Here is the default zprint formatting, when the second element of a
83+
; cond pair is indented when it formats onto the next line due to the
84+
; narrow width.
85+
86+
(czprint-fn pair-indent {:width 22})
87+
88+
(defn pair-indent
89+
"An exmple showing how pairs are indented."
90+
[a b c d]
91+
(cond
92+
(nil? a) (list d)
93+
(nil? b)
94+
(list c d a b)
95+
:else
96+
(list a b c d)))
97+
98+
; Here is the community formatting, where the second element of a
99+
; cond pair is aligned with the first element when it formats onto the
100+
; next line due to the narrow width.
101+
102+
(czprint-fn pair-indent {:style :community :width 22})
103+
104+
(defn pair-indent
105+
"An exmple showing how pairs are indented."
106+
[a b c d]
107+
(cond
108+
(nil? a) (list d)
109+
(nil? b)
110+
(list c d a b)
111+
:else
112+
(list a b c d)))
113+
114+
; Some peope like to separate the pairs that end up on the next line
115+
; with a blank line
116+
117+
(czprint-fn pair-indent {:style [:community :pair-nl] :width 22})
118+
119+
(defn pair-indent
120+
"An exmple showing how pairs are indented."
121+
[a b c d]
122+
(cond
123+
(nil? a) (list d)
124+
(nil? b)
125+
(list c d a b)
126+
127+
:else
128+
(list a b c d)))
129+
130+
```
131+
132+
Here is a more realistic example of the difference:
56133

57134
```clojure
58135
(czprint-fn cond-let)
@@ -102,7 +179,7 @@ At some point, the "community standards" for Clojure source formatting
102179
made a distinction between "body functions" and "argument functions",
103180
and wanted "argument functions" to have an indent of 1, and "body functions"
104181
to have an indent of 2. The theory seemed to be that "body functions"
105-
were functions which had executable forms in them, oftern (though not
182+
were functions which had executable forms in them, often (though not
106183
always) of indeterminate number. "Argument functions", on the other
107184
hand, had arguments (typically a fixed number) which were values and
108185
not primarily executable forms.
@@ -113,8 +190,87 @@ types, and will also accept a value for `:indent-arg`, which (if non-nil)
113190
will be used as the indent for argument functions (which is
114191
everything that is not explicitly classified as a body function).
115192

116-
Here is an example that illustrates the different indent for a body
117-
function as well as the indent for the second element of a pair:
193+
Here is a simple (and contrived) example that illustrates the difference
194+
between the default zprint indent of 2 for all lists with a symbol as the
195+
first element, and the community formatting which has different indents
196+
for different types of functions:
197+
198+
```clojure
199+
; Note: if you don't restrict the width, both {:style :community} and the
200+
; default zprint formatting are identical
201+
202+
; The default formatting with restricted width to force things onto
203+
; subsequent lines
204+
205+
(czprint-fn body-indent {:width 16})
206+
(defn
207+
body-indent
208+
"An example showing how indent for body fns differs from argument fns."
209+
[thing
210+
something-else
211+
ala bala
212+
portokala]
213+
; Body functions
214+
(when thing
215+
(something-else))
216+
(with-out-str
217+
(prn "Hi")
218+
(prn "You"))
219+
; Argument functions
220+
(filter even?
221+
(list
222+
(range
223+
1
224+
10)
225+
(range
226+
100
227+
1000)))
228+
(or
229+
ala
230+
(list
231+
bala
232+
ala
233+
bala)
234+
portokala))
235+
236+
; The community formatting, also with restricted width. The body functions
237+
; don't change, but look at filter, or, list (the first one), and range -- the
238+
; indent on all of these functions is one less than that above.
239+
240+
(czprint-fn body-indent {:style :community :width 16})
241+
242+
(defn
243+
body-indent
244+
"An example showing how indent for body fns differs from argument fns."
245+
[thing
246+
something-else
247+
ala bala
248+
portokala]
249+
; Body functions
250+
(when thing
251+
(something-else))
252+
(with-out-str
253+
(prn "Hi")
254+
(prn "You"))
255+
; Argument functions
256+
(filter
257+
even?
258+
(list
259+
(range 1 10)
260+
(range
261+
100
262+
1000)))
263+
(or
264+
ala
265+
(list bala
266+
ala
267+
bala)
268+
portokala))
269+
```
270+
271+
Here is a more realistic (and more confusing) example that illustrates
272+
the different indent for a body function as well as the indent for the
273+
second element of a pair:
118274

119275
```clojure
120276
(czprint-fn with-open)

‎doc/options/pairs.md‎

Lines changed: 77 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Part of the reason for zprint's existence revolves around the
44
current approach to indenting used for `cond` clauses, `let` binding vectors,
55
and maps and other things with pairs (extend and reader conditionals).
66

7-
Back in the day some of the key functions that include pairs, e.g.
7+
Historically, some of the key functions that include pairs, e.g.
88
`cond` and `let`, had their pairs nested in parentheses. Clojure doesn't
99
follow this convention, which does create cleaner looking code in
1010
the usual case, when the second part of the pair is short and fits
@@ -20,7 +20,82 @@ find them bothersome, so by default zprint will indent the
2020
second part of these pairs by 2 columns (controlled by `{:pair {:indent 2}}`
2121
for `cond` and `{:binding {:indent 2}}` for binding functions).
2222

23-
Here is an example of both approaches:
23+
Here is a simple example of the difference, where the width has been narrowed
24+
in order to force the second element onto the next line in each case:
25+
```clojure
26+
; Here is what you get with the default zprint format with a normal width.
27+
28+
(czprint-fn pair-indent {:width 80})
29+
30+
(defn pair-indent
31+
"An exmple showing how pairs are indented."
32+
[a b c d]
33+
(cond (nil? a) (list d)
34+
(nil? b) (list c d a b)
35+
:else (list a b c d)))
36+
37+
; Here is what you get with the community formatting and a normal width.
38+
; There is no difference between these two.
39+
40+
(czprint-fn pair-indent {:style :community :width 80})
41+
42+
(defn pair-indent
43+
"An exmple showing how pairs are indented."
44+
[a b c d]
45+
(cond (nil? a) (list d)
46+
(nil? b) (list c d a b)
47+
:else (list a b c d)))
48+
49+
; Here is the default zprint formatting, when the second element of a
50+
; cond pair is indented when it formats onto the next line due to the
51+
; narrow width.
52+
53+
(czprint-fn pair-indent {:width 22})
54+
55+
(defn pair-indent
56+
"An exmple showing how pairs are indented."
57+
[a b c d]
58+
(cond
59+
(nil? a) (list d)
60+
(nil? b)
61+
(list c d a b)
62+
:else
63+
(list a b c d)))
64+
65+
; Here is the community formatting, where the second element of a
66+
; cond pair is aligned with the first element when it formats onto the
67+
; next line due to the narrow width.
68+
69+
(czprint-fn pair-indent {:style :community :width 22})
70+
71+
(defn pair-indent
72+
"An exmple showing how pairs are indented."
73+
[a b c d]
74+
(cond
75+
(nil? a) (list d)
76+
(nil? b)
77+
(list c d a b)
78+
:else
79+
(list a b c d)))
80+
81+
; Some peope like to separate the pairs that end up on the next line
82+
; with a blank line
83+
84+
(czprint-fn pair-indent {:style [:community :pair-nl] :width 22})
85+
86+
(defn pair-indent
87+
"An exmple showing how pairs are indented."
88+
[a b c d]
89+
(cond
90+
(nil? a) (list d)
91+
(nil? b)
92+
(list c d a b)
93+
94+
:else
95+
(list a b c d)))
96+
97+
```
98+
Here is a realistic and more complex example of both approaches:
2499

25100
```clojure
26101
(czprint-fn cond-let)
@@ -80,5 +155,3 @@ when calling zprint (specify that in your `.zprintrc` file, perhaps).
80155

81156
You can change the indent from the default of 2 to 0 individually
82157
in `:binding`, `:map`, or `:pair` if you want to tune it in more detail.
83-
84-

‎doc/reference.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4086,10 +4086,20 @@ enclosing the styles in a vector, for example:
40864086
When multiple styles are specified, they are applied in the order
40874087
given.
40884088

4089-
Note that styles are applied before the rest of the elements
4090-
of a options map, so that you can override elements of the style
4091-
that you wish to change by specifying an explicit element in the
4092-
options map.
4089+
There are three phases of processing an options map:
4090+
4091+
1. Any changes to the `:style-map` are processed first.
4092+
2. If a `:style` is specified, the changes to the style map associated
4093+
with that `:style` are processed.
4094+
3. The remaining changes to the options map are processed.
4095+
4096+
So, you can define a new `:style` in the `:style-map`, and then use
4097+
it with `:style`, and then override some of its settings -- all in
4098+
the same `.zprintrc` or `set-options!` call.
4099+
4100+
You can also define one style in terms of another style. You will receive
4101+
an exception if you specify a `:style` which uses another style and ends up
4102+
using the same style twice in the same invocation.
40934103

40944104
### Available Styles:
40954105

@@ -4702,9 +4712,10 @@ map in an individual call to zprint.
47024712
You might wish to define several styles with different color-maps,
47034713
perhaps, allowing you to alter the colors more easily.
47044714

4705-
You cannot define a style and apply it in the same configuration
4706-
pass, as styles are applied before the rest of the configuration
4707-
in a options map.
4715+
You can define a style and apply it in the same `.zprintrc` file
4716+
or `set-options!` call, as the `:style-map` changes are processed
4717+
before the `:style` changes. Both are processed before the remaining
4718+
changes in the options map.
47084719

47094720
______
47104721
## :tab

0 commit comments

Comments
 (0)