WIP

doc/api/units.md

@@ -30,6 +30,10 @@ This provides a consistent interface to every system of measure, unit type, and
 (units/convert units/volume 20 :teaspoon :liter)
 ;; => 0.099
 
+;; You can also round the conversion to a specified precision
+(units/convert units/volume 20 :teaspoon :liter {:precision 1})
+;; => 0.1
+
 ;; 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)

doc/cljdoc.edn

@@ -7,7 +7,6 @@
                     ["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"}]

src/brewtility/calculations.cljc

@@ -19,11 +19,11 @@
   (if (and (number? amount)
            (number? color))
     (let [is-not-grain? (not (fermentables/grain? fermentable))
-          ; MCU is calculated against pounds
+          ;; MCU is calculated against pounds
           kg->lbs       (fn [w] (weight/convert w options/kilogram options/pound))]
       (cond-> fermentable
         true          (update :amount kg->lbs)
-        ; Grain color is in Lovibond, all other fermentables use SRM
+        ;; Grain color is in Lovibond, all other fermentables use SRM
         is-not-grain? (update :color #(color/convert % options/srm options/lovibond))))
     (throw (ex-info "Cannot calculate color with non-numeric values" {:amount amount
                                                                       :color  color}))))

src/brewtility/enrich/fermentables.cljc

@@ -38,8 +38,7 @@
    An option map may be passed as an optional second argument to this function to override the default behavior.
    Supported keys include:
 
-     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false."
+     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false."
   {:added    "2.1"
    :see-also ["brewtility.predicates.fermentables/grain?"
               "brewtility.predicates.fermentables/adjunct?"
@@ -63,8 +62,7 @@
    An option map may be passed as an optional second argument to this function to override the default behavior.
    Supported keys include:
 
-     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false."
+     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false."
   {:added    "2.1"
    :see-also ["brewtility.predicates.fermentables/grain?"
               "brewtility.predicates.fermentables/adjunct?"
@@ -88,8 +86,7 @@
    An option map may be passed as an optional second argument to this function to override the default behavior.
    Supported keys include:
 
-     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false."
+     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false."
   {:added    "2.1"
    :see-also ["brewtility.predicates.fermentables/grain?"
               "brewtility.predicates.fermentables/adjunct?"
@@ -113,8 +110,7 @@
    An option map may be passed as an optional second argument to this function to override the default behavior.
    Supported keys include:
 
-     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false."
+     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false."
   {:added    "2.1"
    :see-also ["brewtility.predicates.fermentables/grain?"
               "brewtility.predicates.fermentables/adjunct?"
@@ -138,8 +134,7 @@
    An option map may be passed as an optional second argument to this function to override the default behavior.
    Supported keys include:
 
-     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false."
+     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false."
   {:added    "2.1"
    :see-also ["brewtility.predicates.fermentables/grain?"
               "brewtility.predicates.fermentables/adjunct?"
@@ -163,8 +158,7 @@
    An option map may be passed as an optional second argument to this function to override the default behavior.
    Supported keys include:
 
-     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false."
+     - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false."
   {:added    "2.1"
    :see-also ["brewtility.predicates.fermentables/extract?"
               "enrich-fermentable"
@@ -269,7 +263,6 @@
    The following keys are supported for controlling high-level behavior:
 
      - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false.
      - `:system-of-measure`: The unit system of measure to convert the amount into. Defaults to `:us`. Acceptable values are:
         - `:imperial`: The [British imperial](https://en.wikipedia.org/wiki/Imperial_units) system of measure.
         - `:metric`: The [metric system](https://en.wikipedia.org/wiki/Metric_system) of measure.
@@ -328,7 +321,6 @@
    The following keys are supported for controlling high-level behavior:
 
      - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false.
      - `:system-of-measure`: The unit system of measure to convert the amount into. Defaults to `:us`. Acceptable values are:
         - `:imperial`: The [British imperial](https://en.wikipedia.org/wiki/Imperial_units) system of measure.
         - `:metric`: The [metric system](https://en.wikipedia.org/wiki/Metric_system) of measure.
@@ -378,7 +370,6 @@
    The following keys are supported for controlling high-level behavior:
 
      - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false.
      - `:system-of-measure`: The unit system of measure to convert the amount into. Defaults to `:us`. Acceptable values are:
         - `:imperial`: The [British imperial](https://en.wikipedia.org/wiki/Imperial_units) system of measure.
         - `:metric`: The [metric system](https://en.wikipedia.org/wiki/Metric_system) of measure.
@@ -428,7 +419,6 @@
    The following keys are supported for controlling high-level behavior:
 
      - `:uppercase?` - If the string comparison for the `:type` should be cast to UPPERCASE instead of lowercase. Default is false.
-     - `:coerce` - If the `:type` field should be coerced to a string for comparison. Default is false.
      - `:system-of-measure`: The unit system of measure to convert the amount into. Defaults to `:us`. Acceptable values are:
         - `:imperial`: The [British imperial](https://en.wikipedia.org/wiki/Imperial_units) system of measure.
         - `:metric`: The [metric system](https://en.wikipedia.org/wiki/Metric_system) of measure.

src/brewtility/enrich/impl.cljc

@@ -5,7 +5,8 @@
   {:no-doc              true
    :added               "2.1"
    :implementation-only true}
-  (:require [brewtility.units :as units]
+  (:require [brewtility.precision :as precision]
+            [brewtility.units :as units]
             [brewtility.units.color :as color]
             [brewtility.units.options :as options]
             [brewtility.units.pressure :as pressure]
@@ -23,80 +24,88 @@
 
 
 (def value-key
-  "The key to source data from in `->displayable` functions"
+  "The key to source data from in `enrich-displayable-*` functions"
   :value-key)
 
+(def low-value-key
+  "The key to source data from in `enrich-displayable-*` functions for the lower end of the range"
+  :low-value-key)
+
+(def high-value-key
+  "The key to source data from in `enrich-displayable-*` functions for the higher end of the range"
+  :high-value-key)
+
 
 (def display-key
-  "The key to store displayable data in in `->displayable` functions"
+  "The key to store displayable data in in `-enrich-displayable-*` functions"
   :display-key)
 
 
 (def fine-grain-target-units
-  "The target units to use for fine-grain toggling of displayable units in `->displayable` functions"
+  "The target units to use for fine-grain toggling of displayable units in `enrich-displayable-*` functions"
   :fine-grain-target-units)
 
 
 (def fine-grain-precision
-  "The suffix to use for fine-grain setting of precision in `->displayable` functions"
+  "The suffix to use for fine-grain setting of precision in `-enrich-displayable-*` functions"
   :fine-grain-precision)
 
 
 (def fine-grain-suffix
-  "The suffix to use for fine-grain setting of precision in `->displayable` functions"
+  "The suffix to use for fine-grain setting of precision in `enrich-displayable-*` functions"
   :fine-grain-suffix)
 
 
 (def default-color-by-system
-  "The default color to use for each system in `->displayable` functions."
+  "The default color to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/srm
    options/metric               options/srm
    options/us-customary         options/srm
    options/international-system options/srm})
 
 
 (def default-pressure-by-system
-  "The default pressure to use for each system in `->displayable` functions."
+  "The default pressure to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/psi
    options/metric               options/kilopascal
    options/us-customary         options/psi
    options/international-system options/kilopascal})
 
 
 (def default-specific-gravity-by-system
-  "The default specific gravity to use for each system in `->displayable` functions."
+  "The default specific gravity to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/specific-gravity
    options/metric               options/specific-gravity
    options/us-customary         options/specific-gravity
    options/international-system options/specific-gravity})
 
 
 (def default-temperature-by-system
-  "The default temperature to use for each system in `->displayable` functions."
+  "The default temperature to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/fahrenheit
    options/metric               options/celsius
    options/us-customary         options/fahrenheit
    options/international-system options/celsius})
 
 
 (def default-time-by-system
-  "The default time to use for each system in `->displayable` functions."
+  "The default time to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/minute
    options/metric               options/minute
    options/us-customary         options/minute
    options/international-system options/minute})
 
 
 (def default-volume-by-system
-  "The default volume to use for each system in `->displayable` functions."
+  "The default volume to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/imperial-gallon
    options/metric               options/litre
    options/us-customary         options/american-gallon
    options/international-system options/litre})
 
 
 (def default-weight-by-system
-  "The default weight to use for each system in `->displayable` functions."
+  "The default weight to use for each system in `enrich-displayable-*` functions."
   {options/imperial             options/pound
    options/metric               options/kilogram
    options/us-customary         options/pound
@@ -233,7 +242,8 @@
 ;; Enricher argument validation functions
 
 (defn valid-unit-for-measurement-type?
-  "TODO: Fill me in"
+  "A functions that confirms if a given `unit` is valid for a given `measurement-type`.
+   If the `unit` is not valid, a Java Exception or Javascript Error is thrown with information on the invalid options."
   {:added    "2.1"
    :no-doc   false}
   [measurement-type unit]
@@ -305,7 +315,21 @@
 
 
 (defn enrich-displayable-units
-  "TODO: Fill me in"
+  "A function to enrich a `source-data` map with a displayable value for a given `measurement-type`.
+   This function will convert the `source-value` from `source-units` to `target-units` and store the result in `display-key`.
+   If the `source-value` is not present, the `source-data` is returned unmodified.
+   The function will default to the following display options:
+
+   - `system-of-measure` : `:us-customary`
+   - `suffix` : `:short`
+   - `precision` : `3`
+   - `source-units` : The BeerXML default system of measure for the given `measurement-type` (e.g. `:kilogram` for `:weight`)
+
+   Customization of function behavior is handled by the following keys in the `opts` map, and will always take precedence over defaults:
+
+   - `fine-grain-precsion` : The precision to use for this displayable value. Enricher functions control their behavior off of uniquely named keys, so behavior can be customized per field
+   - `fine-grain-suffix` : The suffix to use for this displayable value. Enricher functions control their behavior off of uniquely named keys, so behavior can be customized per field
+   - `fine-grain-target-units` : The target units to use for this displayable value. Enricher functions control their behavior off of uniquely named keys, so behavior can be customized per field"
   {:added "2.1"
    :no-doc true}
   [measurement-type
@@ -336,7 +360,21 @@
 
 
 (defn enrich-displayable-range
-  "TODO: Fill me in"
+  "A function to enrich a `source-data` map with a displayable range for a given `measurement-type`.
+     This function will convert the `low-source-value` and `high-source-value` from `source-units` to `target-units` and store the result in `display-key`.
+     If the `source-value` is not present, the `source-data` is returned unmodified.
+     The function will default to the following display options:
+
+     - `system-of-measure` : `:us-customary`
+     - `suffix` : `:short`
+     - `precision` : `3`
+     - `source-units` : The BeerXML default system of measure for the given `measurement-type` (e.g. `:kilogram` for `:weight`)
+
+     Customization of function behavior is handled by the following keys in the `opts` map, and will always take precedence over defaults:
+
+     - `fine-grain-precsion` : The precision to use for this displayable range. Enricher functions control their behavior off of uniquely named keys, so behavior can be customized per field
+     - `fine-grain-suffix` : The suffix to use for this displayable range. Enricher functions control their behavior off of uniquely named keys, so behavior can be customized per field
+     - `fine-grain-target-units` : The target units to use for this displayable range. Enricher functions control their behavior off of uniquely named keys, so behavior can be customized per field"
   {:added    "2.1"
    :no-doc   true
    :see-also ["enrich-displayable-units"]}
@@ -356,13 +394,13 @@
             precision               (or fine-grain-precision precision)
             suffix                  (or fine-grain-suffix suffix)
             opts                    (parse-enrich-displayable-units-opts
-                                      measurement-type
-                                      {:target-units             target-units
-                                       :source-units             source-units
-                                       options/system-of-measure system-of-measure
-                                       options/precision         precision
-                                       options/suffix            suffix})
-            converted-low-value     (units/convert measurement-type low-source-value source-units target-units)
+                                     measurement-type
+                                     {:target-units             target-units
+                                      :source-units             source-units
+                                      options/system-of-measure system-of-measure
+                                      options/precision         precision
+                                      options/suffix            suffix})
+            converted-low-value     (units/convert measurement-type low-source-value source-units target-units {options/precision precision})
             displayable-high-value  (->displayable-units measurement-type high-source-value source-units target-units opts)
             displayable-range       (str converted-low-value " - " displayable-high-value)]
         (assoc source-data display-key displayable-range))

src/brewtility/predicates/equipment.cljc

@@ -16,7 +16,8 @@
    In the BeerXML spec, this behavior is implicitly falsey.
    Therefore, if the :calc-boil-volume field is not present, this function will explicitly return false."
   {:added "1.5"}
-  [equipment]
-  (if (contains? equipment :calc-boil-volume)
-    (:calc-boil-volume equipment)
-    false))
+  ([equipment] (calculated-boil-volume? equipment {})) ; Added to match the arity of the other predicate functions
+  ([equipment _opts]
+   (if (contains? equipment :calc-boil-volume)
+     (:calc-boil-volume equipment)
+     false)))

src/brewtility/predicates/fermentables.cljc

@@ -19,10 +19,13 @@
 
    Therefore, if the :add-after-boil field is not present, this function will explicitly return false."
   {:added "1.5"}
-  [fermentable]
-  (if (contains? fermentable :add-after-boil)
-    (:add-after-boil fermentable)
-    false))
+  ([fermentable] (add-after-boil? fermentable {}))
+  ;; Added to match the arity of the other predicate functions
+
+  ([fermentable _opts]
+   (if (contains? fermentable :add-after-boil)
+     (:add-after-boil fermentable)
+     false)))
 
 
 (defn grain?