diff --git a/Data/Text/Format/Heavy/Instances.hs b/Data/Text/Format/Heavy/Instances.hs --- a/Data/Text/Format/Heavy/Instances.hs +++ b/Data/Text/Format/Heavy/Instances.hs @@ -2,7 +2,7 @@ -- | This module contains Formatable and VarContainer instances for most used types. module Data.Text.Format.Heavy.Instances (-- * Utility data types - Single (..), Shown (..), + Single (..), Several (..), Shown (..), -- * Generic formatters genericIntFormat, genericFloatFormat ) where @@ -29,7 +29,8 @@ instance IsVarFormat GenericFormat where parseVarFormat text = either (Left . show) Right $ parseGenericFormat text - +instance IsVarFormat BoolFormat where + parseVarFormat text = either (Left . show) Right $ parseBoolFormat text ---------------------- Generic formatters ------------------------------------------- @@ -51,6 +52,10 @@ ------------------------ Formatable instances ------------------------------------------- +-- | Unit type is formatted as empty string +instance Formatable () where + formatVar _ _ = Right mempty + instance Formatable Int where formatVar fmt x = genericIntFormat fmt x @@ -103,6 +108,15 @@ instance Formatable a => Formatable (Single a) where formatVar fmt (Single x) = formatVar fmt x +-- | Container for several parameters of the same type. +-- Example usage: +-- +-- @ +-- format "{} + {} = {}" $ Several [2, 3, 5] +-- @ +data Several a = Several {getSeveral :: [a]} + deriving (Eq, Show) + -- | Values packed in Shown will be formatted using their Show instance. -- -- For example, @@ -121,7 +135,16 @@ instance Formatable a => Formatable (Maybe a) where formatVar Nothing Nothing = Right mempty - formatVar fmt (Just x) = formatVar fmt x + formatVar Nothing (Just x) = formatVar Nothing x + formatVar (Just fmtStr) m = + case parseMaybeFormat fmtStr of + Nothing -> case m of + Nothing -> Right mempty + Just x -> formatVar (Just fmtStr) x + Just (xFmtStr, nothingStr) -> + case m of + Nothing -> Right $ B.fromLazyText nothingStr + Just x -> formatVar (Just xFmtStr) x instance (Formatable a, Formatable b) => Formatable (Either a b) where formatVar fmt (Left x) = formatVar fmt x @@ -136,6 +159,12 @@ instance VarContainer () where lookupVar _ _ = Nothing +-- | Maybe container contains one variable (named 0); Nothing contains an empty string. +instance Formatable a => VarContainer (Maybe a) where + lookupVar "0" (Just x) = Just $ Variable x + lookupVar "0" Nothing = Just $ Variable () + lookupVar _ _ = Nothing + instance (Formatable a, Formatable b) => VarContainer (a, b) where lookupVar "0" (a,_) = Just $ Variable a lookupVar "1" (_,b) = Just $ Variable b @@ -184,8 +213,8 @@ lookupVar "6" (_,_,_,_,_,_,g) = Just $ Variable g lookupVar _ _ = Nothing -instance Formatable a => VarContainer [a] where - lookupVar name lst = +instance Formatable a => VarContainer (Several a) where + lookupVar name (Several lst) = if not $ TL.all isDigit name then Nothing else let n = read (TL.unpack name) diff --git a/Data/Text/Format/Heavy/Parse.hs b/Data/Text/Format/Heavy/Parse.hs --- a/Data/Text/Format/Heavy/Parse.hs +++ b/Data/Text/Format/Heavy/Parse.hs @@ -15,6 +15,7 @@ (-- * Parse functions parseFormat, parseFormat', parseGenericFormat, parseBoolFormat, + parseMaybeFormat, -- * Parsec functions pFormat, pGenericFormat, pBoolFormat, -- * Utility types @@ -212,4 +213,24 @@ -- parseBoolFormat :: TL.Text -> Either ParseError BoolFormat parseBoolFormat text = runParser pBoolFormat () "" text + +-- | Try to parse format for @Maybe x@ type. +-- The syntax is: +-- +-- @ +-- someformat|nothing +-- @ +-- +-- where @someformat@ is format for the @x@ type, and @nothing@ is the string +-- to be substituted for @Nothing@ value. +-- +-- Returns Nothing, if format does not contain @|@. Otherwise, returns +-- @Just (someformat, nothing)@. +-- +parseMaybeFormat :: TL.Text -> Maybe (TL.Text, TL.Text) +parseMaybeFormat text = + let (xFmtStr, nothingStr) = TL.breakOnEnd "|" text + in if TL.null xFmtStr + then Nothing + else Just (TL.init xFmtStr, nothingStr) diff --git a/Data/Text/Format/Heavy/Types.hs b/Data/Text/Format/Heavy/Types.hs --- a/Data/Text/Format/Heavy/Types.hs +++ b/Data/Text/Format/Heavy/Types.hs @@ -3,6 +3,7 @@ module Data.Text.Format.Heavy.Types where import Data.Default +import Data.Monoid import qualified Data.Text as T import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as B @@ -25,6 +26,10 @@ -- | String format data Format = Format [FormatItem] deriving (Show) + +instance Monoid Format where + mempty = Format [] + mappend (Format xs) (Format ys) = Format (xs ++ ys) -- | Can be used for different data types describing formats of specific types. class (Default f, Show f) => IsVarFormat f where diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +text-format-heavy README +======================== + +This is Haskell string formatting library, which prefers functionality and +extendability over light weight and (probably, in some cases) performance. +This library is more or less analog of Python's string.format function, and +has similar syntax. It also exposes all required interfaces to extend and +customize it. + +Most notable features are: + + * Automatically numbered variable placeholders (`{}`); + * Positional variable placeholders (`{1}`); + * Named variable placeholders (`{name}`); + * Placeholders can be used in any order; one variable can be used several + times or not used at all. + * Specific format can be used for each variable substitution (`{0:+8.4}`). + +Formatting strings are present by `Format` type. Values of this type can be +parsed from lazy Text, or can be entered as string literals, since `Format` +implements `IsString`. + +The `format` function takes a `Format` specification and a container with +variables. Container types are generalized by `VarContainer` type class. +Standard container implementations include: + + * `Single` type for case when you need to pass only one variable. + * Tuples and lists. These contain numbered variables, i.e. `{0}`, `{1}`, etc. + * `[(Text, a)]` and `Map Text a`. These contain named variables, i.e. + `{name}`. + +One can implement custom variable containers, for example some record types. + +Types of variables that can be used for subsitiution are generalized by +`Formatable` type class. Each implementation defines default value formatting +rules, and a syntax of variable format specification. For example, for +integers, floats and strings, python-like syntax is used. Standard set of +variable types includes: + + * Integers (`Int` and `Integer`, others can be easily added); + * Floats (`Float` and `Double`); + * Strings (`String`, lazy and strict `Text`); + * Booleans; + * Time/date values from Data.Time. + * Any instance of `Show` type class can be used by packing it into `Shown` + constructor. + +One can implement custom variable types. + +For examples, please refer to [GitHub +wiki](https://github.com/portnov/text-format-heavy/wiki) and `examples/` +directory in this repo. There are also some examples in haddock documentation. + +License: BSD3. + diff --git a/examples/test.hs b/examples/test.hs --- a/examples/test.hs +++ b/examples/test.hs @@ -14,5 +14,9 @@ TLIO.putStrLn $ format template xs time <- getZonedTime TLIO.putStrLn $ format "Hello, {}! It is {:%H:%M:%S} now." $ ("Ilya" :: String, time) + let mbX = Nothing :: Maybe Float + mbY = Just 7.37491 :: Maybe Float + mbZ = Nothing :: Maybe Float + TLIO.putStrLn $ format "Maybe X: {:+8.4|}, Maybe Y: {:+8.4|}, Maybe Z: {:+8.4}." (mbX, mbY, mbZ) diff --git a/text-format-heavy.cabal b/text-format-heavy.cabal --- a/text-format-heavy.cabal +++ b/text-format-heavy.cabal @@ -1,5 +1,5 @@ name: text-format-heavy -version: 0.1.0.0 +version: 0.1.1.0 synopsis: Full-weight string formatting library, analog of Python's string.format description: This package contains full-featured string formatting function, similar to Python's string.format. Features include: @@ -29,6 +29,7 @@ category: Text build-type: Simple extra-source-files: ChangeLog.md, + README.md, examples/test.hs, examples/Benchmarks.hs cabal-version: >=1.10