CHANGELOG.adoc

Changelog

Table of Contents

• rewrite-clj v1
• rewrite-clj v0

A release with known breaking changes is marked with:

• [breaking] you probably need to change your code

• [minor breaking] you likely don’t need to change your code

rewrite-clj v1

Unreleased

v1.1.49 - 2024-11-18

• Fix parsing of b// symbol #323 (@borkdude)

• bump org.clojure/tools.reader to version 1.5.0 (@lread)

• sexpr now better matches clojure read-string for ~, @ and ~@ #305 (@frenchy64)

commit log

v1.1.48 - 2024-08-15

• bump org.clojure/tools.reader to version 1.4.2 (@lread)

• sexpr now 1) expands tag metadata to its long form 2) throws on invalid metadata #280 (@lread)

• Add support for Clojure 1.12 vector metadata (ex. (^[double] String/valueOf 3) ) #279 (@lread)

• Add support for Clojure 1.12 array class syntax (ex. byte/3) #279 (@lread)

• rewrite-clj.paredit/barf-forward on zipper created with :track-position? true now correctly barfs when current node has children #245 (@lread, thanks for the issue @p4ulcristian!)

• docs

  • Turf API diff reports for now #132 (@lread)

  • Rewrite-clj can rewrite invalid escaped chars but will throw on sexpr #295 (@lread)

commit log

v1.1.47 - 2023-03-25

• Clojure string to rewrite-clj node coercion fixes #214 (@borkdude & @lread collab)

  • "a\n\b\r\nc" is now preserved as is. It was being coerced to:

    "a
    b
    c"

  • escaped characters now coerce correctly. Previously we were only handling \". Strings like "\\s+" now handled and preserved.

commit log

v1.1.46 - 2023-01-30

• added new rewrite-clj.zip functions of-string* and of-file*, these are versions of of-string and of-file that do no auto-navigation #189 (@lread, thanks @mainej for the analysis work!)

• a lazy sequence now coerces to a rewrite-clj list node #180 (thanks @borkdude!)

• exceptions thrown while reading now include :row and :col keys in ex-data #181 (thanks @ferdinand-beyer)

• docs

  • a docstring typo fix #191 (thanks @bobbicodes!)

• Implement equality for seq nodes #212 (@borkdude)

commit log

v1.1.45 - 2022-06-09

• dropped the alpha status (@lread)

• changed rewrite-clj library version scheme from commit-count to release-num #179 (@lread)

• renamed zipper creation functions that take a rewrite-clj node as input. The old names did not reflect their purpose which led to confusion. Old functions will remain but are marked as deprecated. #178 (@lread)

  • rewrite-clj.zip/edn → rewrite-clj.zip/of-node

  • rewrite-clj.zip/edn* → rewrite-clj.zip/of-node*

• now properly escaping inline double quotes for coerced strings #176 (@lread, thanks to @ivarref for raising the issue!

• docs:

  • docstring fix, was missing list-node from toc (thanks @rfhayashi!)

commit log

v1.0.767-alpha - 2022-04-05

• fix :end-row :end-col metadata for root node #173 (thanks @mainej!)

• docs:

  • user guide correction (thanks @rgkirch!)

  • zip API docstrings now clearer about coercion #168 (@lread)

commit log

v1.0.699-alpha - 2021-10-10

• team update: @borkdude is now officially a co-maintainer of rewrite-clj! Woot woot!

• rewrite-clj v1 minimum Clojure version is now v1.8.0 (was formerly v1.9.0) #164 (@lread)

• internal rewrite-clj developer facing:

  • Migrate from depstar to tools.build (@lread)

commit log

v1.0.682-alpha - 2021-08-23

• update clojure tools.reader dependency to v1.3.6 (@lread)

• a zipper created with both a custom :auto-resolve option and the :track-position? true option will now acknowledge and use the custom :auto-resolve #159 (@lread)

• a Cons now coerces to a rewrite-clj list node #160 #161 (thanks @borkdude!)

• internal rewrite-clj developer facing:

  • Now also linting rewrite-clj sources with Eastwood #158 (thanks @vemv!)

commit log

v1.0.644-alpha - 2021-05-27

• user guide and docstrings better explain sexpr-able? and what invalid code elements rewrite-clj parses #150 #151 (@lread)

• rewrite-clj now exports clj-kondo config for its public API #146 (@lread)

• ClojureScript compiler should no longer emit invalid deprecated warnings #153 (@lread)

• Internal rewrite-clj developer facing:

  • Switched from babashka scripts to babashka tasks, developer guide updated accordingly (@lread)

commit log

v1.0.605-alpha - 2021-04-02

• rewrite-clj now understands the #! comment, a construct often used in scripts #145 (@lread)

commit log

v1.0.594-alpha - 2021-03-20

• rewrite-clj now explicitly depends on the minimum version of Clojure required, v1.9.0, rather than v1.10.3 #142 (@lread)

commit log

v1.0.591-alpha - 2021-03-16

• namespaced map should allow all Clojure whitespace between prefix and map #140 (@lread)

• Beef up docs on node creation #97 (@lread)

• Describe subedit in docs #111 (@lread)

commit log

v1.0.579-alpha - 2021-03-11

• Release workflow now creates a GitHub release (@lread)

commit log

v1.0.574-alpha - 2021-03-10

• Docs now render on cljdoc #138 (@lread)

commit log

v1.0.572-alpha [breaking] - 2021-03-10

If you wish, you can read nitty gritty details on merging rewrite clj v0 and rewrite cljs. What follows is a summary of changes.

commit log

Breaking Changes

• Minimum Clojure version bumped from v1.5.1 to v1.9

• Minimum ClojureScript version (from whatever is was for rewrite-cljs) bumped to v1.10

• Minimum Java version bumped from v7 to v8

• Keyword node field namespaced? renamed to auto-resolved?

• Now using ex-info for explicitly raised exceptions

• Rewrite-cljs positional support migrated to rewrite-clj’s positional support

• Namespaced element support reworked

  • v1 changes do not affect node traversal of the namespaced map, number and order of children remain the same.

  • Namespace map prefix, is now stored in a namespaced map qualifier node.

    • Prior to v1, the prefix was parsed to a keyword-node.

    • Let’s look at what interesting node API functions will return for the prefix node in the following namespaced maps. Assume we have parsed the example and traversed down to the prefix node.
      For example via: (→ "#:prefix{:a 1}" z/of-string z/down z/node).
      

      node API call	rewrite-clj	#:prefix{:a 1}	#::alias{:a 1}	#::{:a 1}
      string is unchanged	v1	":prefix"	"::alias"	"::"
      	v0			throws on parse
      tag is different	v1	:map-qualifier
      	v0	:token		throws on parse
      inner? still indicates that the node is a leaf node and has no children	v1	false
      	v0	false		throws on parse
      sexpr	<read on below for discussion on sexpr>

  • Namespaced element sexpr support now relies on user specifiable auto-resolve function to resolve qualifiers

    • Unlike rewrite-clj v0, the default auto-resolve behaviour never consults *ns*

    • An sexpr for keyword node ::alias/foo no longer returns :alias/foo (this could be considered a bug fix, but if your code is expecting this, then you’ll need to make changes)

  • The following namespaced element sexpr examples assume:

    • *ns* is bound to user namespace (important only for rewrite-clj v0):

    • We are using the default auto-resolve function for rewrite-clj v1

    • That you will refer to the User Guide for more detailed examples of v1 behaviour

      source	sexpr rewrite-clj v1	sexpr rewrite-clj v0	sexpr rewrite-cljs
      qualified keyword :prefix/foo	no change
      current-ns qualified keyword ::foo	:?_current-ns_?/foo	:user/foo	throws on sexpr
      ns-alias qualified keyword ::alias/foo	:??_alias_??/foo	:alias/foo	:alias/foo
      qualified map #:prefix{:a 1}	#:prefix{:a 1}	#:prefix{:a 1}	(read-string "#:prefix{:a 1}")
      current-ns qualified map #::{:b 2}	#:?_current-ns_?{:b 2}	throws on parse	throws on parse
      ns-alias qualified map #::alias{:c 3}	#:??_alias_??{:c 3}	throws unless namespace alias alias has been loaded in *ns* if alias in ns resolves to my.ns1: #:my.ns1{:c 3}	(read-string "#::alias{:c 3}")

    • Let’s dig into prefix and key sub-nodes of a namespaced map to explore v1 differences:

      Description	rewrite-clj v1	rewrite-clj v0 and rewrite-cljs
      prefix (aka qualifier)
      qualified (-> "#:prefix{:a 1}" z/of-string z/down z/sexpr)	prefix	:prefix
      current-ns qualified (-> "#::{:b 2}" z/of-string z/down z/sexpr)	?_current-ns_?	throws on parse
      ns-alias qualified (-> "#::alias{:c 2}" z/of-string z/down z/sexpr)	??_alias_??	:user/alias rewrite-cljs throws
      key
      qualified (-> "#:prefix{:a 1}" z/of-string z/down z/right z/down z/sexpr)	:prefix/a	:a
      current-ns qualified (-> "#::{:b 2}" z/of-string z/down z/right z/down z/sexpr)	:?current-ns?/b	throws on parse
      ns-alias qualified (-> "#::alias{:c 3}" z/of-string z/down z/right z/down z/sexpr)	:??_alias_??/c	:c

• Potentially breaking

  • Some rewrite-cljs optimizations were dropped in favor of a single code base. If performance for rewrite-clj v1 for ClojureScript users is poor with today’s ClojureScript, we shall adapt.

  • Deleted unused rewrite-clj.node.indent #116 (@lread)

  • Deleted redundant rewrite-clj.parser.util #93 (@lread). If you were using this internal namespace you can opt to switch to, the also internal, rewrite-clj.reader namespace.

Other Changes

• A new home under clj-commons. Thanks to @xsc, rewrite-clj will also retain its same maven coordinates on Clojars making for a seamless upgrade path for rewrite-clj v0 users.

• Now supports ClojureScript, merging in rewrite-cljs specific functionality. Frustrations like not having namespace map support and differences from rewrite-clj, like whitespace parsing, should now be things of the past. Rewrite-cljs users migrating to rewrite-clj v1 are now at, and will remain at, feature parity with rewrite-clj.

• Additions to the public API:

  • rewrite-clj.paredit - carried over from rewrite-cljs, an API for structured editing of Clojure forms

  • rewrite-clj.zip

    • Exposes the following (accidentally?) omitted functions:

      • append-child*

      • insert-newline-left

      • insert-newline-right

      • insert-space-left

      • insert-space-right

      • subzip

    • Adds functions from rewrite-cljs

      • find-last-by-pos - navigate to node at row/col

      • find-tag-by-pos - navigate to node with tag at row/col

      • position-span - returns start and end row/col for a form

      • remove-preserve-newline - same as remove but preserves newlines

    • Adds namespaced element support functions

      • reapply-context - reapplies (or removes) map qualifier node context from keywords and symbols

      • zipper creation functions now optionally accept an auto-resolve function to support sexpr on namespaced element nodes

    • Other additions

      • sexpr-able? - return true if sexpr is supported for current node

  • rewrite-clj.node

    • Additions:

      • keyword-node? - returns true if form is a rewrite-clj keyword node

      • map-qualifier-node - to create a namespaced map’s map qualifier node manually

      • map-context-apply - apply map qualifier to keyword or symbol

      • map-context-clear - remove map qualifier from keyword or symbol

      • node? - returns true if a form is a rewrite-clj created node

      • sexpr-able? - return true if sexpr is supported for node

      • symbol-node? - return true if node is a rewrite-clj symbol node

    • Updates:

      • sexpr, sepxrs and child-sexprs - now optionally take an options argument to specify an auto-resolve function

• Many updates to docs and docstrings

Fixes

• OS specific end of line variants in source now normalized consistently to \newline #93 (@lread)

• Postwalk on larger source file no longer throws StackOverflow #69 (@lread)

• Postwalk now walks in post order #123 (@lread)

• We now preserve newline at end of file #121 (@lread)

• Support for garden style selectors #92 (@lread)

• Correct and document prefix and suffix functions #91 (@lread)

• Positional metadata added by the reader is elided on coercion #90 (@lread)

• Can now read ##Inf, ##-Inf and ##Nan #75 (@lread)

• Ensure that all rewrite-clj nodes coerce to themselves (@lread)

• Strings now coerce to string nodes (instead of to token nodes) #126 (@lread)

• Regexes now coerce to regex nodes #128 (@lread)

• Regex node now:

  • converts correctly to string #127 (@lread)

  • reports correct length #130 (@lread)

• Moved from potemkin import-vars to static template based version #98 (@lread):

  • Avoids frustration/mysteries of dynamic import-vars for users and maintainers

  • Argument names now correct in API docs (some were gensymed previously)

  • Also turfed use of custom version of potemkin defprotocol+ in favor of plain old defprotocol. Perhaps I missed something, but I did not see the benefit of defprotocol+ for rewrite-clj v1.

Internal changes (developer facing)

• Tests updated to hit public APIs #106 (@lread)

• ClojureScript tests, in addition to being run under node, are now also run under chrome-headless, shadow-cljs, and for self-hosted ClojureScript, under planck. (@lread)

• Now testing rewrite-clj compiled under GraalVM native-image in two variants (@lread):

  • In a pure form where library and tests are compiled

  • Via sci where a sci exposed rewrite-clj is compiled, then tests are interpreted.

• Now automatically testing rewrite-clj against popular libs #124 (@lread)

• Now linting source with clj-kondo (@lread)

• Code coverage reports now generated for Clojure unit test run and sent to codecov.io (@lread)

• Can now preview for cljdoc locally via script/cljdoc_preview.clj (@lread)

• API diffs for rewrite-clj v1 vs rewrite-clj v0 vs rewrite-cljs can be generated by script/gen_api_diffs.clj (@lread)

• Contributors are acknowledged in README and updated via script/update_readme.clj (@lread)

• Doc code blocks are automatically tested via script/doc_tests.clj #100 (@lread)

• Some tooling and tech replaced (@lread):

  • All scripts are written in Clojure and run via Babashka or Clojure.

  • Switched from leiningen project.clj to Clojure tools CLI deps.edn

  • Moved from CommonMark to AsciiDoc for docs

  • Moved from publishing docs locally via codox to publishing to cljdoc

  • Now using CommonMark in docstrings (they render nicely in cljdoc)

  • Moved from TravisCI to GitHub Actions where, in addition to Linux, we also test under macOS and Windows

  • Adopted kaocha for Clojure testing, stuck with doo for regular ClojureScript testing, and added support for ClojureScript watch testing with figwheel main.

  • Potemkin dynamic import-vars replaced with static code generation solution

• Added GitHub issue templates (@lread)

• Fixed a generative test sporadic failure #88 (@lread)

rewrite-clj v0

0.6.0 [breaking] - 2016-10-02

• BREAKING: uses a dedicated node type for regular expressions. #49 (thanks @ChrisBlom)

• implement NodeCoercable for nil. #53 (thanks @jespera!)

0.5.2 - 2016-08-31

• fixes parsing of splicing reader conditionals #?@…​. #48 (thanks @arrdem!)

0.5.1 - 2016-07-08

• fixes parsing of multi-line regular expressions. #51 (thanks @brian-dawn!)

0.5.0 [breaking] - 2016-04-03

• BREAKING: commas will no longer be parsed into :whitespace nodes but :comma. #44 (thanks @arrdem!)

• BREAKING: position will throw exception if not used on rewrite-clj custom zipper. #45 (@xsc)

• BREAKING: drops testing against JDK6.

• DEPRECATED:

  • append-space in favour of insert-space-right

  • prepend-space in favour of insert-space-left

  • append-newline in favour of insert-newline-right

  • prepend-newline in favour of insert-newline-left

• fix insertion of nodes in the presence of existing whitespace. #33, 34 (thanks @eraserhd!)

• edn and edn* now take a :track-position? option that activates a custom zipper implementation allowing position to be called on. #41, 45 (thanks @eraserhd!)

• fix parsing of whitespace, e.g. <U+2028>. #43 (@xsc)

• fix serialization of `integer-node`s. #37 (thanks @eraserhd!)

• adds insert-left* and insert-right* to facade.

• generative tests. #41 (thanks @eraserhd!)

0.4.13 - 2016-04-02

Development has branched off, using the 0.4.x branch

• upgrades dependencies.

• fixes a compatibility issue when running 'benedekfazekas/mranderson' on a project with both 'rewrite-clj' and 'potemkin'.

• switch to Clojure 1.8.0 as base Clojure dependency; mark as "provided".

• switch to MIT License.

• drop support for JDK6.

0.4.12 - 2015-02-15

• drop fast-zip and potemkin dependencies. #26 (@xsc)

0.4.11 - 2015-02-05

• fix handling of symbols with boundary character inside. #25 (@xsc)

0.4.10 - 2015-02-04

• fix handling of symbols with trailing quote, e.g. x'. #24 (@xsc)

0.4.9 - 2015-01-31

• fix replace-children for :uneval nodes. #23 (@xsc)

• add rewrite-clj.zip/postwalk. #22 (@xsc)

0.4.8 - 2015-01-29

• allow parsing of aliased keywords, e.g. ::ns/foo. #21 (@xsc)

0.4.7 - 2015-01-28

• fixes zipper creation over whitespace-/comment-only data. #20 (@xsc)

0.4.6 - 2015-01-28

• fixes parsing of empty comments. #19 (@xsc)

0.4.5 - 2015-01-25

• fixes parsing of comments that are at the end of a file without linebreak. #18 (@xsc)

0.4.4 - 2015-01-18

• upgrades dependencies.

• add rewrite-clj.zip/child-sexprs to public API.

0.4.3 - 2015-01-18

• fix parsing of backslash \\ character. #17 (@xsc)

0.4.2 - 2015-01-16

• fix :fn nodes (were printable-only? but should actually create an s-sexpression).

• fix assert-sexpr-count to not actually create the s-expressions.

0.4.1 - 2015-01-13

• fixes infinite loop when trying to read a character.

0.4.0 [breaking] - 2015-01-13

• BREAKING rewrite-clj.zip.indent no longer usable.

• BREAKING node creation/edit has stricter preconditions (e.g. :meta has to contain exactly two non-whitespace forms).

• BREAKING moved to a type/protocol based implementation of nodes.

• fix radix support. #13 (@xsc)

• fix handling of spaces between certain forms. #7 (@xsc)

• add node constructor functions.

• add child-sexprs function.

0.3.12 - 2014-12-14

• fix assoc on empty map. #16 (@xsc)

0.3.11 - 2014-10-23

• drop tests for Clojure 1.4.0.

• fix behaviour of leftmost.

• upgrade to fast-zip 0.5.2.

0.3.10 - 2014-10-21

• fix behaviour of next and end?.

• fix prewalk.

• add row/column metadata.

0.3.9 - 2014-03-29

• add end?.

• allow access to children of quoted forms. #6 (@xsc)

• fix children lookup for zipper (return nil on missing children). #5 (@xsc)

0.3.8 - 2014-03-15

• add :uneval element type (for #_form elements).

• fix estimate-length for multi-line strings.

0.3.7 - 2014-02-09

• fix zipper creation from file.

0.3.6 - 2014-02-08

• upgrade dependencies.

• fix file parser (UTF-8 characters were not parsed correctly, see #24@xsc/lein-ancient).

0.3.5 - 2013-12-14

• upgrade dependencies.

• cleanup dependency chain.

0.3.4 - 2013-11-02

• upgrade dependencies.

0.3.3 - 2013-10-24

• Bugfix: parsing of a variety of keywords threw an exception.

0.3.2 - 2013-10-22

• Bugfix: :1.4 and others threw an exception.

0.3.1 - 2013-10-07

• added namespaced keywords.

0.3.0 - 2013-08-07

• added token type :newline to handle linebreak characters.

• rewrite-clj.zip/edn wraps everything into [:forms …​] node, but the initial location is the node passed to it.

• new functions in rewrite-clj.zip.core:

  • length

  • move-to-node

  • edit→>, edit-node

  • subedit→, subedit→>, edit-children

  • leftmost?, rightmost?

• new functions in rewrite-clj.zip.edit:

  • splice-or-remove

  • prefix, suffix (formerly rewrite-clj.zip.utils)

• rewrite-clj.zip.edit/remove now handles whitespace appropriately.

• indentation-aware modification functions in rewrite-clj.zip.indent:

  • indent

  • indent-children

  • replace

  • edit

  • insert-left

  • insert-right

  • remove

  • splice

• fast-zip utility functions in rewrite-clj.zip.utils

0.2.0 - 2013-07-26

• added more expressive error handling to parser.

• added multi-line string handling (node type: :multi-line)

• new functions in rewrite-clj.printer:

  • →string

  • estimate-length

• new functions in rewrite-clj.zip:

  • of-string, of-file

  • print, print-root

  • →string, →root-string

  • append-space, prepend-space

  • append-newline, prepend-newline

  • right*, left*, …​ (delegating to fast-zip.core/right, …​)

• new token type :forms

• new functions in rewrite-clj.parser:

  • parse-all

  • parse-string-all

  • parse-file-all

• zipper utility functions in rewrite-clj.zip.utils (able to handle multi-line strings):

  • prefix

  • suffix

0.1.0 - 2013-07-20

• Initial Release