An ordered sequence of elements where each element consists of an annotation and a label.

This type is a thin newtype wrapper over [(a,b)], and usefully different from that bare type in nuance only: in Parts, the first tuple component (the annotation) is assumed to be meaningful only together with the second tuple component (the label). Therefore, Parts have no utility functions or instances that allow combining over only the annotations of a Parts - hence the lack of (Bi)Foldable and (Bi)Traversable. Parts instead offers up to (Bi)Functor, Semigroup and Monoid; all of which retains the structural pairing of annotations and labels. For combining over the (ann,b) pairs (elements) of a Parts, foldParts and interpret are provided instead.

Further, the justification of a Parts type could be claimed to rely solely on its specialization to the Silenceable type.

Embed a value annotated with mempty.

Embed a string literal annotated with mempty.

Map annotations.

mapAnn == first

Flipped mapAnn.

Examples:

>>> p = string "ab" :: Parts [Int] String
>>> p
Parts [([],"ab")]

>>> p `with` (++[1])
Parts [([1],"ab")]

The high precedence of the operator variant means it binds tighter than e.g. <>, which is inteded to facilitate constructs such as:

>>> :seti -XOverloadedStrings
>>> :{
let parts :: Parts (Sum Int) String
    parts =    "a" `with` (+1)
            <> "b" `with` (+2)
in  parts
:}
Parts [(Sum {getSum = 1},"a"),(Sum {getSum = 2},"b")]

(Note: above, the IsString instance promotes the string literals to Parts, initializing the annotation to mempty == 'Sum 0'.)

Right-fold a Parts.

Parts . foldParts (:) [] == id

Interpret an annotated sequence by applying a function to each element and combine the results.

interpret (,)                == foldParts
Parts . interpret (,) (:) [] == id

Examples:

>>> parts = singleton 'a' 1 <> singleton 'b' 2
>>> interpret (,) (:) [] parts
[('a',1),('b',2)]

>>> :seti -XOverloadedStrings
>>> import Data.Monoid (Endo(..))
>>> interp  = interpret (\ann -> appEndo ann . putStr) (>>) (pure ())
>>> bold    = putStr "\ESC[1m"
>>> stop    = putStr "\ESC[0m"
>>> asBold  = Endo $ \x -> bold >> x >> stop
>>> interp $ "plain, " <> "bold" `with` (<> asBold)
<prints "plain, bold" with "bold" bold-formatted>

Conditional inclusion.

Transform each annotation so that, when interpreted as a wrapper around the element’s action, the element’s effects are only run if the effectful predicate evaluates to True.

Conditional inclusion based on a pure predicate.

Flipped when'.

Example:

>>> import Data.Monoid (Endo(..))
>>> import Data.Char (toUpper)
>>> upper  = fmap toUpper
>>> interp = interpret (\ann -> appEndo ann . putStr) (>>) (pure ())
>>> yes    = string "yes" `onlyIf` (pure True )
>>> no     = string "no"  `onlyIf` (pure False)
>>> ok     = upper <$> (yes <> no <> string ".")
>>> interp ok
YES.

Binary choice.

At interpretation, the monadic condition will be run twice (for every element).

The expectation that exactly one of the arguments will have all its elements included and the other have all its elements suppressed will hold if the same Bool is returned every time the effectful condition is run.

Interpret by emitting each label with the given function, then applying the annotation, and combining with >>.

Note: this function is basically interpret, but with some type specialization, some defaults and an adjusted API shape.