diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +# Text.Encoding.Z + +## The Z-encoding + +`zEncodeString` is a name-encoding and decoding function. It encodes any ascii +string into a string that is acceptable as a C name. This is code was originally +part of GHC and used right before emitting a symbol name into the compiled C or +asm code. This library was created as this encoding is useful when working with +GHC compiled code or generally when C-compatible name mangling is desired. + +`zDecodeString` is the inverse operation. diff --git a/Tests.hs b/Tests.hs new file mode 100644 --- /dev/null +++ b/Tests.hs @@ -0,0 +1,17 @@ +module Main where + +import Hedgehog +import qualified Hedgehog.Gen as Gen +import qualified Hedgehog.Range as Range +import Test.Hspec +import Test.Hspec.Hedgehog + +import Text.Encoding.Z + +main :: IO () +main = hspec $ do + describe "Round trip" $ do + it "self-inverse of arbitrary ascii" $ hedgehog $ do + xs <- forAll $ Gen.string (Range.linear 0 100) Gen.ascii + zDecodeString (zEncodeString xs) === xs + diff --git a/Text/Encoding/Z.hs b/Text/Encoding/Z.hs --- a/Text/Encoding/Z.hs +++ b/Text/Encoding/Z.hs @@ -1,45 +1,13 @@ +{-# LANGUAGE Safe #-} {- | The Z-encoding This is the main name-encoding and decoding function. It encodes any -string into a string that is acceptable as a C name. This is done -right before we emit a symbol name into the compiled C or asm code. -Z-encoding of strings is cached in the FastString interface, so we -never encode the same string more than once. - -The basic encoding scheme is this. - - * Tuples (,,,) are coded as Z3T - - * Alphabetic characters (upper and lower) and digits - all translate to themselves; - except 'Z', which translates to 'ZZ' - and 'z', which translates to 'zz' - We need both so that we can preserve the variable/tycon distinction - - * Most other printable characters translate to 'zx' or 'Zx' for some - alphabetic character x - - * The others translate as 'znnnU' where 'nnn' is the decimal number - of the character +string into a string that is acceptable as a C name. This is code was +originally part of GHC and used right before emitting a symbol name +into the compiled C or asm code. This library was created as this +encoding is useful when working with GHC compiled code or generally +when C-compatible name mangling is desired. -@ - Before After - -------------------------- - Trak Trak - foo_wib foozuwib - \> zg - \>1 zg1 - foo\# foozh - foo\#\# foozhzh - foo\#\#1 foozhzh1 - fooZ fooZZ - :+ ZCzp - () Z0T 0-tuple - (,,,,) Z5T 5-tuple - (\# \#) Z1H unboxed 1-tuple (note the space) - (\#,,,,\#) Z5H unboxed 5-tuple - (NB: There is no Z1T nor Z0H.) -@ -} module Text.Encoding.Z ( zEncodeString, @@ -51,10 +19,43 @@ import Data.Char import Numeric -type UserString = String -- As the user typed it -type EncodedString = String -- Encoded form - +type UserString = String -- ^ As the user typed it +type EncodedString = String -- ^ Encoded form +-- | The basic encoding scheme is this: +-- +-- * Tuples (,,,) are coded as Z3T +-- +-- * Alphabetic characters (upper and lower) and digits +-- all translate to themselves; +-- except 'Z', which translates to 'ZZ' +-- and 'z', which translates to 'zz' +-- We need both so that we can preserve the variable/tycon distinction +-- +-- * Most other printable characters translate to 'zx' or 'Zx' for some +-- alphabetic character x +-- +-- * The others translate as 'znnnU' where 'nnn' is the decimal number +-- of the character +-- +-- @ +-- Before After +-- -------------------------- +-- Trak Trak +-- foo_wib foozuwib +-- \> zg +-- \>1 zg1 +-- foo\# foozh +-- foo\#\# foozhzh +-- foo\#\#1 foozhzh1 +-- fooZ fooZZ +-- :+ ZCzp +-- () Z0T 0-tuple +-- (,,,,) Z5T 5-tuple +-- (\# \#) Z1H unboxed 1-tuple (note the space) +-- (\#,,,,\#) Z5H unboxed 5-tuple +-- (NB: There is no Z1T nor Z0H.) +-- @ zEncodeString :: UserString -> EncodedString zEncodeString cs = case maybe_tuple cs of Just n -> n -- Tuples go to Z2T etc @@ -119,6 +120,7 @@ -- eg. strings of unicode characters come out as 'z1234Uz5678U', we -- could remove the 'U' in the middle (the 'z' works as a separator). +-- | The inverse of 'zEncodeString' zDecodeString :: EncodedString -> UserString zDecodeString [] = [] zDecodeString ('Z' : d : rest) diff --git a/zenc.cabal b/zenc.cabal --- a/zenc.cabal +++ b/zenc.cabal @@ -1,5 +1,5 @@ Name: zenc -Version: 0.1.1 +Version: 0.1.2 Synopsis: GHC style name Z-encoding and Z-decoding Description: Implements GHC's name mangling. This code was taken directly from the GHC source. @@ -10,24 +10,37 @@ Copyright: GHC HQ Category: Text Build-type: Simple -Cabal-version: >=1.6 +Cabal-version: >=1.10 +extra-source-files: README.md Library -- Modules exported by the library. Exposed-modules: Text.Encoding.Z - + -- Packages needed in order to build this package. Build-depends: base >= 3 && <= 5 GHC-options: -O2 - + default-language: Haskell2010 + + -- Modules not exported by this package. - -- Other-modules: - + -- Other-modules: + -- Extra tools (e.g. alex, hsc2hs, ...) needed to build the source. - -- Build-tools: - + -- Build-tools: + +test-suite tests + type: exitcode-stdio-1.0 + main-is: Tests.hs + other-modules: Text.Encoding.Z + build-depends: base >= 3 && <= 5 + build-depends: hedgehog == 1.0.* + build-depends: hspec == 2.8.* + build-depends: hspec-hedgehog == 0.0.* + default-language: Haskell2010 + source-repository this type: git - location: git://github.com/dagit/zenc.git - tag: 0.1.0 + location: https://github.com/dagit/zenc.git + tag: 0.1.2