Merge branch 'release-1.0.0'

CHANGELOG.md

@@ -1,71 +1,126 @@
-Release Notes
-=============
+Change Log
+==========
 
-This page documents the high-level changes in each release of Puget.
+All notable changes to this project will be documented in this file, which
+follows the conventions of [keepachangelog.com](http://keepachangelog.com/).
+This project adheres to [Semantic Versioning](http://semver.org/).
 
-## 0.9.2 (2015-10-20)
+## [1.0.0] - 2015-10-29
 
+Finally decided it was time to recognize that this is a stable library!
+
+### Added
+- Adopt `visit-record` logic from upgrade to fipp 0.6.3.
+  [brandonbloom/fipp#29](//github.com/brandonbloom/fipp/pull/29)
+
+### Changed
+- Move pattern and var printing back into `PrettyPrinter` visitor protocol.
+- Improve class name parsing of inner function names.
+
+## [0.9.2] - 2015-10-20
+
+### Added
 - Add `printer/unknown-handler` and improve rendering of unknown types.
 - Add print handlers for class and function values.
+
+### Changed
 - Line-break tagged literals when the form is a collection.
 
-## 0.9.1 (2015-10-17)
+## [0.9.1] - 2015-10-17
 
-- Improve `chained-lookup` logic to remove nil dispatch entries.
+### Added
 - Add `printer/pr-handler` as a useful default for dispatching.
-- Rename `:sort-mode` option back to `:sort-keys`. (#25)
-- Fix rendering of lazy sequences. (#26)
 - Add `:seq-limit` option, to cap realization of lazy sequences.
 
-## 0.9.0 (2015-10-13)
+### Changed
+- Improve `chained-lookup` logic to remove nil dispatch entries.
+- Rename `:sort-mode` option back to `:sort-keys`.
+  [#25](//github.com/greglook/puget/issues/25)
+
+### Fixed
+- Fix rendering of lazy sequences.
+  [#26](//github.com/greglook/puget/issues/26)
+
+## [0.9.0] - 2015-10-13
 
+This version involves a major update to the printer internals with the upgrade
+to fipp and Clojure 1.7.
+
+### Added
+- Add more `:print-fallback` possibilities.
+- Add `CanonicalPrinter` as a minimalist alternative to `PrettyPrinter`.
+
+### Changed
 - Upgrade to Clojure 1.7 and fipp 0.6.2.
 - Separate total-order comparator into
   [mvxcvi/arrangement](https://github.com/greglook/clj-arrangement).
-- Reordered args to `color/document` and `color/text`.
+- Reorder args to `color/document` and `color/text`.
 - Drop `puget.data/ExtendedNotation` protocol and switched to type-dispatched
   print-handler approach.
 - Rename `:sort-keys` option to `:sort-mode`.
+
+### Removed
 - Remove `:escape-types` functionality in favor of `:print-handlers`.
-- Add more `:print-fallback` possibilities.
-- Add `CanonicalPrinter` as a minimalist alternative to `PrettyPrinter`.
 
-## 0.8.1 (2015-04-25)
+## [0.8.1] - 2015-04-25
 
+### Removed
 - Remove `tagged-literal` code which conflicts with the built-in `clojure.core`
   functions in 1.7. [#20](//github.com/greglook/puget/issues/20)
 
-## 0.8.0 (2015-03-10)
+## [0.8.0] - 2015-03-10
 
+### Added
+- Add `:escape-types` option to avoid rendering types that Puget does not handle
+  well. [#19](//github.com/greglook/puget/pull/19)
+
+### Removed
 - Remove byte array and URI extension to Whidbey.
   [#16](//github.com/greglook/puget/issue/16)
-- Added `:escape-types` option to avoid rendering types that Puget does not
-  handle well.
-  [#19](//github.com/greglook/puget/pull/19)
 
-## 0.7.1 (2015-02-28)
+## [0.7.1] - 2015-02-28
 
-- Updated documentation and clean up docstrings.
-- Refactored document formatting multimethod to dispatch on `type` metadata.
+### Added
+- Add `:print-fallback` option to support custom `print-method` implementations.
+  [#18](//github.com/greglook/puget/pull/18)
+
+### Changed
+- Refactor document formatting multimethod to dispatch on `type` metadata.
   [#13](//github.com/greglook/puget/issue/13)
   [#14](//github.com/greglook/puget/pull/14)
-- Changed `TaggedValue` to `TaggedLiteral` per the discussion
+- Change `TaggedValue` to `TaggedLiteral` per the discussion
   [here](https://groups.google.com/forum/#!topic/clojure-dev/LW0ocQ1RcYI).
 - Change color markup to a customizable multimethod with ANSI and HTML output.
   [#15](//github.com/greglook/puget/pull/15)
-- Added `:print-fallback` option to support custom `print-method` implementations.
-  [#18](//github.com/greglook/puget/pull/18)
 
-## 0.6.6 (2014-12-28)
+### Fixed
+- Update documentation and clean up docstrings.
 
-- Added `:sort-keys` option to allow bounded canonicalization. #12
+## [0.6.6] - 2014-12-28
 
-## 0.6.4 (2014-09-23)
+### Added
+- Add `:sort-keys` option to allow bounded canonicalization.
+  [#12](//github.com/greglook/puget/pull/12)
 
-- Added `merge-options` and `with-options` helpers.
-- Added `:coll-separator` option.
-- Maps default to using commas between entries.
-- Gave characters a separate syntax element than strings.
-- Added format method for `IDeref` and `IPending` references.
+## [0.6.4] - 2014-09-23
+
+### Added
+- Add `merge-options` and `with-options` helpers.
+- Add `:coll-separator` option.
+- Add format method for `IDeref` and `IPending` references.
   [#9](//github.com/greglook/puget/issues/9)
   [#10](//github.com/greglook/puget/pull/10)
+
+### Changed
+- Maps default to using commas between entries.
+- Gave characters a separate syntax element than strings.
+
+[1.0.0]: https://github.com/greglook/puget/compare/0.9.2...1.0.0
+[0.9.2]: https://github.com/greglook/puget/compare/0.9.1...0.9.2
+[0.9.1]: https://github.com/greglook/puget/compare/0.9.0...0.9.1
+[0.9.0]: https://github.com/greglook/puget/compare/0.8.1...0.9.0
+[0.8.1]: https://github.com/greglook/puget/compare/0.8.0...0.8.1
+[0.8.0]: https://github.com/greglook/puget/compare/0.7.1...0.8.0
+[0.7.1]: https://github.com/greglook/puget/compare/0.6.6...0.7.1
+[0.6.6]: https://github.com/greglook/puget/compare/0.6.4...0.6.6
+[0.6.4]: https://github.com/greglook/puget/compare/0.6.3...0.6.4

README.md

@@ -12,10 +12,11 @@ Puget is a Clojure library for printing Clojure and
 data into a _print document_ and uses the [Fast Idiomatic
 Pretty-Printer](https://github.com/brandonbloom/fipp) library to render it.
 
-Puget offers two main features which set it apart from FIPP and Clojure's native
-pretty-printing functions: [syntax coloring](#syntax-coloring) and [canonical
-printing](#canonical-representation). Custom rendering is supported using type
-dispatch to select [print handlers](#type-extensions).
+Puget offers several features which set it apart from FIPP and Clojure's native
+pretty-printing functions. [Syntax coloring](#syntax-coloring) is the most
+widely used, followed by [canonical printing](#canonical-representation). Custom
+value rendering is supported using type dispatch to select [print
+handlers](#type-extensions).
 
 ## Installation
 
@@ -28,57 +29,55 @@ See [Whidbey](https://github.com/greglook/whidbey) for nREPL and Leiningen integ
 
 ## Usage
 
-Puget's printing is controlled by a map of options which include print width,
-sorting mode, color scheme and style, whether to print metadata, and so on. The
-default options are held in the dynamic var `puget.printer/*options*`. This can
-be bound with the `with-options` macro for convenience.
+Puget's printing is controlled by a map of options which configure things like
+print width, sorting mode, color scheme and style, whether to print metadata,
+and so on. The default options are held in the dynamic var
+`puget.printer/*options*`, which can be bound using `with-options`. See the
+[`puget.printer`](https://greglook.github.io/puget/api/puget.printer.html)
+namespace documentation for the full set of options.
 
-These options are used to construct a _printer_ object to render values with.
-You can create these manually with `pretty-printer` or `canonical-printer`, then
-use them with `render-out` or `render-str` for maximum control.
-
-These options are used to construct a printer record, which is either the
-`PrettyPrinter` or `CanonicalPrinter`. The printers can be used directly to
-render values with `render-out` or `render-str` if maximal repeatability is
-desired.
-
-Otherwise, the `pprint` and `pprint-str` functions will automatically create a
-`PrettyPrinter` using the dynamic options and any provided configuration.
+These options are used to construct a _printer_ to render values with. `pprint`
+and `pprint-str` will automatically create a `PrettyPrinter` record from the
+current and passed options, or you can use `pretty-printer` or
+`canonical-printer` to construct one manually. `render-out` and `render-str`
+take a printer and a value if you need maximum control over the printing.
 
 ## Syntax Coloring
 
-Puget's first main feature is colorizing the printed data using ANSI escape
-codes or HTML `span` elements for color markup. This is kind of like syntax
-highlighting, except much easier since the code works directly with the data
-instead of parsing it from text.
+Puget's first major feature is colorizing the printed data by rendering it with
+embedded markup. Different syntax elements are given different colors to make
+the printed output much easier for humans to parse. This is similar to syntax
+highlighting, but much easier since the code works directly with the data
+instead of parsing it from text!
 
-Different syntax elements are given different colors to make reading the
-printed output much easier for humans. The `:print-color` option can be set to
-enable colorization using the `with-color` macro - alternately, the `cprint`
-function always prints with colored output enabled:
+Elements are mapped to color codes by the `:color-scheme` option. The
+`:print-color` option can be set to enable colorization using the `with-color`
+macro - alternately, the `cprint` function always prints with colored output
+enabled:
 
 ![colorization example](screenshot.png)
 
-The `:color-markup` option defaults to `:ansi`, but can be set to `:html-inline`
-or `:html-classes` to use HTML `span` elements for color markup. Finally, the
-`:color-scheme` map controls how various elements are highlighted.
+Puget supports three different kinds of color markup:
+- `:ansi` (the default) adds ANSI color escapes for terminal outputs.
+- `:html-inline` adds HTML `span` elements with inline `style` attributes.
+- `:html-classes` adds `span` elements with semantic `class` attributes.
 
 ## Canonical Representation
 
-Puget's other main goal is to provide _canonical serialization_ of data. In
-short, if two data values are equal, they should be printed identically. This is
-important for data deduplication and in situations where the printed data is
-hashed.
+Puget also provides _canonical serialization_ of data. In most cases, if two
+data values are equal, they should be printed identically. This is important for
+when the printed data is hashed, but it also makes it easier to process maps and
+other structures with similar contents.
 
 By default, Puget uses the
 [arrangement](https://github.com/greglook/clj-arrangement) library to sort the
 values in sets and the keys in maps so they are always printed the same way.
-This can be disabled with the `:sort-mode` option, or enabled only for
+This can be disabled with the `:sort-keys` option, or enabled only for
 collections under a certain size.
 
-Most printing is done with the `puget.printer.PrettyPrinter` class, but the
-library also offers the `CanonicalPrinter` for serializing data in a stricter
-(and more compact) fashion.
+Most printing is done with the `PrettyPrinter` class, but the library also
+offers the `CanonicalPrinter` for serializing data in a stricter (and more
+compact) fashion.
 
 ```clojure
 => (require '[puget.printer :as puget])
@@ -98,18 +97,24 @@ library also offers the `CanonicalPrinter` for serializing data in a stricter
 
 ## Type Extensions
 
-All of Clojure's primitive types are given their standard canonical print
-representations. To handle non-standard data types, Puget supports a mechanism
-to dispatch to custom _print handlers_. These take precedence over the standard
-rendering mechanisms.
+All of Clojure's primitive types are given their standard print representations.
+To handle non-standard data types, Puget supports a mechanism to dispatch to
+custom _print handlers_. These take precedence over the normal rendering
+mechanisms.
 
 This can be used to provide an EDN tagged-literal representation for certain
 types, or just avoid trying to pretty-print types which the engine struggles
-with (such as attempting to render a Datomic database).
+with (such as Datomic database values).
+
+Before rendering a value, the printer checks for a `:print-handlers` function.
+If available, it is called with the type of the value to be printed. If the
+lookup returns a handler, that function is called with the value and the result
+is used as the rendered format of the value.
 
-The `puget.dispatch` namespace has functions to help build handler lookup
-functions; most commonly, a chained inheritance-based lookup provides semantics
-similar to Clojure's multimethod dispatch.
+The [`puget.dispatch`](https://greglook.github.io/puget/api/puget.dispatch.html)
+namespace has functions to help build handler lookup functions. The
+`inheritance-lookup` constructor provides semantics similar to Clojure's
+multimethod dispatch.
 
 As an example, extending `#inst` formatting to clj-time's `DateTime`:
 
@@ -132,12 +137,13 @@ As an example, extending `#inst` formatting to clj-time's `DateTime`:
 ```
 
 If no handler is specified for a given type and it's not a built-in EDN type,
-Puget refers to the `:print-fallback` option. The default `:pretty` prints a
-colored representation of the unknown value (note this is not valid EDN!),
-while `:print` will fall back to the standard `pr-str`. Alternately, `:error`
-will throw an exception for types with no defined representation. Finally, a
-function may be provided which will be passed the current printer and the
-unknown value to render.
+Puget refers to the `:print-fallback` option, which must be one of:
+- `:pretty` (the default) prints a colored representation of the unknown value
+  (not valid EDN!).
+- `:print` falls back to the standard `pr-str` representation.
+- `:error` throws an exception for types with no defined representation.
+- A function which will be called with the printer and the unknown value to
+  render, returning the formatted value.
 
 ## License
 

project.clj

@@ -1,4 +1,4 @@
-(defproject mvxcvi/puget "0.9.2"
+(defproject mvxcvi/puget "1.0.0"
   :description "Colorizing canonical Clojure printer for EDN values."
   :url "https://github.com/greglook/puget"
   :license {:name "Public Domain"
@@ -10,12 +10,10 @@
   [[lein-cloverage "1.0.6"]]
 
   :dependencies
-  [[fipp "0.6.2"]
+  [[fipp "0.6.3"]
    [mvxcvi/arrangement "1.0.0"]
    [org.clojure/clojure "1.7.0"]]
 
-  :cljfmt {:indents {with-options [[:block 1]]}}
-
   :codox {:defaults {:doc/format :markdown}
           :output-dir "doc/api"
           :src-dir-uri "https://github.com/greglook/puget/blob/master/"