diff --git a/README.rst b/README.rst new file mode 100644 --- /dev/null +++ b/README.rst @@ -0,0 +1,70 @@ +=============================================== + Memorable Bits |hackage-badge| |travis-badge| +=============================================== + +.. |hackage-badge| image:: https://img.shields.io/hackage/v/memorable-bits.svg +.. |travis-badge| image:: https://img.shields.io/travis/luke-clifton/memorable-bits.svg + +A library for generating human-readable (and memorable) phrases from +data. What sets this library apart from most others, is that it is highly +customisable. The phrases that are generated are described at the type +level, which can ensure, at compile time, that the phrase generated has +enough bits to cover the data being converted. + +The library comes with some pre-baked themes:: + + λ> :set -XOverloadedStrings + λ> import Data.Word + λ> import Crypto.Hash + λ> import Network.IP.Addr + λ> import Data.Memorable + λ> + λ> import Data.Memorable.Theme.Fantasy + λ> renderMemorable (padHex rpgWeapons) (12345 :: Word32) + "ghostly-trident-of-zombie-tormenting-039" + λ> + λ> import Data.Memorable.Theme.Food + λ> renderMemorable (padHex desserts) $ ip4FromOctets 127 0 0 1 + "bland-strawberry-pancakes-000001" + λ> + λ> import Data.Memorable.Theme.Words + λ> let h = hash ("an example" :: ByteString) :: Digest MD5 + λ> renderMemorable (padHex eightEqualWordsFor64Bits) a + "than-high-bonk-gash-into-keen-rush-swat-7efea731142d8f84" + λ> + λ> import Data.Memorable.Theme.Science + λ> renderMemorable (padDec chemBabble) (0xdeadbeef :: Word32) + "tri-propyl-4-benzene-oxide-114415" + +But you can easily create your own and mix and match:: + + λ> :set -XDataKinds -XTypeOperators + λ> import Data.Memorable.Theme.Fantasy as Fantasy + λ> import Data.Memorable.Theme.Food as Food + λ> type MyPattern = NumberWithOffset Dec 1 3 :- Food.DessertFlavours :- Fantasy.Monster + λ> let myPattern = Proxy :: Proxy MyPattern + λ> renderMemorable (padHex myPatter) (0x4321 :: Word16) + "3-blueberry-sphinx-01" + +You can check how many bits are covered by your pattern:: + + λ> :kind! Depth MyPattern + Depth MyPattern :: Nat + = 7 + +Or using the ``getDepth`` function:: + + λ> getDepth words12 + 12 + λ> getDepth (words12 .- words12) + 24 + +If you are happy to have some non-human-readable parts in your pattern, use +the convenience functions ``padHex`` and ``padDec``:: + + λ> :set -XOverloadedStrings + λ> import Data.ByteString + λ> import Crypto.Hash + λ> let myPattern = padHex (four flw10) + λ> renderMemorable myPattern (hash ("anExample" :: ByteString) :: Digest MD5) + "bark-most-gush-tuft-1b7155ab0dce3ecb4195fc" diff --git a/memorable-bits.cabal b/memorable-bits.cabal --- a/memorable-bits.cabal +++ b/memorable-bits.cabal @@ -2,8 +2,11 @@ -- documentation, see http://haskell.org/cabal/users-guide/ name: memorable-bits -version: 0.1.0.0 +version: 0.1.0.1 synopsis: Generate human memorable strings from binary data. +description: I library for creating human readable strings from + various types of data. Also a DSL for comming up + with patterns. license: BSD2 license-file: LICENSE author: Luke Clifton @@ -11,7 +14,12 @@ category: Data build-type: Simple cabal-version: >=1.10 +extra-source-files: README.rst +source-repository head + type: git + location: https://github.com/luke-clifton/memorable-bits + flag data-dword-inst description: Include data-dword and provide instances for its types. default: True @@ -63,7 +71,8 @@ test-suite test-memorable-bits type: exitcode-stdio-1.0 main-is: test/Main.hs - build-depends: base >=4.8 && <4.10 + default-language: Haskell2010 + build-depends: base >=4.8 && <5 , memorable-bits , tasty , tasty-hunit @@ -75,7 +84,8 @@ benchmark bench-memorable-bits type: exitcode-stdio-1.0 main-is: bench/Main.hs - build-depends: base >=4.8 && <4.10 + default-language: Haskell2010 + build-depends: base >=4.8 && <5 , criterion , memorable-bits , random @@ -84,7 +94,7 @@ executable membits main-is: app/Membits.hs default-language: Haskell2010 - build-depends: base >=4.8 && <4.10 + build-depends: base >=4.8 && <5 , memorable-bits , bytestring , cryptonite diff --git a/src/Data/Memorable/Internal.hs b/src/Data/Memorable/Internal.hs --- a/src/Data/Memorable/Internal.hs +++ b/src/Data/Memorable/Internal.hs @@ -377,10 +377,6 @@ -- >>> import Data.Memorable.Theme.Fantasy -- >>> renderMemorable (padHex rpgWeapons) (0xdeadbeef01020304 :: Word64) -- "sacred-club-of-ghoul-charming-eef01020304" --- --- The depth to pad to is the first type-level argument. If you have --- `TypeApplications` set, you can use it like `padHex @256` to be --- explicit. padHex :: forall n a. Proxy a -> Proxy (PadTo Hex n a) padHex _ = Proxy @@ -406,8 +402,7 @@ hex32 = Proxy -- | A single hex number consuming `n` bits, which it will try and figure --- out from context (with leading 0's). Using `TypeApplications` allows you --- to specify the size directly, `hex @32 == hex32`. +-- out from context (with leading 0's). hex :: Proxy (Number Hex n) hex = Proxy @@ -428,8 +423,7 @@ dec32 = Proxy -- | A single decimal number consuming `n` bits, which it will try and figure --- out from context (no leading 0's). Using `TypeApplications` allows you --- to specify the size directly, `dec @32 == hex32`. +-- out from context (no leading 0's) dec :: Proxy (Number Dec n) dec = Proxy @@ -795,8 +789,8 @@ renderMem = mapM_ putUnaligned . B.unpack . convert; \ parserMem = do { \ let {b = (BITS) `div` 8;}; \ - Just md <- (digestFromByteString . B.pack) <$> replicateM b (getBitsFrom 7 0); \ - return md;}} + fromJust <$> (digestFromByteString . B.pack) <$> replicateM b (getBitsFrom 7 0); \ + }} DIGEST_INST(Whirlpool,512) DIGEST_INST(Blake2s_224,224)