sayable 1.1.0.0 → 1.1.1.0
raw patch · 3 files changed
+54/−4 lines, 3 filesdep ~basePVP ok
version bump matches the API change (PVP)
Dependency ranges changed: base
API changes (from Hackage documentation)
Files
- CHANGELOG.md +5/−0
- Text/Sayable.hs +45/−0
- sayable.cabal +4/−4
CHANGELOG.md view
@@ -1,5 +1,10 @@ # Revision history for sayable +## 1.1.1.0 -- 2023-06-20++* Add Haddock documentation showing examples for operators.+* Support GHC 9.6+ ## 1.1.0.0 -- 2023-01-17 * Added `&<`, `&<*`, and `&<?` operators to generate a newline between expressing
Text/Sayable.hs view
@@ -109,59 +109,97 @@ standard argument to use for building the output message from distinct parts. + >>> sez @"info" $ t'"hello" &- t'"world"+ "hello world"+ ['&+'] This is a variation of the standard '&-' operator that has no intervening space between the two arguments that are converted to a Sayable form. + >>> sez @"info" $ t'"hello" &+ t'"world"+ "helloworld"+ ['&%'] This is a variation of the standard '&-' operator that only requires the second argument to be an instances of Prettyprinter.Pretty instead of an instance of 'Sayable', which can be convenient and avoids the need to define large numbers of 'Sayable' instances. + >>> sez @"info" $ t'"hello" &% (t'"world", t'"!")+ "hello (world, !)"+ ['&*'] This is a helper operator whose second argument is a 'Foldable' series of 'Sayable' elements. This will fold over the series, adding the 'Sayable' instance value for each element separated by commas. + >>> sez @"info" $ t'"three:" &* [1, 2, 3::Int]+ "three: 1, 2, 3"+ ['&+*'] This is similar to the '&*' helper, but it uses the first argument as the separator between the elements of the 'Foldable' second argument (instead of the ", " default used by the '&*' helper). + >>> sez @"info" $ t'"three:" &- t'".." &+* [1, 2, 3::Int]+ "three: 1..2..3"+ ['&?'] This is a helper operator whose second argument is a @Maybe a@ (where @a@ is a @Showable@). This will emit the @Showable@ of @a@ if the argument is a 'Just' value, or nothing (an empty Text Showable) if the argument is a 'Nothing' value. + >>> sez @"info" $ t'"It's" &? Just (t'"something") &- t'"or" &? (Nothing :: Maybe Text)+ "It's something or"+ ['&<'] This is a helper operator that generates a newline between its two arguments. + >>> sez @"info" $ t'"Hello" &< t'"world"+ "Hello\nworld"+ ['&<*'] This is a helper operator that combines the '&<' and '&*' operators: it generates a newline between its two arguments and the second argument is a Foldable that will be output separated by commas. + >>> sez @"info" $ t'"three:" &<* [1, 2, 3::Int]+ "three:\n1, 2, 3"+ ['&<?'] This is a helper operator that conbines the '&<' and '&?' operators: if the second argument is a 'Just' value, it will be output preceeded by the first argument and a newline. If the second argument is 'Nothing', only the first argument is emitted (no newline either). + >>> sez @"info" $ t'"First" &<? Just (t'"something")+ "First\nsomething"+ >>> sez @"info" $ t'"Then" &<? (Nothing :: Maybe Text)+ "Then"+ ['&!'] This is a helper operator to apply a Prettyprinter transformation function (the first argument) to a 'Sayable' message (the second argument). + >>> sez @"info" $ PP.group &! t'"hi"+ "hi"+ ['&!?'] This helper operator is a combination of the '&!' operator and the '&?' operator: for a second-argument 'Just' value it will convert the value to a sayable and then apply the Prettyprinter conversion operator first-argument. + >>> sez @"info" $ PP.group &!? Just (t'"hi")+ "hi"+ ['&!*'] This helper operator is a combination of the '&!' operator and the '&*' operator: it applies the first argument (a @[PrettyPrinter.Doc ann] -> PrettyPrinter.Doc ann@ function) to the foldable collection represented by the second argument. + >>> sez @"info" $ t'"three:" &- PP.align . PP.vsep &!* [1, 2, 3::Int]+ "three: 1, \n 2, \n 3"+ ['&!$*'] This helper operator is a combination of the '&!' operator and the '&*' operator: it applies the first argument (a @PrettyPrinter.Doc ann -> PrettyPrinter.Doc ann@ function) to the *result* of a foldable@@ -169,6 +207,9 @@ '&!*' operator except that it applies the Prettyprinter conversion to the singular result of the list rather than to the list of results. + >>> sez @"info" $ t'"three:" &- PP.align &!$* [1, 2, 3::Int]+ "three: 1, 2, 3"+ ['&!+*'] This helper operator is a combination of the '&!' operator and the '&+*' operator (and is a trinary rather than a binary operator): it applies the first argument (a @[PrettyPrinter.Doc ann] ->@@ -176,6 +217,9 @@ represented by the third argument, using the second argument to specify the separators between the elements. + >>> sez @"info" $ t'"three:" &- (PP.align . PP.vsep &!+* (t'" or")) [1, 2, 3::Int]+ "three: 1 or\n 2 or\n 3"+ == Convenience/other * This module also provides an instance to convert a Sayable back@@ -204,6 +248,7 @@ by fixing the @ann@ of 'PP.Doc ann' to 'SayableAnn'. Fixes the error:+ @ • Overlapping instances for Sayable saytag (PP.Doc ann1) arising from a use of ‘&-’
sayable.cabal view
@@ -1,6 +1,6 @@ cabal-version: 2.4 name: sayable-version: 1.1.0.0+version: 1.1.1.0 synopsis: Data structures, classes and operators for constructing context-adjusted pretty output description: .@@ -17,11 +17,11 @@ license-file: LICENSE author: Kevin Quick maintainer: kquick@galois.com-copyright: Galois Inc., 2022+copyright: Galois Inc., 2023 category: Text build-type: Simple extra-doc-files: CHANGELOG.md-tested-with: GHC == 9.4.2, GHC == 9.2.4, GHC == 9.0.2, GHC == 8.10.7, GHC == 8.8.4+tested-with: GHC == 9.6.2, GHC == 9.4.5, GHC == 9.2.7, GHC == 9.0.2, GHC == 8.10.7, GHC == 8.8.4 source-repository head type: git@@ -43,7 +43,7 @@ hs-source-dirs: . default-language: Haskell2010 exposed-modules: Text.Sayable- build-depends: base >= 4.13 && < 4.18+ build-depends: base >= 4.13 && < 4.19 , exceptions , bytestring , text