diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## [0.2.0.2] - 2018-07-30 + +### Changed + +- Use `doctest-driver-gen` to run doctests + +- Dependencies bump + +- Use `markdown-unlit` to test code example in README + ## [0.2.0.1] - 2018-03-15 ### Changed @@ -36,14 +46,15 @@ ### Fixed - A bug in `createLeft` which failed to actually pad/truncate strings - (reported by Altai-man ) + () ## [0.1.2] - 2017-01-18 ### Added -- `Vector` support, `Eq` and `Ord` instances (contributed by Dylan - Simon ) +- `Vector` support, `Eq` and `Ord` instances. \ + Contributed by Dylan Simon + () ## [0.1.1] - 2016-19-12 @@ -59,6 +70,8 @@ ## [0.1.0.0] - 2014-08-10 +[0.2.0.2]: https://github.com/dzhus/static-text/compare/0.2.0.1...0.2.0.2 +[0.2.0.1]: https://github.com/dzhus/static-text/compare/0.2.0...0.2.0.1 [0.2.0]: https://github.com/dzhus/static-text/compare/0.1.3.1...0.2.0 [0.1.3.1]: https://github.com/dzhus/static-text/compare/0.1.3...0.1.3.1 [0.1.3]: https://github.com/dzhus/static-text/compare/0.1.2...0.1.3 diff --git a/README.lhs b/README.lhs new file mode 100644 --- /dev/null +++ b/README.lhs @@ -0,0 +1,60 @@ +# static-text: lists, Texts, ByteStrings and Vectors of statically known length + +[![Travis CI build status](https://travis-ci.org/dzhus/static-text.svg)](https://travis-ci.org/dzhus/static-text) +[![Hackage](https://img.shields.io/hackage/v/static-text.svg?colorB=5e5184&style=flat)](https://hackage.haskell.org/package/static-text) +[![Hackage deps](https://img.shields.io/hackage-deps/v/static-text.svg)](http://packdeps.haskellers.com/feed?needle=static-text) + +static-text provides type-level safety for basic operations on +string-like types (finite lists of elements), such as `Data.Text`, +`String` (and all lists), `Data.ByteString` and `Data.Vector`. Use it +when you need static guarantee on lengths of strings produced in your +code. + +An example application would be a network exchange protocol built of +packets with fixed-width fields: + +```haskell +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} +import Data.ByteString.Char8 (ByteString, pack) +import Data.StaticText + +mkPacket :: ByteString -> Static ByteString 32 +mkPacket inp = + -- 5-character version signature + $(st "PKT10") `append` + -- 25-character payload + payload `append` + -- 2-character payload checksum + checksum + where + payload = createLeft 0x20 inp + checksum :: Static ByteString 2 + checksum = createLeft 0x20 $ + pack $ show $ Data.StaticText.length payload `mod` 100 + +message :: Static ByteString 64 +message = mkPacket "Hello" `append` mkPacket "world" + +main :: IO () +main = print message +``` + +Please consult the [Hackage page for static-text][hackage-doc] for +documentation and examples. + +## Alternatives + +The emphasis of static-text is on type-safe padding/truncation and +type-safe string literals. Other similar libraries may suit different +use cases: + +- [vector-sized][] and [fixed-vector][]: full support for Vector API, + but not string-like types. + +[hackage-doc]: http://hackage.haskell.org/package/static-text/docs/Data-StaticText.html + +[fixed-vector]: https://hackage.haskell.org/package/fixed-vector + +[vector-sized]: https://hackage.haskell.org/package/vector-sized diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ {-# LANGUAGE DataKinds #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE TemplateHaskell #-} +import Data.ByteString.Char8 (ByteString, pack) import Data.StaticText mkPacket :: ByteString -> Static ByteString 32 @@ -31,10 +32,13 @@ payload = createLeft 0x20 inp checksum :: Static ByteString 2 checksum = createLeft 0x20 $ - pack $ show $ Data.Static.length payload `mod` 100 + pack $ show $ Data.StaticText.length payload `mod` 100 message :: Static ByteString 64 message = mkPacket "Hello" `append` mkPacket "world" + +main :: IO () +main = print message ``` Please consult the [Hackage page for static-text][hackage-doc] for diff --git a/src/Data/StaticText.hs b/src/Data/StaticText.hs --- a/src/Data/StaticText.hs +++ b/src/Data/StaticText.hs @@ -12,40 +12,6 @@ {-| -static-text provides type-level safety for basic operations on -string-like types (finite lists of elements), such as "Data.Text", -"String" (and all lists), "Data.ByteString" and "Data.Vector". Use it -when you need static guarantee on lengths of strings produced in your -code. - -An example application would be a network exchange protocol built of -packets with fixed-width fields: - -@ -{\-\# LANGUAGE DataKinds #-\} -{\-\# LANGUAGE OverloadedStrings #-\} -{\-\# LANGUAGE TemplateHaskell #-\} -@ - -> import Data.StaticText -> -> mkPacket :: ByteString -> Static 32 ByteString -> mkPacket inp = -> -- 5-character version signature -> $(st "PKT10") `append` -> -- 25-character payload -> payload `append` -> -- 2-character payload checksum -> checksum -> where -> payload = createLeft 0x20 inp -> checksum :: Static 2 ByteString -> checksum = createLeft 0x20 $ -> pack $ show $ Data.Static.length payload `mod` 100 -> -> message :: Static 64 ByteString -> message = mkPacket "Hello" `append` mkPacket "world" - static-text combinators are defined for members of 'IsStaticText' class. The package includes 'IsStaticText' instances for several common types. diff --git a/static-text.cabal b/static-text.cabal --- a/static-text.cabal +++ b/static-text.cabal @@ -1,17 +1,17 @@ -name: static-text -version: 0.2.0.1 cabal-version: >=1.10 -build-type: Simple +name: static-text +version: 0.2.0.2 license: BSD3 license-file: LICENSE maintainer: dima@dzhus.org +author: Dmitry Dzhus homepage: https://github.com/dzhus/static-text#readme bug-reports: https://github.com/dzhus/static-text/issues synopsis: Lists, Texts, ByteStrings and Vectors of statically known length description: static-text provides type-level safety for basic operations on string-like types (finite lists of elements), such as Data.Text, String (and all lists), Data.ByteString and Data.Vector. Use it when you need static guarantee on lengths of strings produced in your code. category: Data, Text, Type System -author: Dmitry Dzhus +build-type: Simple extra-source-files: CHANGELOG.md README.md @@ -33,60 +33,75 @@ Build interface for Vector library + exposed-modules: + Data.StaticText + Data.StaticText.Class + Data.StaticText.TH + hs-source-dirs: src + other-modules: + Paths_static_text + default-language: Haskell2010 + ghc-options: -Wall -Wcompat + build-depends: + base <5, + template-haskell <2.14 if flag(bytestring) + cpp-options: -DWITH_BS build-depends: bytestring <0.11 - cpp-options: -DWITH_BS if flag(text) + cpp-options: -DWITH_TEXT build-depends: text <1.3 - cpp-options: -DWITH_TEXT if flag(vector) + cpp-options: -DWITH_VECTOR build-depends: vector <0.13 - cpp-options: -DWITH_VECTOR - exposed-modules: - Data.StaticText - Data.StaticText.Class - Data.StaticText.TH + +test-suite readme + type: exitcode-stdio-1.0 + main-is: README.lhs + other-modules: + Paths_static_text + default-language: Haskell2010 + ghc-options: -Wall -Wcompat -pgmL markdown-unlit build-depends: base <5, + bytestring <0.11, + markdown-unlit <0.6, + static-text -any, template-haskell <2.14 - default-language: Haskell2010 - hs-source-dirs: src - other-modules: - Paths_static_text - ghc-options: -Wall -Wcompat -test-suite static-text-doctests +test-suite static-text-doctests type: exitcode-stdio-1.0 main-is: doctest-driver.hs - build-depends: - base <5, - doctest <0.16, - doctest-discover >=0.1.0.8 && <0.2, - template-haskell <2.14 - default-language: Haskell2010 hs-source-dirs: tests other-modules: Main Paths_static_text + default-language: Haskell2010 ghc-options: -Wall -Wcompat -threaded -test-suite static-text-example + build-depends: + base <5, + doctest <0.17, + doctest-driver-gen <0.3, + template-haskell <2.14 + +test-suite static-text-example type: exitcode-stdio-1.0 main-is: Main.hs + hs-source-dirs: tests + other-modules: + Paths_static_text + default-language: Haskell2010 + ghc-options: -Wall -Wcompat build-depends: base <5, bytestring <0.11, static-text -any, - tasty <1.1, + tasty <1.2, tasty-hunit <0.11, template-haskell <2.14 - default-language: Haskell2010 - hs-source-dirs: tests - other-modules: - Paths_static_text - ghc-options: -Wall -Wcompat diff --git a/tests/doctest-driver.hs b/tests/doctest-driver.hs --- a/tests/doctest-driver.hs +++ b/tests/doctest-driver.hs @@ -1,1 +1,1 @@ -{-# OPTIONS_GHC -F -pgmF doctest-discover #-} +{-# OPTIONS_GHC -F -pgmF doctest-driver-gen -optF src #-}