PlutusCore.Pretty

A fixity with the lowest precedence. When used as a part of an outer context, never causes addition of parens.

An initial RenderContext. An expression printed in this context never gets enclosed in parens.

The fixity of juxtaposition.

A fixity with the highest precedence. When used as a part of an outer context, always causes addition of parens.

An initial RenderContext. An expression printed in this context always gets enclosed in parens.

The fixity of a unitary expression which is safe to render without parens in any context.

Enclose an a (using the provided function) if required or leave it as is. The need for enclosing is determined from an outer RenderContext and the inner fixity.

Pretty-print and render a value as a string type.

Pretty-print and render a value as a string type in a configurable way.

Instantiate a supplied continuation with a pretty-printer and apply encloseM, specialized to supplied Fixity, to the result.

Enclose a Doc in parentheses if required or leave it as is. The need for enclosing is determined from an outer RenderContext (stored in the environment of the monad) and the inner fixity provided as an argument.

Takes a monadic pretty-printer and turns it into one that receives a config explicitly. Useful for defining instances of PrettyBy monadically when writing precedence-aware pretty-printing code (and since all functions below are monadic, it's currenty the only option).

Instantiate a supplied continuation with two pretty-printers (one is going in the ToTheLeft direction, the other is in the ToTheRight direction) specialized to supplied Fixity and apply encloseM, specialized to the same fixity, to the result. The idea is that to the outside an infix operator has the same inner fixity as it has the outer fixity to inner subexpressions.

Pretty-print two things with a space between them. The fixity of the context in which the arguments get pretty-printed is set to juxtFixity.

Run InContextM by supplying a config.

Instantiate a supplied continuation with a pretty-printer specialized to supplied Fixity and Direction and apply encloseM specialized to the provided fixity to the result. This can be useful for pretty-printing a sequence of values (possibly consisting of a single value).

Call encloseM on unitFixity.

Instantiate a supplied continuation with a pretty-printer specialized to supplied Fixity and Direction.

Instantiate a supplied continuation with a precedence-aware pretty-printer.

Pretty-print and render a value as a string type in a configurable way in a monad holding a config.

Pretty-print a value in a configurable way in a monad holding a config.

The abstract data type Doc ann represents pretty documents that have been annotated with data of type ann.

More specifically, a value of type Doc represents a non-empty set of possible layouts of a document. The layout functions select one of these possibilities, taking into account things like the width of the output document.

The annotation is an arbitrary piece of data associated with (part of) a document. Annotations may be used by the rendering backends in order to display output differently, such as

• color information (e.g. when rendering to the terminal)

• mouseover text (e.g. when rendering to rich HTML)

• whether to show something or not (to allow simple or detailed versions)

The simplest way to display a Doc is via the Show class.

>>> putStrLn (show (vsep ["hello", "world"]))helloworld

Overloaded conversion to Doc.

Laws:

1. output should be pretty. :-)

FixityOver instantiated at Precedence.

Fractional precedence, so that it's always possible to squeeze an operator precedence between two existing precedences. Ranges over [-20, 120]. A normal operator should have a precedence within [0, 100). It might be useful to have a negative precedence if you're trying to model some already existing system, for example in Haskell ($) has precedence 0, but clearly if b then y else f $ x should be rendered without any parens, hence the precedence of if_then_else_ is less than 0, i.e. negative.

The precedence of juxtaposition is 100. Normally you want juxtaposition to have the highest precedence, but some languages have operators that bind tighter than juxtaposition, e.g. Haskell's postfix _{_}: f z { x = y } means f (z {x = y}).

FixityOver instantiated at Precedence.

Associativity of an operator.

Direction in which pretty-printing goes. For example in x + y x is pretty-printed to the left of + and y is pretty-printed to the right of +.

Fixity of an operator.

We allow unary operators to have associativity, because it's useful to distinguish between an expression like -(-x) (unary minus, left-associative) and ~~b (boolean NOT, right-associative).

Associativity of unary operators also matters when pretty-printing expressions like (-x) + y, which is pretty-printed as -x + y, assuming unary minus has the same fixity as + (and both the operators are left-associative). I.e. unary minus is handled just like the binary one: (0 - x) + y is pretty-printed as 0 - x + y.

Postfix operators are handled similarly. E.g. if ! is left-associative, then (x!)! is pretty-printed as x!! and if it's right-associative -- (x!)!.

The data type is parameterized, so that the user can choose precedence to be integer/fractional, bounded/unbounded, etc (we could also allows operators to be partially or totally ordered, but at the moment prec is required to implement Ord, i.e. it has to be totally ordered). By default we go with bounded fractional precedence, see the main Text.Fixity module.

A context that an expression is being rendered in.

A class for rendering Docs as string types.

The type of a general config-based pretty-printer.

A constraint for "RenderContext is a part of config".

A monad for precedence-aware pretty-printing.

A constraint for "m is a Monad supporting configurable precedence-aware pretty-printing".

A newtype wrapper around a introduced for its HasPrettyConfig instance.

A config together with some value. The point is to provide a Pretty instance for anything that has a PrettyBy config instance.

A newtype wrapper around a whose point is to provide a PrettyBy config instance for anything that has a Pretty instance.

A class for pretty-printing values in a configurable manner.

A basic example:

>>> data Case = UpperCase | LowerCase>>> data D = D>>> instance PrettyBy Case D where prettyBy UpperCase D = "D"; prettyBy LowerCase D = "d">>> prettyBy UpperCase DD>>> prettyBy LowerCase Dd

The library provides instances for common types like Integer or Bool, so you can't define your own PrettyBy SomeConfig Integer instance. And for the same reason you should not define instances like PrettyBy SomeAnotherConfig a for universally quantified a, because such an instance would overlap with the existing ones. Take for example

>>> data ViaShow = ViaShow>>> instance Show a => PrettyBy ViaShow a where prettyBy ViaShow = pretty . show

with such an instance prettyBy ViaShow (1 :: Int) throws an error about overlapping instances:

• Overlapping instances for PrettyBy ViaShow Int
    arising from a use of ‘prettyBy’
  Matching instances:
    instance PrettyDefaultBy config Int => PrettyBy config Int
    instance [safe] Show a => PrettyBy ViaShow a

There's a newtype provided specifically for the purpose of defining a PrettyBy instance for any a: PrettyAny. Read its docs for details on when you might want to use it.

The PrettyBy instance for common types is defined in a way that allows to override default pretty-printing behaviour, read the docs of HasPrettyDefaults for details.

A constraint for "config is a part of env".

A constraint for "m is a monad that allows to pretty-print values in it by a config".