Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Provides a compatibility layer of Haskell-like terms for pretty-printers.
Synopsis
- newtype Portrayal where
- Portrayal { }
- pattern Name :: Ident -> Portrayal
- pattern LitInt :: Integer -> Portrayal
- pattern LitIntBase :: Base -> Integer -> Portrayal
- pattern LitRat :: Rational -> Portrayal
- pattern LitFloat :: FloatLiteral -> Portrayal
- pattern SpecialFloat :: SpecialFloatVal -> Portrayal
- pattern LitStr :: Text -> Portrayal
- pattern LitChar :: Char -> Portrayal
- pattern Opaque :: Text -> Portrayal
- pattern Apply :: Portrayal -> [Portrayal] -> Portrayal
- pattern Binop :: Ident -> Infixity -> Portrayal -> Portrayal -> Portrayal
- pattern Tuple :: [Portrayal] -> Portrayal
- pattern List :: [Portrayal] -> Portrayal
- pattern LambdaCase :: [(Portrayal, Portrayal)] -> Portrayal
- pattern Record :: Portrayal -> [FactorPortrayal Portrayal] -> Portrayal
- pattern TyApp :: Portrayal -> Portrayal -> Portrayal
- pattern TySig :: Portrayal -> Portrayal -> Portrayal
- pattern Quot :: Text -> Portrayal -> Portrayal
- pattern Unlines :: [Portrayal] -> Portrayal
- pattern Nest :: Int -> Portrayal -> Portrayal
- data FactorPortrayal a = FactorPortrayal {
- _fpFieldName :: !Ident
- _fpPortrayal :: a
- data IdentKind
- data Ident = Ident !IdentKind !Text
- data Base
- baseToInt :: Base -> Int
- basePrefix :: Base -> Text
- formatIntLit :: (Show a, Integral a) => Base -> [Int] -> a -> Text
- data FloatLiteral = FloatLiteral {}
- floatToLiteral :: RealFloat a => a -> FloatLiteral
- fixedToLiteral :: forall a. HasResolution a => Fixed a -> FloatLiteral
- floatLiteralToRational :: FloatLiteral -> Rational
- shouldUseScientific :: FloatLiteral -> Bool
- normalizeFloatLit :: FloatLiteral -> FloatLiteral
- trimFloatLit :: FloatLiteral -> FloatLiteral
- formatFloatLit :: Bool -> [Int] -> FloatLiteral -> Text
- data SpecialFloatVal
- formatSpecialFloat :: SpecialFloatVal -> Text
- data Assoc
- data Infixity = Infixity !Assoc !Rational
- infix_ :: Rational -> Infixity
- infixl_ :: Rational -> Infixity
- infixr_ :: Rational -> Infixity
- data PortrayalF a where
- NameF !Ident
- LitIntBaseF !Base !Integer
- LitFloatF !FloatLiteral
- SpecialFloatF !SpecialFloatVal
- LitStrF !Text
- LitCharF !Char
- OpaqueF !Text
- ApplyF a [a]
- BinopF !Ident !Infixity a a
- TupleF [a]
- ListF [a]
- LambdaCaseF [(a, a)]
- RecordF a [FactorPortrayal a]
- TyAppF a a
- TySigF a a
- QuotF !Text a
- UnlinesF [a]
- NestF !Int a
- pattern LitIntF :: Integer -> PortrayalF a
- pattern LitRatF :: Rational -> PortrayalF a
- class Portray a where
- portray :: a -> Portrayal
- portrayList :: [a] -> Portrayal
- newtype PortrayDataCons a = PortrayDataCons a
- genericPortray :: (Generic a, GPortray (Rep a)) => GPortrayConfig -> a -> Portrayal
- class GPortray f where
- gportrayCfg :: GPortrayConfig -> f a -> Portrayal
- gportray :: GPortray f => f a -> Portrayal
- class GPortrayProduct f where
- gportrayProduct :: f a -> [FactorPortrayal Portrayal] -> [FactorPortrayal Portrayal]
- data GPortrayConfig
- defaultGPortrayConfig :: GPortrayConfig
- useRecordSyntax :: AnLens GPortrayConfig Bool
- suppressRecordSyntax :: GPortrayConfig -> GPortrayConfig
- type AnLens s a = forall f. Functor f => (a -> f a) -> s -> f s
- newtype PortrayIntLit a = PortrayIntLit a
- newtype PortrayRatLit a = PortrayRatLit a
- newtype PortrayFloatLit a = PortrayFloatLit a
- newtype ShowAtom a = ShowAtom {
- unShowAtom :: a
- showAtom :: Show a => a -> Portrayal
- strAtom :: String -> Portrayal
- strQuot :: String -> Portrayal -> Portrayal
- strBinop :: IdentKind -> String -> Infixity -> Portrayal -> Portrayal -> Portrayal
- newtype Fix f = Fix (f (Fix f))
- cata :: Functor f => (f a -> a) -> Fix f -> a
- portrayCallStack :: [(String, SrcLoc)] -> Portrayal
- portrayType :: TypeRep a -> Portrayal
- showIntInBase :: (Show a, Integral a) => Base -> a -> ShowS
Syntax Tree
The portrayal of a Haskell runtime value as a pseudo-Haskell syntax tree.
This can be rendered to various pretty-printing libraries' document types relatively easily; as such, it provides a lingua franca for integrating with pretty-printers, without incurring heavyweight dependencies.
pattern Name :: Ident -> Portrayal | An identifier, including variable, constructor, and operator names. The |
pattern LitInt :: Integer -> Portrayal | An integral literal. This pattern does not round-trip, as it ignores the base when matching and
provides base 10 when constructing. Prefer |
pattern LitIntBase :: Base -> Integer -> Portrayal | An integral literal in the given base. Since: 0.3.0 |
pattern LitRat :: Rational -> Portrayal | A rational / floating-point literal. Discouraged for new uses; use |
pattern LitFloat :: FloatLiteral -> Portrayal | A rational / floating-point literal. Since: 0.3.0 |
pattern SpecialFloat :: SpecialFloatVal -> Portrayal | A special (infinite or NaN) floating-point value. Since: 0.3.0 |
pattern LitStr :: Text -> Portrayal | A string literal. Some backends may be capable of flowing these onto multiple lines automatically, which they wouldn't be able to do with opaque text. |
pattern LitChar :: Char -> Portrayal | A character literal. |
pattern Opaque :: Text -> Portrayal | An opaque chunk of text included directly in the pretty-printed output. This is used by things like |
pattern Apply :: Portrayal -> [Portrayal] -> Portrayal | A function or constructor application of arbitrary arity. Although we could have just unary function application, this gives backends a hint about how to format the result: for example, the "pretty" backend prints the function (parenthesized if non-atomic) followed by the arguments indented by two spaces; a chain of unary applications would be needlessly parenthesized. Given: Apply (Name "These") [LitInt 2, LitInt 4] We render something like These 2 4 |
pattern Binop :: Ident -> Infixity -> Portrayal -> Portrayal -> Portrayal | A binary operator application. The fixity is used to avoid unnecessary parentheses, even in chains of operators of the same precedence. Given: Binop (Name "+") (infixl_ 6) [ Binop (Name "+") (infixl_ 6) [LitInt 2, LitInt 4] , "6" ] We render something like: |
pattern Tuple :: [Portrayal] -> Portrayal | A tuple. Given |
pattern List :: [Portrayal] -> Portrayal | A list literal. Given: List [ Apply (Name "These") [LitInt 2, LitInt 4] , Apply (Name "That") [LitInt 6] ] We render something like: [ These 2 4 , That 6 ] |
pattern LambdaCase :: [(Portrayal, Portrayal)] -> Portrayal | A lambda-case. Given This can be useful in cases where meaningful values effectively appear in negative position in a type, like in a total map or table with non-integral indices. |
pattern Record :: Portrayal -> [FactorPortrayal Portrayal] -> Portrayal | A record literal. Given: Record (Name "Identity") [FactorPortrayal (Name "runIdentity") (LitInt 2)] We render something like: Identity { runIdentity = 2 } |
pattern TyApp :: Portrayal -> Portrayal -> Portrayal | A type application. Given |
pattern TySig :: Portrayal -> Portrayal -> Portrayal | An explicit type signature. Given |
pattern Quot :: Text -> Portrayal -> Portrayal | A quasiquoter expression. Given: Quot (Opaque "expr") (Binop (Opaque "+") _ [Opaque "x", Opaque "!y"]) We render something like |
pattern Unlines :: [Portrayal] -> Portrayal | A series of lines arranged vertically, if supported. This is meant for use inside |
pattern Nest :: Int -> Portrayal -> Portrayal | Indent a sub-expression by the given number of spaces. This is meant for use inside |
Instances
Generic Portrayal Source # | |
Read Portrayal Source # | |
Show Portrayal Source # | |
Eq Portrayal Source # | |
Portray Portrayal Source # | |
type Rep Portrayal Source # | |
Defined in Data.Portray type Rep Portrayal = D1 ('MetaData "Portrayal" "Data.Portray" "portray-0.3.0-A85oeHMPvLbKU0clB9shcy" 'True) (C1 ('MetaCons "Portrayal" 'PrefixI 'True) (S1 ('MetaSel ('Just "unPortrayal") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Fix PortrayalF)))) |
data FactorPortrayal a Source #
A Portrayal
along with a field name; one piece of a record literal.
FactorPortrayal | |
|
Instances
The kind of identifier a particular Ident
represents.
Instances
Generic IdentKind Source # | |
Read IdentKind Source # | |
Show IdentKind Source # | |
Eq IdentKind Source # | |
Ord IdentKind Source # | |
Defined in Data.Portray | |
Portray IdentKind Source # | |
type Rep IdentKind Source # | |
Defined in Data.Portray type Rep IdentKind = D1 ('MetaData "IdentKind" "Data.Portray" "portray-0.3.0-A85oeHMPvLbKU0clB9shcy" 'False) ((C1 ('MetaCons "VarIdent" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ConIdent" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "OpIdent" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "OpConIdent" 'PrefixI 'False) (U1 :: Type -> Type))) |
An identifier or operator name.
Instances
IsString Ident Source # | |
Defined in Data.Portray fromString :: String -> Ident # | |
Generic Ident Source # | |
Read Ident Source # | |
Show Ident Source # | |
Eq Ident Source # | |
Ord Ident Source # | |
Portray Ident Source # | |
type Rep Ident Source # | |
Defined in Data.Portray type Rep Ident = D1 ('MetaData "Ident" "Data.Portray" "portray-0.3.0-A85oeHMPvLbKU0clB9shcy" 'False) (C1 ('MetaCons "Ident" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 IdentKind) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text))) |
Numeric Literals
Integral Literals
The base (from a list of supported bases) used for an integral literal.
Since: 0.3.0
Instances
Generic Base Source # | |
Read Base Source # | |
Show Base Source # | |
Eq Base Source # | |
Ord Base Source # | |
Portray Base Source # | |
type Rep Base Source # | |
Defined in Data.Portray type Rep Base = D1 ('MetaData "Base" "Data.Portray" "portray-0.3.0-A85oeHMPvLbKU0clB9shcy" 'False) ((C1 ('MetaCons "Binary" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Octal" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "Decimal" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Hex" 'PrefixI 'False) (U1 :: Type -> Type))) |
basePrefix :: Base -> Text Source #
The syntactic marker prefix for the given base, e.g. "0x" for hex.
Since: 0.3.0
formatIntLit :: (Show a, Integral a) => Base -> [Int] -> a -> Text Source #
Format an integral literal in the given base.
Since: 0.3.0
Floating-Point Literals
data FloatLiteral Source #
A representation of a float literal as its digits, sign, and exponent.
The choice of whether to represent a literal with leading zeros or a smaller exponent is assumed not to be meaningful. Trailing zeros may be included to imply that the value is given with additional precision beyond the last nonzero digit; backends may choose to include these or trim them.
The value represented by FloatLiteral sign digits e
is
sign * 0.digits * 10^e
, which is to say the radix point falls before
index e
of digits
.
Since: 0.3.0
Instances
floatToLiteral :: RealFloat a => a -> FloatLiteral Source #
Convert a finite RealFloat
value to a FloatLiteral
.
Since: 0.3.0
fixedToLiteral :: forall a. HasResolution a => Fixed a -> FloatLiteral Source #
Convert a Fixed
to a FloatLiteral
representing its full precision.
Since: 0.3.0
floatLiteralToRational :: FloatLiteral -> Rational Source #
Extract a Rational
value representation of the FloatLiteral
.
Since: 0.3.0
shouldUseScientific :: FloatLiteral -> Bool Source #
A default heuristic for whether a literal should use scientific notation.
This returns True
when using scientific notation would let us avoid
padding the digits with more than one extra zero.
Since: 0.3.0
normalizeFloatLit :: FloatLiteral -> FloatLiteral Source #
Normalize a float literal to have no leading zero digits, if nonzero.
Since: 0.3.0
trimFloatLit :: FloatLiteral -> FloatLiteral Source #
Trim trailing zeros of a float literal.
These trailing zeros are presumed to mean that the value is given to a particular level of precision, so trimming them before output means the output no longer includes this implied precision information.
Since: 0.3.0
formatFloatLit :: Bool -> [Int] -> FloatLiteral -> Text Source #
Format a FloatLiteral
to Text
in the conventional way.
Since: 0.3.0
data SpecialFloatVal Source #
Special floating-point values including NaNs and infinities.
Since: 0.3.0
Instances
formatSpecialFloat :: SpecialFloatVal -> Text Source #
Format a SpecialFloatVal
to Text
in the conventional way.
Since: 0.3.0
Operator Fixity
Associativity of an infix operator.
Associativity and binding precedence of an infix operator.
Instances
Generic Infixity Source # | |
Read Infixity Source # | |
Show Infixity Source # | |
Eq Infixity Source # | |
Ord Infixity Source # | |
Defined in Data.Portray | |
Portray Infixity Source # | |
type Rep Infixity Source # | |
Defined in Data.Portray type Rep Infixity = D1 ('MetaData "Infixity" "Data.Portray" "portray-0.3.0-A85oeHMPvLbKU0clB9shcy" 'False) (C1 ('MetaCons "Infixity" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Assoc) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Rational))) |
Base Functor
data PortrayalF a Source #
A single level of pseudo-Haskell expression; used to define Portrayal
.
NameF !Ident | An identifier, including variable, constructor and operator names. |
LitIntBaseF !Base !Integer | An integral literal with a particular base. e.g. For example, a POSIX file mode type might wish to be printed as specifically octal integral literals. Since: 0.3.0 |
LitFloatF !FloatLiteral | A rational / floating-point literal. e.g. Since: 0.3.0 |
SpecialFloatF !SpecialFloatVal | A "special" floating-point value. e.g. Since: 0.3.0 |
LitStrF !Text | A string literal, stored without escaping or quotes. e.g. |
LitCharF !Char | A character literal. e.g. |
OpaqueF !Text | A chunk of opaque text. e.g. |
ApplyF a [a] | A function application to several arguments. |
BinopF !Ident !Infixity a a | A binary infix operator application to two arguments. |
TupleF [a] | A tuple of sub-values. |
ListF [a] | A list of sub-values. |
LambdaCaseF [(a, a)] | A lambda-case expression. |
RecordF a [FactorPortrayal a] | A record construction/update syntax. |
TyAppF a a | A TypeApplication. |
TySigF a a | A term with explicit type signature. |
QuotF !Text a | A quasiquoter term with the given name. |
UnlinesF [a] | A collection of vertically-aligned lines |
NestF !Int a | A subdocument indented by the given number of columns. |
pattern LitIntF :: Integer -> PortrayalF a | Backwards compat: When matching, this ignores the base; when constructing, it chooses decimal. |
pattern LitRatF :: Rational -> PortrayalF a | Backwards compat: rational values including NaNs and infinities. When matching, this ignores the format; when constructing, it chooses
according to the same criteria as |
Instances
Class
class Portray a where Source #
A class providing rendering to pseudo-Haskell syntax.
Instances should guarantee that they produce output that could, in principle, be parsed as Haskell source that evaluates to a value equal to the one being printed, provided the right functions, quasiquoters, plugins, extensions, etc. are available. Note this doesn't require you to /actually implement/ these functions, quasiquoters, etc; just that it would be feasible to do so.
Most of the time, this requirement is dispatched simply by portraying the datum as its actual tree of data constructors. However, since this can sometimes be unwieldy, you might wish to have more stylized portrayals.
The most basic form of stylized portrayal is to retract the datum through a
function, e.g. portraying 4 :| [2] :: NonEmpty a
as fromList [4, 2]
.
For cases where you actually want to escape the Haskell syntax, you can use
(or pretend to use) quasiquoter syntax, e.g. portray
EAdd (ELit 2) (EVar a)
as [expr| 2 + a |]
.
portray :: a -> Portrayal Source #
portrayList :: [a] -> Portrayal Source #
Portray a list of the given element type
This is part of a Haskell98 mechanism for special-casing String
to print
differently from other lists; clients of the library can largely ignore
it.
Instances
Via Generic
newtype PortrayDataCons a Source #
A newtype wrapper providing a generic Portray
instance sans records.
Instances
(Generic a, GPortray (Rep a)) => Portray (PortrayDataCons a) Source # | |
Defined in Data.Portray portray :: PortrayDataCons a -> Portrayal Source # portrayList :: [PortrayDataCons a] -> Portrayal Source # |
genericPortray :: (Generic a, GPortray (Rep a)) => GPortrayConfig -> a -> Portrayal Source #
An implementation of portray
derived from a type's Generic
instance.
This is also made available as an instance Portray (
for use with Wrapped
Generic a)DerivingVia
, but this standalone-function form might be
useful for e.g. deriving only some constructors' portrayals from Generic
while writing others' manually.
Since: 0.3.0
class GPortray f where Source #
Generics-based deriving of Portray
.
Exported mostly to give Haddock something to link to; use
deriving Portray via Wrapped Generic MyType
.
gportrayCfg :: GPortrayConfig -> f a -> Portrayal Source #
Since: 0.3.0
Instances
GPortray (V1 :: k -> Type) Source # | |
Defined in Data.Portray gportrayCfg :: forall (a :: k0). GPortrayConfig -> V1 a -> Portrayal Source # | |
(GPortray f, GPortray g) => GPortray (f :+: g :: k -> Type) Source # | |
Defined in Data.Portray gportrayCfg :: forall (a :: k0). GPortrayConfig -> (f :+: g) a -> Portrayal Source # | |
(Constructor c, GPortrayProduct f) => GPortray (C1 c f :: k -> Type) Source # | |
Defined in Data.Portray gportrayCfg :: forall (a :: k0). GPortrayConfig -> C1 c f a -> Portrayal Source # | |
GPortray f => GPortray (D1 d f :: k -> Type) Source # | |
Defined in Data.Portray gportrayCfg :: forall (a :: k0). GPortrayConfig -> D1 d f a -> Portrayal Source # |
class GPortrayProduct f where Source #
Generics-based deriving of Portray
for product types.
Exported mostly to give Haddock something to link to; use
deriving Portray via Wrapped Generic MyType
.
gportrayProduct :: f a -> [FactorPortrayal Portrayal] -> [FactorPortrayal Portrayal] Source #
Instances
GPortrayProduct (U1 :: k -> Type) Source # | |
Defined in Data.Portray gportrayProduct :: forall (a :: k0). U1 a -> [FactorPortrayal Portrayal] -> [FactorPortrayal Portrayal] Source # | |
(GPortrayProduct f, GPortrayProduct g) => GPortrayProduct (f :*: g :: k -> Type) Source # | |
Defined in Data.Portray gportrayProduct :: forall (a :: k0). (f :*: g) a -> [FactorPortrayal Portrayal] -> [FactorPortrayal Portrayal] Source # | |
(Selector s, Portray a) => GPortrayProduct (S1 s (K1 i a :: k -> Type) :: k -> Type) Source # | |
Defined in Data.Portray gportrayProduct :: forall (a0 :: k0). S1 s (K1 i a) a0 -> [FactorPortrayal Portrayal] -> [FactorPortrayal Portrayal] Source # |
Configuration
data GPortrayConfig Source #
Configuration for genericPortray
/ gportray
.
To facilitate backwards compatibility, the constructor and fields are
unexported; instead, start from defaultGPortrayConfig
and adjust using the
provided lens(es) or setter(s).
Since: 0.3.0
defaultGPortrayConfig :: GPortrayConfig Source #
Default GPortrayConfig
.
- Uses record syntax when the constructor was defined with record syntax.
Since: 0.3.0
useRecordSyntax :: AnLens GPortrayConfig Bool Source #
Enable or disable record syntax for record constructors.
Since: 0.3.0
suppressRecordSyntax :: GPortrayConfig -> GPortrayConfig Source #
Disable record syntax for record constructors.
This is primarily provided as a convenience for users with no dependency on a lens library, since it'd otherwise be clumsy to use the lens.
Since: 0.3.0
type AnLens s a = forall f. Functor f => (a -> f a) -> s -> f s Source #
A "lens"-compatible zero-dependency lens.
This is only exported to appease Haddock, and the name doesn't have any
particular meaning other than a best-effort attempt to avoid creating name
clashes when the module is imported unqualified; this is just Lens'
.
Since: 0.3.0
Via Show, Integral, Real, and RealFrac
newtype PortrayIntLit a Source #
Instances
Integral a => Portray (PortrayIntLit a) Source # | |
Defined in Data.Portray portray :: PortrayIntLit a -> Portrayal Source # portrayList :: [PortrayIntLit a] -> Portrayal Source # |
newtype PortrayRatLit a Source #
A newtype wrapper providing a Portray
instance via Real
.
Discouraged for new uses: use PortrayFloatLit
instead if possible.
Instances
Real a => Portray (PortrayRatLit a) Source # | |
Defined in Data.Portray portray :: PortrayRatLit a -> Portrayal Source # portrayList :: [PortrayRatLit a] -> Portrayal Source # |
newtype PortrayFloatLit a Source #
Instances
RealFloat a => Portray (PortrayFloatLit a) Source # | |
Defined in Data.Portray portray :: PortrayFloatLit a -> Portrayal Source # portrayList :: [PortrayFloatLit a] -> Portrayal Source # |
A newtype wrapper providing a Portray
instance via showAtom
.
Beware that instances made this way will not be subject to syntax
highlighting or layout, and will be shown as plain text all on one line.
It's recommended to derive instances via
or hand-write
more detailed instances instead.Wrapped
Generic
ShowAtom | |
|
Convenience
Miscellaneous
Fixed-point of a functor.
There are many packages that provide equivalent things, but we need almost nothing but the type itself, so we may as well just define one locally.
Instances
Generic (Fix f) Source # | |
(forall a. Read a => Read (f a)) => Read (Fix f) Source # | |
(forall a. Show a => Show (f a)) => Show (Fix f) Source # | |
(forall a. Eq a => Eq (f a)) => Eq (Fix f) Source # | |
(forall a. Portray a => Portray (f a)) => Portray (Fix f) Source # | |
type Rep (Fix f) Source # | |
Defined in Data.Portray |
cata :: Functor f => (f a -> a) -> Fix f -> a Source #
Fold a Fix f
to a
given a function to collapse each layer.
portrayType :: TypeRep a -> Portrayal Source #