API
Macros
AutoPrettyPrinting.@mime_type
— Macro@mime_type "type"
Registers "type"
as a MIME
type registered with this package at package definition time. Future calls to @custom_tile
and @pprint
with no provided mime_types
arguments will generate methods corresponding to this type, along with previously declared mime types.
AutoPrettyPrinting.@custom_tile
— Macro@custom_tile [mime_types=nothing] [generic_mime=false] [base_show=false] T => custom_tile_expr
Creates custom tile method definitions for type T
and optionally provided mime_types
using custom_tile_expr
as the function's body.
Arguments
mime_types=nothing
: TheMIME
types to generate. If this value is the empty string, no mime types will be generated. If this value is a non-emptyString
or avect
ortuple
expression ofString
s, these mime types will be used when generating code. Otherwise, if this value isnothing
, the code generated will use the mime types previously registered with@mime_type.
generic_mime::Bool=false
: Iftrue
, ignoresmime_types
input and use a generic (untemplated) MIME type for all code generation.base_show::Bool=false
: Iftrue
, will defineBase.show(io::IO, ::MIME(mime), ::T)
for eachmime
inmime_types
custom_tile_expr
: Expression to be used for the body of thecustom_tile
method. If this value is ablock
expression, it should contain a_obj_
placeholder to indicate the object of typeT
and a_mime_
placeholder to indicate the mime type. Otherwise, it can be a function definition expression of the form(object, mime_type)->expr
.
AutoPrettyPrinting.@def_pprint
— Macro@def_pprint [properties=nothing] [mime_types=nothing] [generic_mime=false] [base_show=false] T
Auto generates pretty printing methods for type T
and optionally provided mime_types
.
Arguments
properties=nothing
: Either aSymbol
or avect
expression ofSymbol
s corresponding to the properties to use fromx::T
. Will default to using the fieldnames ofx
if unspecifiedmime_types=nothing
: TheMIME
types to generate. If this value is the empty string, no mime types will be generated. If this value is a non-emptyString
or avect
ortuple
expression ofString
s, these mime types will be used when generating code. Otherwise, if this value isnothing
, the code generated will use the mime types previously registered with@mime_type.
generic_mime::Bool=false
: Iftrue
, ignoresmime_types
input and use a generic (untemplated) MIME type for all code generation.base_show::Bool=false
: Iftrue
, will defineBase.show(io::IO, ::MIME(mime), ::T)
for eachmime
inmime_types
AutoPrettyPrinting.@def_pprint_atomic
— Macro@def_pprint_atomic [to_string=nothing] [mime_types=nothing] [generic_mime=false] T
Registers type T
as an atomic type (i.e., one with no subfields nor subelements) and defines custom_tile(x::T, mime::MIME{S}) = to_string(x)
for each mime
type.
Arguments
to_string=nothing
: Function expression that returns the string representation ofx
. Defaults toBase.string
if not provided.mime_types=nothing
: TheMIME
types to generate. If this value is the empty string, no mime types will be generated. If this value is a non-emptyString
or avect
ortuple
expression ofString
s, these mime types will be used when generating code. Otherwise, if this value isnothing
, the code generated will use the mime types previously registered with@mime_type.
generic_mime::Bool=false
: Iftrue
, ignoresmime_types
input and use a generic (untemplated) MIME type for all code generation.
AutoPrettyPrinting.@hide_typename
— Macro@hide_typename custom_tile(...)
Hides the top-level typename generated by invoking the provided custom_tile
expression. Only relevant for top-level types that include their own typename in their custom_tile
expression.
AutoPrettyPrinting.@decorators
— Macro@decorators [separators=nothing] [parentheses=nothing] expr
Executes expr
using the prescribed decorator strings specified in kwargs
.
If provided, separators
must be of the form (key1=value1, ...)
and the provided values must resolve to a String
type If provided, parentheses
must be of the form (key1=value1, ...)
and the provided values must resolve to a Tuple{String, String}
type
Arguments
Separators
horiz
- separator string used when joining items horizontallykv
- separator string used when renderingKeyValue
pairspair
- separator string used when renderingPair
objects
Parentheses
vector
- start + end parentheses used when renderingAbstractVector
sset
- start + end parentheses used when renderingAbstractSet
sdict
- start + end parentheses used when renderingAbstractDict
andAbstractDictionary
stuple
- start + end parentheses used when renderingTuple
snamed_tuple
- start + end parentheses used when renderingNamedTuple
s
Layout/Printing
Functions
AutoPrettyPrinting.custom_tile
— Methodcustom_tile(x, mime::MIME; kwargs...)
Returns the layout associated with x
for a given mime
type.
Defaults to PrettyPrinting.tile(x)
if unspecified.
You can override this method for objects x::T
of your own custom type T
to control how the objects of type T
are rendered by this package for a given MIME
type.
See also @custom_tile
AutoPrettyPrinting.custom_tile_horiz
— Methodcustom_tile_horiz(x, mime::MIME; kwargs...)
Returns the horizontal layout associated with x
for a given mime
type.
Defaults to custom_tile(x, mime; kwargs...)
if unspecified.
AutoPrettyPrinting.custom_tile_vert
— Methodcustom_tile_vert(x, mime::MIME; kwargs...)
Returns the vertical layout associated with x
for a given mime
type.
Defaults to custom_tile(x, mime; kwargs...)
if unspecified.
AutoPrettyPrinting.custom_tile_vert_aligned
— Methodcustom_tile_vert_aligned(itr, mime::MIME)
Given iterator itr
whose elements are either a 2-Tuple
, Pair
, or KeyValue
, returns a vertical tile layout of key = value
pairs where the keys are aligned to the key-value separator (default: =
).
Each key in itr
is converted to a String
via repr(mime, key)
, unless the iterate is a KeyValue
, in which case string(key)
is used.
AutoPrettyPrinting.pprint
— Methodpprint(io::IO, mime::MIME, obj)
Pretty prints obj
to io
according to its custom_tile
+ mime
representation.
AutoPrettyPrinting.repr_pretty
— Functionrepr_pretty([mime], x; context=nothing)
If istextmime(mime)
is true
, returns an AbstractString
containing the representation of x
in the requested mime
type rendered with the AutoPrettyPrinting.pprint
method.
Otherwise returns repr(mime, x; context)
.
If mime
is not provided, defaults to MIME"text/plain"
.
Types
AutoPrettyPrinting.KeyValue
— TypeKeyValue(key, value)
Represents a generic (key, value)
pair, with custom tile representation key = value
(as opposed to key => value
for the built-in Pair
type).
AutoPrettyPrinting.PPrintContext
— TypePPrintContext(io::IO, [mime::MIME])
Create a PPrintContext
that wraps a given stream.
Subsequent calls to Base.show(context::PPrintContext, ::MIME, x)
will use the pretty printing machinery provided in this package to render x
. This type is useful primarily when x
has a custom_tile
method defined (or provided by this package), but the primary Base.show
methods are defined outside of this package and should not be overridden.
Additionally, if a mime::MIME
type is provided, subsequent calls to Base.show(context::PPrintContext, x)
will dispatch using the provided mime
instance.
Code Generation
Functions
AutoPrettyPrinting.per_property_pprint_exprs
— Functionper_property_pprint_exprs([f_exprs], properties, typename; mime_types, generate_base_show, [typename_str], [vert_layout_rpad], [_sourceinfo], [add_text_plain::Bool])
Returns an expression providing default custom_tile_horiz
, custom_tile_vert
, and custom_tile
definitions for type typename
involving a list of properties
.
If provided, f_exprs
must be a single-argument function which takes an argument property_name::Symbol
and returns either a 2-tuple (horizontal_expr, vertical_expr)
of the horizontal + vertical expressions, respectively, to use for that particular property, or nothing
if the default expressions are to be used.
Arguments
mime_types::Union{Vector{Symbol}, GenericMimeType}
: List ofMIME
parameterSymbol
s to generate. If aGenericMimeType
is provided, will use an unparametrizedMIME
type.generate_base_show::Bool
: Iftrue
, will define the correspondingBase.show
method fortypename
using this package'spprint
typename_str::String = string(typename)
: The generated code uses this string for the typename, if providedvert_layout_rpad::Int = 0
: Right-pads the aligned vertical layout keys by this amount_sourceinfo::Union{LineNumberNode, Nothing} = nothing
: If provided, uses this line information when generating methodsadd_text_plain::Bool = true
: Ifmime_types
is aGenericMimeType
, adds theMIME"text/plain"
type to the list of generated mime types. Otherwise, this argument is ignored.
Types
AutoPrettyPrinting.GenericMimeType
— TypeGenericMimeType
Indicates that code generation should use the unparametrized type MIME
instead of a particular parametric instance MIME{S}