[WB-29]: Add conversion/display functions for all units of measure

.sealog/changes/2-0-0.edn

@@ -0,0 +1,22 @@
+{:version      {:major 2
+                :minor 0
+                :patch 0}
+ :version-type :semver3
+ :changes      {:added      ["`brewtility.units.color` for converting between SRM, EBC, and Lovibond."
+                             "`brewtility.units.pressure` for converting between PSI, Bar, etc."
+                             "`brewtility.units.specific-gravity` for converting Specific Gravity."
+                             "`brewtility.units.temperature` for converting between Celsius, Fahrenheit, and Kelvin."
+                             "`brewtility.units.time` for converting between seconds, minutes, hours, etc."
+                             "`brewtility.units.volume` for converting between gallons, liters, etc."
+                             "`brewtility.units.weight` for converting between pounds, kilograms, etc."
+                             "`brewtility.units.options` to introduce the symbolic keyword pattern"
+                             "Display functions for all unit types."]
+                :changed    ["Internal functions that convert between unit systems now use `brewtility.units`"]
+                :deprecated []
+                :removed    ["`brewility.color` has been removed in favor of `brewtility.units.color`"
+                             "`brewtility.units/convert-weight` has been removed in favor of `brewtility.units/convert` and `brewtility.units.weight/convert`"
+                             "`brewtility.units/convert-volume` has been removed in favor of `brewtility.units/convert` and `brewtility.units.volume/convert`"
+                             "`brewtility.units/convert-temperature` has been removed in favor of `brewtility.units/convert` and `brewtility.units.temperature/convert`"]
+                :fixed      []
+                :security   []}
+ :timestamp    "2023-06-11T18:47:32.340619900Z"}

CHANGELOG.md

@@ -6,13 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## Table of Contents
 
+* [2.0.0 - 2023-06-11](#200---2023-06-11)
 * [1.5.0 - 2023-02-13](#150---2023-02-13)
 * [1.4.0 - 2023-02-12](#140---2023-02-12)
 * [1.3.0 - 2023-02-12](#130---2023-02-12)
 * [1.2.0 - 2022-07-10](#120---2022-07-10)
 * [1.1.0 - 2020-08-15](#110---2020-08-15)
 * [1.0.0 - 2020-07-19](#100---2020-07-19)
 
+## 2.0.0 - 2023-06-11
+
+* Added
+  * `brewtility.units.color` for converting between SRM, EBC, and Lovibond.
+  * `brewtility.units.pressure` for converting between PSI, Bar, etc.
+  * `brewtility.units.specific-gravity` for converting Specific Gravity.
+  * `brewtility.units.temperature` for converting between Celsius, Fahrenheit, and Kelvin.
+  * `brewtility.units.time` for converting between seconds, minutes, hours, etc.
+  * `brewtility.units.volume` for converting between gallons, liters, etc.
+  * `brewtility.units.weight` for converting between pounds, kilograms, etc.
+  * `brewtility.units.options` to introduce the symbolic keyword pattern
+  * Display functions for all unit types.
+* Changed
+  * Internal functions that convert between unit systems now use `brewtility.units`
+* Removed
+  * `brewility.color` has been removed in favor of `brewtility.units.color`
+  * `brewtility.units/convert-weight` has been removed in favor of `brewtility.units/convert` and `brewtility.units.weight/convert`
+  * `brewtility.units/convert-volume` has been removed in favor of `brewtility.units/convert` and `brewtility.units.volume/convert`
+  * `brewtility.units/convert-temperature` has been removed in favor of `brewtility.units/convert` and `brewtility.units.temperature/convert`
+
 ## 1.5.0 - 2023-02-13
 
 * Added

README.md

@@ -31,12 +31,18 @@ Below are examples of provided functionality for each namespace.
 The library does provide access to other functions, but those primarily exist in support of those outlined here.
 
 - [Calculations](doc/api/calculations.md)
-- [Color](doc/api/color.md)
 - [Precision](doc/api/precision.md)
 - [Predicates](doc/api/predicates.md)
 - [Units of Measure](doc/api/units.md)
 - [Wrapping](doc/api/wrapping.md)
 
+## Common Patterns
+
+Brewtility follows several conventions and design patterns that result in artifacts available to library consumers.
+These are not strictly required for use; however, they provide additional documentation and ease-of-use to those who adopt them.
+
+- [Symbolic Keywords](doc/patterns/symbolic_keywords.md)
+
 ## Testing
 
 [doo](https://github.com/bensu/doo), a Leiningen plugin used to run ClojureScript tests in many JS environments, is already in `project.clj`.

doc/api/units.md

@@ -1,94 +1,169 @@
 # Units of Measure
 
-Beer has become an international interest/
+Beer has become an international interest.
 Additionally, brewing spans across the commercial and home environments.
 As a result, the systems of measure and scales of measure can very greatly between brewers.
 The BeerXML spec clearly delineates what units of measure are to be used to storing and transmitting data; however, they also allow users to pass `display` formats for values.
 These are used to translate uniform, machine-friendly systems into more appropriate systems and scales based on geographic region and user case.
 
-## Systems of Measure
+The `brewtility.units` namespace contains functions to convert between different systems and units of measure across several different types of measurement.
+Additionally, this namespace may be used to render common display formats.
 
-Brewtility supports four systems of measure:
+The names of these systems and units are frequently used in code, and shorthand symbolic references to these names may be found in `brewtility.units.options`
 
-- [The British Imperial System](https://en.wikipedia.org/wiki/Imperial_units)
-- [The Metric System](https://en.wikipedia.org/wiki/Metric_system)
-- [The International System](https://en.wikipedia.org/wiki/International_System_of_Units)
-- [The US Customary Scale](https://en.wikipedia.org/wiki/United_States_customary_units)
+## Basic Use
 
-## Volume Conversion
-
-Given a `volume` in `source-measurement`, convert it to the `target-measurement`.
-Supported measurements are:
-
-- Teaspoon
-- Tablespoon
-- Imperial Fluid Ounce
-- American Fluid Ounce
-- Cup
-- Imperial Pint
-- American Pint
-- Imperial Quart
-- American Quart
-- Imperial Gallon
-- American Gallon
-- Litre (Or Liter, depending on regional convention)
-- Millilitre (Or Milliliter, depending on regional convention)
+The majority of the functionality belongs to the functions `convert` and `display`.
+This provides a consistent interface to every system of measure, unit type, and more.
 
 ```clj
-(:require [brewtility.units :refer :all])
+(:require [brewtility.units :as units]
+          [brewtility.units.options :as options]
+          [brewtility.units.volume :as volume])
 
-(convert-volume 1.0 :liter :litre)
+;; You can use the keys in `brewtility.units.options` as arguments.
+;; This guarantees you don't have typos in code, and can link to helpful documentation
+(units/convert units/volume 1.0 options/liter options/litre)
 ;; => 1.0
 
-(convert-volume 20 :teaspoon :liter)
+;; Or, if you prefer, bare keywords are accepted too
+(units/convert units/volume 20 :teaspoon :liter)
 ;; => 0.099
 
-(convert-volume 9.99209 :imperial-pint :american-pint)
+;; If you only plan on dealing with volumes,
+;;   then you can import the `brewtility.units.volume` namespace
+(volume/convert 9.99209 :imperial-pint :american-pint)
 ;; => 12.0
+
+;; You can also render display values
+(units/display :volume 1.5 :liter)
+;; => \"1.5 l\"
+
+;; The keys in `brewtility.units.options` are also acceptable
+(units/display options/volume 1.5 options/liter)
+;; => \"1.5 l\"
+
+;; You may supply additional options, such as the default precision for rounding
+;;   and the type of suffix to use
+(units/display options/volume 1.45 options/liter {options/precision 1})
+;; => \"1.5 l\"
+
+(units/display options/volume 1.45 options/liter {options/suffix options/full})
+;; => \"1.45 liter\"
+
+;; Like `convert`, you can also call the measurement-type's functionality directly
+(volume/display 1.45 options/liter {options/precision 1})
+;; => \"1.5 l\"
+
+;; And, of course, the symbolic keywords are ultimately plain keywords.
+(volume/display 1.45 :liter {:suffix :full :precision 1})
+;; => \"1.5 liter\"
 ```
 
-## Weight Conversion
+## Supported Systems
 
-Given a `weight` in `source-measurement`, convert it to the `target-measurement`.
-Supported measurements are:
+Brewtility supports four systems of measure:
 
-- Ounce
-- Pound
-- Milligram
-- Gram
-- Kilogram
+- [The British Imperial System](https://en.wikipedia.org/wiki/Imperial_units)
+- [The Metric System](https://en.wikipedia.org/wiki/Metric_system)
+- [The International System](https://en.wikipedia.org/wiki/International_System_of_Units)
+- [The US Customary Scale](https://en.wikipedia.org/wiki/United_States_customary_units)
 
-```clj
-(:require [brewtility.units :refer :all])
+These are the most commonly seen systems in brewing.
+There are measurement functions for the most common types of measurements within these systems:
 
-(convert-weight 1.0 :kilogram :kilogram)
-;; => 1.0
+- [Color](##color)
+- [Pressure](##pressure)
+- [Specific Gravity](##specific-gravity)
+- [Temperature](##temperature)
+- [Time](##time)
+- [Volume](##volume)
+- [Weight](##weight)
 
-(convert-weight 15.0 :pound :ounce)
-;; => 240.0
+### Color
 
-(convert-weight 1205.5 :milligram :pound)
-;; => 0.003
-```
+Currently, brewtility supports the following types of color:
 
-## Temperature Conversion
+- [SRM](https://en.wikipedia.org/wiki/Standard_Reference_Method)
+- [EBC](https://en.wikipedia.org/wiki/European_Brewery_Convention)
+- [Lovibond](https://en.wikipedia.org/wiki/Beer_measurement#Colour)
+- [RGBa](https://en.wikipedia.org/wiki/RGBA_color_model)
 
-Given a `temperature` in `source-measurement`, convert it to the `target-measurement`.
-Supported measurements are:
+The `RGBa` system is special, as it can only be used as an argument for the result of a unit conversion.
+Unfortunately, there is not a great deterministic way to cast the values back to the other systems.
+brewtility will thrown an exception in this case and explain the problem.
 
-- Celsius (Or Centigrade, depending on regional convention. Or C, for convenience)
-- Kelvin (Or K, for convenience)
-- Fahrenheit (Or F, for convenience)
+### Pressure
 
-```clj
-(:require [brewtility.units :refer :all])
+Currently, brewtility supports the following types of pressure:
 
-(convert-temperature 32.0 :fahrenheit :fahrenheit)
-;; => 32.0
+- [pascal](https://en.wikipedia.org/wiki/Pascal_(unit)#Multiples_and_submultiples)
+- [kilopascal](https://en.wikipedia.org/wiki/Pascal_(unit)#Multiples_and_submultiples)
+- [bar](https://en.wikipedia.org/wiki/Bar_(unit))
+- [atmosphere](https://en.wikipedia.org/wiki/Atmosphere_(unit))
+- [torr](https://en.wikipedia.org/wiki/Torr)
+- [psi](<https://en.wikipedia.org/wiki/Pound-force_per_square_inch>
 
-(convert-temperature 0.0 :c :f)
-;; => 32.0
+### Specific Gravity
 
-(convert-temperature 2016.3 :kelvin :c)
-;; => 1743.15
-```
+Currently, brewtility supports the following types of specific gravity:
+
+- [specific-gravity](https://en.wikipedia.org/wiki/Specific_gravity)
+
+While there is currently only one system, the same namespace and functionality exists as the other measurement types.
+This allows for progressive evolution, and provides a consistent interface to every measurement type encoded in the BeerXML specification.
+
+### Temperature
+
+Currently, brewtility supports the following types of temperature measurements:
+
+- [celsius](https://en.wikipedia.org/wiki/Celsius)
+- [fahrenheit](https://en.wikipedia.org/wiki/Fahrenheit)
+- [kelvin](https://en.wikipedia.org/wiki/Kelvin_(unit))
+
+Given the prevalence of shorthand names in temperature measurements, brewtility also accepts `c`, `k`, and `f`.
+
+### Time
+
+Currently, brewtility supports the following types of time measurements:
+
+- [microsecond](https://en.wikipedia.org/wiki/Microsecond)
+- [nanosecond](https://en.wikipedia.org/wiki/Nanosecond)
+- [millisecond](https://en.wikipedia.org/wiki/Millisecond)
+- [second](https://en.wikipedia.org/wiki/Second)
+- [minute](https://en.wikipedia.org/wiki/Minute)
+- [hour](https://en.wikipedia.org/wiki/Hour)
+- [day](https://en.wikipedia.org/wiki/Day)
+- [week](https://en.wikipedia.org/wiki/Week)
+
+### Volume
+
+Currently, brewtility supports the following types of volume:
+
+- [american-fluid-ounce](https://en.wikipedia.org/wiki/Fluid_ounce)
+- [american-gallon](https://en.wikipedia.org/wiki/Gallon)
+- [american-pint](https://en.wikipedia.org/wiki/Pint)
+- [american-quart](https://en.wikipedia.org/wiki/Quart)
+- [cup](https://en.wikipedia.org/wiki/Cup_(unit))
+- [imperial-fluid-ounce](https://en.wikipedia.org/wiki/Fluid_ounce)
+- [imperial-gallon](https://en.wikipedia.org/wiki/Gallon)
+- [imperial-pint](https://en.wikipedia.org/wiki/Pint)
+- [imperial-quart](https://en.wikipedia.org/wiki/Quart)
+- [liter](https://en.wikipedia.org/wiki/Litre)
+- [litre](https://en.wikipedia.org/wiki/Litre)
+- [milliliter](https://en.wikipedia.org/wiki/Millilitre)
+- [millilitre](https://en.wikipedia.org/wiki/Millilitre)
+- [tablespoon](https://en.wikipedia.org/wiki/Tablespoon)
+- [teaspoon](https://en.wikipedia.org/wiki/Teaspoon))
+
+Given the prevalence of the French spellings in English recipes, both `:litre` and `:liter` can be passed as options.
+
+### Weight
+
+Currently, brewtility supports the following types of weight:
+
+- [gram](https://en.wikipedia.org/wiki/Gram)
+- [milligram](https://en.wikipedia.org/wiki/Milligram)
+- [kilogram](https://en.wikipedia.org/wiki/Kilogram)
+- [ounce](https://en.wikipedia.org/wiki/Ounce)
+- [pound](https://en.wikipedia.org/wiki/Pound_(mass))

doc/cljdoc.edn

@@ -2,11 +2,14 @@
                    ["Changelog" {:file "CHANGELOG.md"}]
                    ["Community" {}
                     ["Contributing" {:file "CONTRIBUTING.md"}]
-                    ["Code of Conduct" {:file "CODE_OF_CONDUCT.md"}]]
+                    ["Code of Conduct" {:file "CODE_OF_CONDUCT.md"}]
+                    ["Security Policy" {:file "SECURITY.md"}]]
                    ["Functionality" {}
                     ["Calculations" {:file "doc/api/calculations.md"}]
                     ["Color" {:file "doc/api/color.md"}]
                     ["Precision" {:file "doc/api/precision.md"}]
                     ["Predicates" {:file "doc/api/predicates.md"}]
                     ["Units of Measure" {:file "doc/api/units.md"}]
-                    ["Wrapping" {:file "doc/api/wrapping.md"}]]]}
+                    ["Wrapping" {:file "doc/api/wrapping.md"}]]
+                   ["Adopted Patterns" {}
+                    ["Symbolic Keywords" {:file "doc/patterns/symbolic_keywords.md"}]]]}