Optional dependency on binary via package flags

.travis.yml

@@ -20,6 +20,7 @@ env:
 - ARGS="--resolver lts-13"
 - ARGS="--resolver lts-15"
 - ARGS="--resolver lts-17"
+- ARGS="--resolver lts-17" FLAGS="--flag dimensional:binary"
 
 before_install:
 # Download and unpack the stack executable
@@ -36,7 +37,7 @@ before_install:
 # This line does all of the work: build the library,
 # executables, and test suites, and runs the test suites. --no-terminal works
 # around some quirks in Travis's terminal implementation.
-script: stack $ARGS --no-terminal test --haddock --no-haddock-deps --bench
+script: stack $ARGS --no-terminal test $FLAGS --haddock --no-haddock-deps --bench
 
 # Caching so the next build will be fast too.
 cache:

CHANGELOG.md

@@ -1,3 +1,8 @@
+1.6 (2024-08)
+-------------
+
+* Added a package flag `binary`, enabling optional dependency on the `binary` package to provide instances of `Binary`.
+
 1.5 (2022-06)
 -------------
 * Add Julian `decade` and `millennium` to `NonSI`.

README.md

@@ -64,6 +64,23 @@ main = do
          putStrLn $ "The journey requires " ++ show wholeSeconds ++ " seconds, rounded up to the nearest second."
 ```
 
+## Package Flags
+
+Package flags enable users get instances for `Quantity` that are useful to interoperate with various popular packages, without adding dependencies for those who do not need it.
+
+To provide `Binary` serialization for `Quantity` from the `binary` package, the `binary` flag can be used like so:
+
+```bash
+cabal install dimensional -f binary
+```
+
+If you use a `cabal.project` file, you can instead add the following clause to activate this package flag:
+
+```txt
+package dimensional
+    flags: +binary
+```
+
 ## Contributing
 
 For project information (issues, updates, wiki, examples) see:

dimensional.cabal

@@ -37,6 +37,11 @@ extra-source-files:  README.md,
                      examples/GM.lhs,
                      examples/NewtonianMechanics.hs
 
+flag binary
+  description: Provide instances for use with the binary package.
+  default:     False
+  manual:      True
+
 source-repository head
   type:     git
   location: https://github.com/bjornbm/dimensional/
@@ -72,6 +77,9 @@ library
                        Numeric.Units.Dimensional.Float
   other-modules:       Numeric.Units.Dimensional.Internal
                        Numeric.Units.Dimensional.UnitNames.Internal
+  if flag(binary)
+    build-depends:     binary >= 0.7 && < 1
+    cpp-options:       -DUSE_BINARY
 
 test-suite tests
   type:                exitcode-stdio-1.0

src/Numeric/Units/Dimensional/Dimensions/TermLevel.hs

@@ -1,6 +1,7 @@
 {-# OPTIONS_HADDOCK not-home, show-extensions #-}
 
 {-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE CPP #-}
 {-# LANGUAGE DefaultSignatures #-}
 {-# LANGUAGE DeriveDataTypeable #-}
 {-# LANGUAGE DeriveGeneric #-}
@@ -36,6 +37,9 @@ module Numeric.Units.Dimensional.Dimensions.TermLevel
 where
 
 import Control.DeepSeq
+#if USE_BINARY
+import qualified Data.Binary
+#endif
 import Data.Data
 import Data.Semigroup (Semigroup(..))
 import Data.Monoid (Monoid(..))
@@ -66,6 +70,10 @@ instance Monoid Dimension' where
   mempty = dOne
   mappend = (<>)
 
+#if USE_BINARY
+instance Data.Binary.Binary Dimension'
+#endif
+
 -- | The dimension of a dynamic value, which may not have any dimension at all.
 data DynamicDimension = NoDimension -- ^ The value has no valid dimension.
                       | SomeDimension Dimension' -- ^ The value has the given dimension.
@@ -74,6 +82,10 @@ data DynamicDimension = NoDimension -- ^ The value has no valid dimension.
 
 instance NFData DynamicDimension where
 
+#if USE_BINARY
+instance Data.Binary.Binary DynamicDimension
+#endif
+
 -- | Dimensional values, or those that are only possibly dimensional, inhabit this class,
 -- which allows access to a term-level representation of their dimension.
 class HasDynamicDimension a where

src/Numeric/Units/Dimensional/Dynamic.hs

@@ -9,6 +9,7 @@
 Defines types for manipulation of units and quantities without phantom types for their dimensions.
 -}
 
+{-# LANGUAGE CPP #-}
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE DeriveDataTypeable #-}
 {-# LANGUAGE DeriveGeneric #-}
@@ -37,6 +38,9 @@ module Numeric.Units.Dimensional.Dynamic
 
 import Control.DeepSeq
 import Control.Monad
+#if USE_BINARY
+import qualified Data.Binary
+#endif
 import Data.Data
 import Data.ExactPi
 import Data.Kind
@@ -115,6 +119,10 @@ instance Num a => Monoid (AnyQuantity a) where
   mempty = demoteQuantity (1 Dim.*~ one)
   mappend = (<>)
 
+#if USE_BINARY
+instance (Data.Binary.Binary a) => Data.Binary.Binary (AnyQuantity a)
+#endif
+
 -- | Possibly a 'Quantity' whose 'Dimension' is only known dynamically.
 --
 -- By modeling the absence of a value, this type differs from 'AnyQuantity' in that it may
@@ -194,6 +202,10 @@ instance Num a => Monoid (DynQuantity a) where
   mempty = demoteQuantity (1 Dim.*~ one)
   mappend = (<>)
 
+#if USE_BINARY
+instance (Data.Binary.Binary a) => Data.Binary.Binary (DynQuantity a)
+#endif
+
 -- | A 'DynQuantity' which does not correspond to a value of any dimension.
 invalidQuantity :: DynQuantity a
 invalidQuantity = DynQuantity NoDimension $ error "Attempt to evaluate the value of an invalid quantity."

src/Numeric/Units/Dimensional/Internal.hs

@@ -28,6 +28,9 @@ where
 import Control.Applicative
 import Control.DeepSeq
 import Data.AEq (AEq)
+#if USE_BINARY
+import qualified Data.Binary
+#endif
 import Data.Coerce (coerce)
 import Data.Data
 import Data.Kind
@@ -137,6 +140,10 @@ instance (Num a) => Monoid (SQuantity s d a) where
   mempty = Quantity 0
   mappend = (<>)
 
+#if USE_BINARY
+deriving instance (Data.Binary.Binary a) => Data.Binary.Binary (SQuantity s d a)
+#endif
+
 {-
 
 = Dimensionless =