-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Utilities for creating inputs for dzen.
--
-- This library has everything you need to create your dzen's
-- bar input strings using powerful combinators in a type-safe way.
--
-- It can be used to create standalone "scripts" with runhaskell
-- or it can be used inside xmonad's main function.
--
-- To see what can be done, please read the documentation of the toplevel
-- module System.Dzen.
@package dzen-utils
@version 0.1
-- | This module contains most of the basic functions of this package. The
-- data types presented here are:
--
--
-- - DString strings that support constant time
-- concatenation, dzen attributes and some instropection.
-- - Printer encapsulates functions take take some input
-- and produce a DString as a result, allowing them to be
-- combined and applied.
--
module System.Dzen.Base
-- | A DString is used for constant string output, see
-- str. The D on DString stands for
-- dzen, as these strings may change depending on the state (and
-- that's why you shouldn't rely on Show, as it just uses an empty
-- state)
data DString
-- | Converts a String into a DString, escaping
-- characters if needed. This function is used in fromString from
-- IsString, so DStrings created by
-- OverloadedStrings extension will be escaped.
str :: String -> DString
-- | Converts a String into a DString without escaping
-- anything. You really don't need to use this, trust me!
rawStr :: String -> DString
-- | Converts a DString back into a String. Note that
-- (toString . rawStr) is not id, otherwise
-- toString would not work in some cases. Probably you don't
-- need to use this, unless you want something like a static bar and
-- nothing else.
toString :: DString -> String
-- | Tries to get the number of characters of the DString. May
-- return Nothing when there are graphical objects. Probably you
-- don't need to use this function.
size :: DString -> Maybe Int
-- | parens open close d is equivalent to mconcat [open, d,
-- close].
parens :: DString -> DString -> DString -> DString
-- | A printer is used when the output depends on an input, so a
-- Printer a generates a DString based on some input of
-- type a (and possibly updates some internal state).
data Printer a
-- | A Printer is a cofunctor.
comap :: (a -> b) -> (Printer b -> Printer a)
-- | Constructs a Printer that depends only on the input.
simple :: (a -> DString) -> Printer a
-- | Like simple, but using Strings.
simple' :: (a -> String) -> Printer a
-- | Constructs a Printer that depends on the current and on the
-- previous inputs.
inputPrinter :: (b -> a -> (DString, b)) -> b -> Printer a
-- | Like inputPrinter, but with Strings.
inputPrinter' :: (b -> a -> (String, b)) -> b -> Printer a
-- | Works like str, but uses the input instead of being constant.
-- In fact, it is defined as simple str.
cstr :: Printer String
-- | Same as simple' show.
cshow :: Show a => Printer a
-- | Class used for combining DStrings and Printers
-- exactly like mappend.
--
-- Note that we don't lift DString to Printer () and
-- use a plain function of type Printer a -> Printer b ->
-- Printer (a,b) because that would create types such as Printer
-- ((),(a,((),(b,())))) instead of Printer (a,b).
class Combine a b where { type family Combined a b :: *; }
(+++) :: Combine a b => a -> b -> Combined a b
-- | Sometimes you want two printers having the same input, but p1 +++
-- p2 :: Printer (a,a) is not convenient. So p1 +=+ p2 ::
-- Printer a works like +++ but gives the same input for both
-- printers.
(+=+) :: Printer a -> Printer a -> Printer a
-- | Works like +=+ but the second printer's input is a tuple.
(+-+) :: Printer a -> Printer (a, b) -> Printer (a, b)
-- | While you may say p1 +=+ (ds1 +++ ds2 +++ p2), where
-- p1,p2 :: Printer a and ds1,ds2 :: DString, you can't
-- say p1 +=+ (po +++ p2) nor (p1 +++ po) +=+ p2 where
-- po :: Printer b.
--
-- This operator works like +++ but shifts the tuple, giving you
-- Printer (b,a) instead of Printer (a,b). In the
-- example above you may write p1 +>+ po +/+ p2.
(+/+) :: Printer a -> Printer b -> Printer (b, a)
-- | This operator works like +/+ but the second printer's input is
-- a tuple. Use it like
--
--
-- pA1 +-+ pB +<+ pC +<+ pD +/+ pA2 :: Printer (a,(b,(c,d)))
--
--
-- where both pA1 and pA2 are of type Printer
-- a.
(+<+) :: Printer a -> Printer (b, c) -> Printer (b, (a, c))
-- | This is a general combine function for Printers. The outputs
-- are always concatenated, but the inputs are given by the supplied
-- function.
--
-- The combining operators above are defined as:
--
--
-- (+++) = combine id -- restricted to Printers
-- (+=+) = combine (\x -> ( x, x))
-- (+-+) = combine (\x -> (fst x, x))
-- (+/+) = combine (\(a,b) -> (b,a))
-- (+<+) = combine (\(b,(a,c)) -> (a,(b,c)))
--
--
-- Note also the resamblence with comap. In fact, if we have
-- (+++) and comap we may define
--
--
-- combine f a b = comap f (a +++ b) -- pointwise
-- combine = flip (.) (+++) . (.) . comap -- pointfree
--
--
-- and with combine and simple we may define
--
--
-- comap f = combine (\i -> ((), f i)) (simple $ const mempty) -- pointwise
-- comap = flip combine (simple $ const mempty) . ((,) () .) -- pointfree
--
combine :: (c -> (a, b)) -> Printer a -> Printer b -> Printer c
-- | Apply a printer to an appropriate input, returning the output string
-- and the new printer.
apply :: Printer a -> a -> (String, Printer a)
-- | Apply a printer many times in sequence. Most of the time you would
-- ignore the final printer using applyMany_, but it can be used
-- to continue applying.
applyMany :: Printer a -> [a] -> ([String], Printer a)
-- | Like applyMany but ignoring the final printer.
applyMany_ :: Printer a -> [a] -> [String]
-- | Apply a printer forever inside a monad. The first action is used as a
-- supply of inputs while the second action receives the output before
-- the next input is requested.
--
-- Note that your supply may be anything. For example, inside IO
-- you may use threadDelay:
--
--
-- applyForever (threadDelay 100000 >> getInfo) (hPutStrLn dzenHandle)
--
applyForever :: Monad m => Printer a -> m a -> (String -> m ()) -> m ()
-- | Transform is a specialization of Functor for
-- DStrings. This class is used for functions that may receive
-- DString or Printer a as an argument because they
-- operate only on their outputs and internal states (and not on the
-- inputs).
--
-- So, whenever you see a function of type
--
--
-- func :: Transform a => Blah -> Bleh -> a -> a
--
--
-- it means that func can be used in two ways:
--
--
-- func :: Blah -> Bleh -> DString -> DString
-- func :: Blah -> Bleh -> Printer a -> Printer a -- Printer of any input!
--
--
-- Try to have this in mind when reading the types.
--
-- Note: There is also a non-exported transformSt for
-- transforming the state in this class, otherwise it would be
-- meaningless to use a class only for transform (it would be
-- better to make liftT :: (DString -> DString) -> (Printer a
-- -> Printer a)).
class Transform a
transform :: Transform a => (DString -> DString) -> (a -> a)
instance Combine (Printer a) (Printer b)
instance Combine (Printer a) DString
instance Combine DString (Printer a)
instance Combine DString DString
-- | Support for colours. This module is entirely based on the
-- colour package, so we strongly recommend that you at least
--
--
-- import qualified Data.Colour.Names as C
--
--
-- which will import various aliases for creating Colours.
--
-- Note changing the colours using the functions below do not hinder the
-- use of automatic padding.
module System.Dzen.Colour
-- | Our colours.
type DColour = Colour Double
-- | Set the foreground colour. Note that the foreground colour is changed
-- only inside the transformed DString or Printer,
-- unlike using "^fg" which may affect subsequent strings.
--
-- So you may write fg black (fg lime (str "lime")
-- +++ str "black") and it works like you expect it to.
fg :: Transform a => DColour -> (a -> a)
-- | Like fg, but set the background colour.
bg :: Transform a => DColour -> (a -> a)
-- | Set the foreground colour to be the default one, which is specified as
-- a parameter to dzen (outside the control of the printers).
defFg :: Transform a => a -> a
-- | Like defFg, but for the background colour.
defBg :: Transform a => a -> a
-- | Set the foreground to be a specified one (Just c) or the
-- dzen's default (Nothing). Both fg and defFg are
-- specializations of this function.
changeFg :: Transform a => Maybe DColour -> (a -> a)
-- | Like changeFg, but for the background colour.
changeBg :: Transform a => Maybe DColour -> (a -> a)
-- | Support for the graphical abilities of dzen. Unfortunately
-- this is not the strongest are of dzen, so there isn't a lot
-- of functionality here, but there are "bindings" for every function
-- they provide.
--
-- You can draw:
--
--
-- - icons With icon (see dzen documentation
-- about formats and paths).
-- - rectanges With rect and rectO.
-- - circles With circ and circO.
--
--
-- Although it may seem that you can draw anything with the rectangle
-- primitive (i.e. in the worst case just use 1x1 rectangles to simulate
-- pixels), dzen does not allow you to control the y
-- part of the shapes, only the x part (using pos and
-- absPos): they are always vertically centered.
module System.Dzen.Graphics
type Width = Int
type Height = Int
type Radius = Int
-- | Draws an icon.
icon :: FilePath -> DString
-- | rect w h draws and fills a rectangle of width w and
-- height h. The rectangle is vertically centered (that is, if
-- h == 1 then it is a centered line, something like
-- ----).
rect :: Width -> Height -> DString
-- | Like rect, but only draws and does not fills (i.e. draws an
-- outline).
rectO :: Width -> Height -> DString
-- | circ r draws and fils a circle of radius r, also
-- vertically centered.
circ :: Radius -> DString
-- | Like circ, but does not fills.
circO :: Radius -> DString
-- | pos p moves the position of the next input p pixels
-- to the right. Note that p may be negative, effectively moving
-- to the right.
pos :: Int -> DString
-- | absPos p moves the position of the next input to be exactly
-- p pixels to the right of the initial position. This should be
-- used with care.
absPos :: Int -> DString
-- | If True, the transformed DString or Printer
-- will ignore the background colour (i.e. it will draw over what was
-- already drawn). The default is False, the background colour
-- is used.
ignoreBg :: Transform a => Bool -> (a -> a)
-- | This is a handy module with functions for manual and automatic
-- padding. To pad means to force the length of a string to be of a
-- minimum size by adding padding characters on either or both
-- sides of the string (usually spaces). For example, padding the string
-- "123" to have length of 10 characters would give us the
-- string
--
--
-- " 123" -- if padding on the left
-- "123 " -- if padding on the right
-- " 123 " -- if padding on both sides
--
--
-- We provide two kinds of padding here:
--
--
-- - manual padding This is the kind of padding you usually see
-- in other (non-dzen) libraries. You give them the type of
-- padding and the minimum length that you want and they will give you
-- back another string. The pad* functions do this with both
-- plain DStrings and with the output of Printers.
-- - automatic padding This is the same as a "never shrink"
-- padding. An automatic padder adjusts its minimum length to be at least
-- the greatest length it has seen so far, which means that an
-- auto-padded Printer will never shrink its size. This is very
-- useful if you don't want everything swinging on your bar everytime the
-- bar is updated.
--
module System.Dzen.Padding
-- | Pads the given DString or Printer output with spaces
-- to be at least n chars in length
padL :: Transform a => Int -> (a -> a)
-- | Same as padL, but insert spaces on the right of the string.
padR :: Transform a => Int -> (a -> a)
-- | Same as padL, but insert spaces on both sides, trying to keep
-- the original contents in the middle.
padC :: Transform a => Int -> (a -> a)
-- | Generic pad function, padding with any character and in any place.
pad :: Transform a => Char -> PadWhere -> Int -> (a -> a)
-- | Where to add the padding characters.
data PadWhere
PadLeft :: PadWhere
PadRight :: PadWhere
PadCenter :: PadWhere
-- | Automatic padding for padL.
autoPadL :: Int -> (Printer a -> Printer a)
-- | Automatic padding for padR.
autoPadR :: Int -> (Printer a -> Printer a)
-- | Automatic padding for padC.
autoPadC :: Int -> (Printer a -> Printer a)
-- | Generic automatic padding function, analog to pad.
autoPad :: Char -> PadWhere -> Int -> (Printer a -> Printer a)
-- | Drawing of progress bars (sometimes called progress gauges), like
-- dbar and gdbar utilities work but a little more
-- powerful (in fact, we can simulate both utilities, see dbar and
-- gdbar).
--
-- An example of text progress bar that can be drawn:
--
--
-- 96% [==================> ]
--
module System.Dzen.Bars
-- | Mimics the dbar utility. Uses the dbar_style.
dbar :: (Num a, Enum a, Ord a) => Bool -> Width -> (a, a) -> a -> DString
-- | Mimics the dbar utility while getting the input dinamically.
cdbar :: (Num a, Enum a, Ord a) => Bool -> Width -> (a, a) -> Printer a
-- | Mimics the gdbar utility. Uses the gdbar_style.
gdbar :: (Num a, Enum a, Ord a) => Bool -> (Width, Height) -> Maybe DColour -> Maybe DColour -> Bool -> (a, a) -> a -> DString
-- | Mimics the gdbar utility while getting the input dinamically.
cgdbar :: (Num a, Enum a, Ord a) => Bool -> (Width, Height) -> Maybe DColour -> Maybe DColour -> Bool -> (a, a) -> Printer a
-- | Draws a bar and optionally some text describing some quantity in
-- relation to some range. For example,
--
--
-- bar (AtLeft Percentage) (Text "[" "=" (Just ">") " " "]" 20) (-10,10) i
--
--
-- produces the bars
--
--
-- " 2% [ ]" where i = -9.6
-- " 2% [> ]" where i = -9.5
-- " 50% [=========> ]" where i = 0
-- " 96% [==================> ]" where i = 9.4
-- " 99% [===================>]" where i = 9.99
-- "100% [====================]" where i = 10
--
--
-- Note that the text is always padded to four characters. If the first
-- bar above had AtRight Percentage the result would be
--
--
-- "[ ] 2% "
--
--
-- so the padding always inserts the spaces on the outside.
bar :: (Num a, Enum a, Ord a) => BarText -> BarType -> (a, a) -> a -> DString
-- | bar wrapped with simple so that the value is taken from
-- an input.
cbar :: (Num a, Enum a, Ord a) => BarText -> BarType -> (a, a) -> Printer a
-- | The type of the bar to be drawn.
data BarType
-- | Draws a text bar. Note, however, that the DStrings below can
-- be anything, not just text. For example, they may have colours
-- (fg), shapes (rects and circs) or icons,
-- you may even simulate both Filled and Hollow using just
-- Text (although performance would be suboptimal).
Text :: !DString -> !DString -> !Maybe DString -> !DString -> !DString -> !Width -> BarType
-- | Text written at the start.
txtOpen :: BarType -> !DString
-- | Text written for each filled square.
txtFilled :: BarType -> !DString
-- | Text written for the last filled square. If Nothing, the same
-- as the filled square is used, but more fairly than if you used the
-- same value for filled and middle chars.
txtMiddle :: BarType -> !Maybe DString
-- | Text written for the unfilled squares.
txtBackground :: BarType -> !DString
-- | Text written at the end.
txtClose :: BarType -> !DString
-- | How many squares there should be (i.e. does not count the open and
-- close parts).
txtWidth :: BarType -> !Width
-- | Draws a filled graphical bar, like gdbar would.
Filled :: !Maybe DColour -> !Maybe DColour -> !(Width, Height) -> BarType
-- | Colour used for filled squares, or Nothing to use the default
-- foreground colour.
grpFilled :: BarType -> !Maybe DColour
-- | Colour used for the unfilled squares, or Nothing to use the
-- default background colour.
grpBackground :: BarType -> !Maybe DColour
-- | Size of the whole bar.
grpSize :: BarType -> !(Width, Height)
-- | Draws a filled graphical bar with a surrounding border.
Hollow :: !Maybe DColour -> !Maybe DColour -> !Maybe DColour -> !(Width, Height) -> BarType
-- | Colour used for filled squares, or Nothing to use the default
-- foreground colour.
grpFilled :: BarType -> !Maybe DColour
-- | Colour used for the unfilled squares, or Nothing to use the
-- default background colour.
grpBackground :: BarType -> !Maybe DColour
-- | Colour of the border, or Nothing to use the default
-- foreground colour.
grpBorder :: BarType -> !Maybe DColour
-- | Size of the whole bar.
grpSize :: BarType -> !(Width, Height)
-- | The type of text to be written.
data BarTextType
Percentage :: BarTextType
Absolute :: BarTextType
-- | How to draw the bar text. AtLeft and AtRight are
-- used to specify if the text is at the left or the right of the bar,
-- and None means that no text will be written.
data BarText
AtLeft :: !BarTextType -> BarText
AtRight :: !BarTextType -> BarText
None :: BarText
-- | The style produced by the dbar utility.
dbar_style :: Char -> Width -> BarType
-- | The style of gdbar (or something very close).
gdbar_style :: (Width, Height) -> Maybe DColour -> Maybe DColour -> Bool -> BarType
instance Eq BarText
instance Ord BarText
instance Show BarText
instance Eq BarTextType
instance Ord BarTextType
instance Show BarTextType
instance Enum BarTextType
instance Show BarType
-- | Functions for creating supplies and running dzen.
module System.Dzen.Process
-- | Pipes a Printer to a fresh instance of dzen. It runs
-- the following commands:
--
--
-- - Start dzen with the supplied executable and
-- arguments.
-- - Call the supply to get an input.
-- - Apply the input to the printer.
-- - Write the printer's output to dzen's standard input.
-- - Sleeps for the specified delay using threadDelay.
-- - Go back to step 2.
--
--
-- You may want to use this function inside a forkIO if, for
-- example, you're inside xmonad.
runDzen :: FilePath -> [String] -> Int -> Printer a -> IO a -> IO ()
-- | This is the same as liftM2 (,), but with as a convenient
-- operator with right infixity (the same as +++). For example,
-- suppose you have printers
--
--
-- prA :: Printer a
-- prB :: Printer b
-- prC :: Printer c
--
--
-- and supply functions
--
--
-- getA :: m a
-- getB :: m b
-- getC :: m c
--
--
-- for some monad m. The final printer
--
--
-- prFinal = prA +++ prB +++ prC
--
--
-- will be of type Printer (a,(b,c)), so you may use as its
-- supply function
--
--
-- getFinal = getA ## getB ## getC
--
--
-- which is of type m (a,(b,c)).
(##) :: Monad m => m a -> m b -> m (a, b)
-- | Runs a dzen instance and returns its stdin pipe.
-- Both stdout and stderr of the new process will be
-- the same as this process'. The pipe returned is already line buffered.
--
-- The first string is interpreted as a shell command to start
-- dzen. Some examples of usage:
--
--
-- createDzen (RawCommand "dzen2" ["-p"])
-- createDzen (ShellCommand "dzen2 -l 8 -bg #331100")
--
createDzen :: CmdSpec -> IO Handle
-- | Like createDzen, but never uses a shell (which is good).
createDzen' :: FilePath -> [String] -> IO Handle
-- | Hello!
--
-- This is dzen-utils' main module. It re-exports every other
-- module from this library, so you may just say
--
--
-- import System.Dzen
--
--
-- and you'll have everything in hand. To learn more about this library,
-- please see the documentation of each module exported here. To get you
-- started, there are some simple examples below. :)
module System.Dzen