added doctests

.github/workflows/haskell-ci.yml

@@ -1,10 +1,18 @@
+name: build
 on: [push]
-name: haskell-ci
+
+# INFO: The following configuration block ensures that only one build runs per branch,
+# which may be desirable for projects with a costly build process.
+# Remove this block from the CI workflow to let each CI job run to completion.
+concurrency:
+  group: build-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   hlint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: haskell-actions/hlint-setup@v2
     - uses: haskell-actions/hlint-run@v2
       with:
@@ -13,90 +21,68 @@ jobs:
   ormolu:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: haskell-actions/run-ormolu@v11
-  cabal:
+      - uses: actions/checkout@v4
+      - uses: haskell-actions/run-ormolu@v16
+  build:
     name: GHC ${{ matrix.ghc-version }} on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        ghc-version: ['9.8', '9.6', '9.4', '9.2', '8.10']
-        docspec: [false]
-        experimental: [false]
+        ghc-version: ['9.10', '9.8', '9.6']
 
         include:
           - os: windows-latest
-            ghc-version: '9.6'
+            ghc-version: '9.8'
           - os: macos-latest
-            ghc-version: '9.6'
-          - os: ubuntu-latest
-            ghc-version: '9.6'
-            docspec: true
-            experimental: true
-            name: docspec
+            ghc-version: '9.8'
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up GHC ${{ matrix.ghc-version }}
         uses: haskell-actions/setup@v2
         id: setup
         with:
           ghc-version: ${{ matrix.ghc-version }}
 
-      - name: Installed minor versions of GHC and Cabal
-        shell: bash
-        run: |
-          GHC_VERSION=$(ghc --numeric-version)
-          CABAL_VERSION=$(cabal --numeric-version)
-          echo "GHC_VERSION=${GHC_VERSION}"     >> "${GITHUB_ENV}"
-          echo "CABAL_VERSION=${CABAL_VERSION}" >> "${GITHUB_ENV}"
-
       - name: Configure the build
         run: |
           cabal configure --enable-tests --enable-benchmarks --disable-documentation
           cabal build --dry-run
         # The last step generates dist-newstyle/cache/plan.json for the cache key.
 
       - name: Restore cached dependencies
-        uses: actions/cache/restore@v3
+        uses: actions/cache/restore@v4
         id: cache
+        env:
+          key: ${{ runner.os }}-ghc-${{ steps.setup.outputs.ghc-version }}-cabal-${{ steps.setup.outputs.cabal-version }}
         with:
           path: ${{ steps.setup.outputs.cabal-store }}
-          key: ${{ runner.os }}-ghc-${{ env.GHC_VERSION }}-cabal-${{ env.CABAL_VERSION }}-plan-${{ hashFiles('**/plan.json') }}
-          restore-keys: |
-            ${{ runner.os }}-ghc-${{ env.GHC_VERSION }}-cabal-${{ env.CABAL_VERSION }}-
+          key: ${{ env.key }}-plan-${{ hashFiles('**/plan.json') }}
+          restore-keys: ${{ env.key }}-
 
       - name: Install dependencies
+        # If we had an exact cache hit, the dependencies will be up to date.
+        if: steps.cache.outputs.cache-hit != 'true'
         run: cabal build all --only-dependencies
 
       # Cache dependencies already here, so that we do not have to rebuild them should the subsequent steps fail.
       - name: Save cached dependencies
-        uses: actions/cache/save@v3
-        # Caches are immutable, trying to save with the same key would error.
-        if: ${{ !steps.cache.outputs.cache-hit
-          || steps.cache.outputs.cache-primary-key != steps.cache.outputs.cache-matched-key }}
+        uses: actions/cache/save@v4
+        # If we had an exact cache hit, trying to save the cache would error because of key clash.
+        if: steps.cache.outputs.cache-hit != 'true'
         with:
           path: ${{ steps.setup.outputs.cabal-store }}
           key: ${{ steps.cache.outputs.cache-primary-key }}
 
       - name: Build
         run: cabal build all
 
+      - if: ${{ matrix.os == 'ubuntu-latest' && matrix.ghc-version == '9.8'}}
+        name: doctests
+        run: cabal run doctests
+
       - name: Check cabal file
         run: cabal check
-
-      - if: matrix.docspec
-        name: cabal-docspec
-        run: |
-          mkdir -p $HOME/.cabal/bin
-          echo "$HOME/.cabal/bin" >> $GITHUB_PATH
-          curl -sL https://github.com/phadej/cabal-extras/releases/download/cabal-docspec-0.0.0.20230406/cabal-docspec-0.0.0.20230406-x86_64-linux.xz > cabal-docspec.xz
-          echo '68fa9addd5dc453d533a74a763950499d4593b1297c9a05c3ea5bd1acc04c9dd cabal-docspec.xz' | sha256sum -c -
-          xz -d < cabal-docspec.xz > $HOME/.cabal/bin/cabal-docspec
-          rm -f cabal-docspec.xz
-          chmod a+x $HOME/.cabal/bin/cabal-docspec
-          $HOME/.cabal/bin/cabal-docspec --version
-          cabal-docspec

.gitignore

@@ -6,3 +6,5 @@ TAGS
 /.hie/
 /cabal.project.local*
 /.hkgr/
+/.ghc.environment.aarch64-darwin-9.10.1
+/checklist.org

.hlint.yaml

@@ -2,5 +2,6 @@
 - ignore: {name: Use if}
 - ignore: {name: Use last}
 - ignore: {name: Redundant multi-way if}
+- ignore: {name: Use =<<}
 # To generate a suitable file for HLint do:
 # $ hlint --default > .hlint.yaml

ChangeLog.md

@@ -0,0 +1,4 @@
+0.3.1
+===
+
+- added doctests

cabal.project

@@ -0,0 +1,4 @@
+packages:
+  formatn.cabal
+
+write-ghc-environment-files: always

formatn.cabal

@@ -1,6 +1,6 @@
 cabal-version: 3.0
 name: formatn
-version: 0.3.0.1
+version: 0.3.1.0
 license: BSD-3-Clause
 license-file: LICENSE
 copyright: Tony Day (c) 2016
@@ -12,15 +12,21 @@ bug-reports: https://github.com/tonyday567/formatn/issues
 synopsis: Formatting of doubles.
 description:
     This package provides support for number formatting styles, especially styles involving significant figure calculations.
-    .
+
     == Usage
-    .
+
     >>> import Data.FormatN
     >>> comma (Just 3) 1234
     1,230
 
 build-type: Simple
-tested-with: GHC ==8.6.5 || ==8.8.4 || ==8.10.7 || ==9.2.5 || ==9.4.7 || ==9.6.3 || ==9.8.1
+tested-with:
+    , GHC == 9.10.1
+    , GHC == 9.6.5
+    , GHC == 9.8.2
+extra-doc-files:
+    ChangeLog.md
+    readme.md
 
 source-repository head
     type: git
@@ -37,69 +43,25 @@ common ghc-options-stanza
         -Wredundant-constraints
 
 common ghc2021-stanza
-    if impl ( ghc >= 9.2 )
-        default-language: GHC2021
-
-    if impl ( ghc < 9.2 )
-        default-language: Haskell2010
-        default-extensions:
-            BangPatterns
-            BinaryLiterals
-            ConstrainedClassMethods
-            ConstraintKinds
-            DeriveDataTypeable
-            DeriveFoldable
-            DeriveFunctor
-            DeriveGeneric
-            DeriveLift
-            DeriveTraversable
-            DoAndIfThenElse
-            EmptyCase
-            EmptyDataDecls
-            EmptyDataDeriving
-            ExistentialQuantification
-            ExplicitForAll
-            FlexibleContexts
-            FlexibleInstances
-            ForeignFunctionInterface
-            GADTSyntax
-            GeneralisedNewtypeDeriving
-            HexFloatLiterals
-            ImplicitPrelude
-            InstanceSigs
-            KindSignatures
-            MonomorphismRestriction
-            MultiParamTypeClasses
-            NamedFieldPuns
-            NamedWildCards
-            NumericUnderscores
-            PatternGuards
-            PolyKinds
-            PostfixOperators
-            RankNTypes
-            RelaxedPolyRec
-            ScopedTypeVariables
-            StandaloneDeriving
-            StarIsType
-            TraditionalRecordSyntax
-            TupleSections
-            TypeApplications
-            TypeOperators
-            TypeSynonymInstances
-
-    if impl ( ghc < 9.2 ) && impl ( ghc >= 8.10 )
-        default-extensions:
-            ImportQualifiedPost
-            StandaloneKindSignatures
+    default-language: GHC2021
 
 library
     import: ghc-options-stanza
     import: ghc2021-stanza
     hs-source-dirs: src
     build-depends:
-        -- just for cabal-docspec --check-properties
-        , QuickCheck >=2.14.2 && <2.15
-        , base       >=4.7 && <5
+        , base       >=4.14 && <5
         , containers >=0.6 && <0.8
         , text       >=1.2 && <2.2
     exposed-modules: Data.FormatN
+
+test-suite doctests
+    import: ghc2021-stanza
+    main-is: doctests.hs
+    hs-source-dirs: test
+    build-depends:
+        , QuickCheck       >=2.14.2 && <2.16
+        , base             >=4.14 && <5
+        , doctest-parallel >=0.3 && <0.4
+    ghc-options: -threaded
+    type: exitcode-stdio-1.0

readme.md

@@ -0,0 +1,116 @@
+
+# formatn 
+
+[![img](https://img.shields.io/hackage/v/formatn.svg)](https://hackage.haskell.org/package/formatn) [![img](https://github.com/tonyday567/formatn/workflows/haskell-ci/badge.svg)](https://github.com/tonyday567/formatn/actions?query=workflow%3Ahaskell-ci)
+
+A library for support of:
+
+-   significant figure rounding of numbers, and
+-   common number formatting patterns.
+
+<a id="org95ded84"></a>
+
+# Usage
+
+    :reload
+    :set prompt "> "
+
+    :set -Wno-type-defaults
+    :set -XOverloadedStrings
+    import Data.FormatN
+
+    xs = [(-1),0,0.1,1,1.01,1.02,1.1,1.2]
+
+    fixed (Just 2) <$> xs
+    decimal (Just 2) <$> xs
+    formats False False (const DecimalStyle) (Just 2) xs
+    formats False True (const DecimalStyle) (Just 2) xs
+    distinguish 4 False True (const DecimalStyle) (Just 2) xs
+
+    Ok, 14 modules loaded.
+    > >
+    >
+    > ["-1.00","0.00","0.10","1.00","1.01","1.02","1.10","1.20"]
+    ["-1.0","0.0","0.10","1.0","1.0","1.0","1.1","1.2"]
+    ["-1.00","0.00","0.10","1.00","1.00","1.00","1.10","1.20"]
+    ["-1.0","0.0","0.1","1.0","1.0","1.0","1.1","1.2"]
+    ["-1.00","0.00","0.10","1.00","1.01","1.02","1.10","1.20"]
+
+
+<a id="orgb82f98d"></a>
+
+# getting 0 right
+
+
+<a id="orgaf42992"></a>
+
+## fixed
+
+    fixed (Just 3) <$> [0, 0.5, 1.5, 2.0]
+
+    ["0.000","0.500","1.500","2.000"]
+
+fixed defaults to representing Doubles in the same manner as Haskell does ie with a trailing &rsquo;.0&rsquo;
+
+    fixed Nothing <$> [0, 0.5, 1.5, 2]
+
+    ["0.0","0.5","1.5","2.0"]
+
+
+<a id="org1b53172"></a>
+
+## expt
+
+    expt Nothing 0
+
+    0e0
+
+    expt (Just 2) 1
+    expt (Just 2) 0
+
+    1.0e0
+    0.0e0
+
+
+<a id="org90e32fb"></a>
+
+## decimal
+
+    decimal Nothing 0
+    decimal (Just 1) 0
+    decimal (Just 3) 0
+
+    0
+    0
+    0.00
+
+
+<a id="orgbe4b502"></a>
+
+## percent
+
+percent is a little weird any way you cut it.
+
+    percent decimalSF (Just 4) 0
+    percent decimalSF (Just 4) 1
+
+    0.0%
+    100.0%
+
+
+<a id="org549dfe5"></a>
+
+## inclusion in lists
+
+    formats True False commaPrecStyle Nothing [0, 0.5, 1.5, 2]
+    formats True False commaPrecStyle (Just 1) [0, 1, 10]
+    formats True False commaPrecStyle (Just 1) [0, 0.5, 1.5, 2]
+    formats True False commaPrecStyle (Just 2) [0, 0.5, 1.5, 2]
+    formats True True commaPrecStyle (Just 6) [0, 0.5, 1.5, 2]
+
+    ["0.0","0.5","1.5","2.0"]
+    [" 0"," 1","10"]
+    ["0.0","0.5","2.0","2.0"]
+    ["0.00","0.50","1.50","2.00"]
+    ["0.0","0.5","1.5","2.0"]
+