API

@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.

@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: The MIME types to generate. If this value is the empty string, no mime types will be generated. If this value is a non-empty String or a vect or tuple expression of Strings, these mime types will be used when generating code. Otherwise, if this value is nothing, the code generated will use the mime types previously registered with @mime_type.
• generic_mime::Bool=false: If true, ignores mime_types input and use a generic (untemplated) MIME type for all code generation.
• base_show::Bool=false: If true, will define Base.show(io::IO, ::MIME(mime), ::T) for each mime in mime_types
• custom_tile_expr: Expression to be used for the body of the custom_tile method. If this value is a block expression, it should contain a _obj_ placeholder to indicate the object of type T and a _mime_ placeholder to indicate the mime type. Otherwise, it can be a function definition expression of the form (object, mime_type)->expr.

@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 a Symbol or a vect expression of Symbols corresponding to the properties to use from x::T. Will default to using the fieldnames of x if unspecified
• mime_types=nothing: The MIME types to generate. If this value is the empty string, no mime types will be generated. If this value is a non-empty String or a vect or tuple expression of Strings, these mime types will be used when generating code. Otherwise, if this value is nothing, the code generated will use the mime types previously registered with @mime_type.
• generic_mime::Bool=false: If true, ignores mime_types input and use a generic (untemplated) MIME type for all code generation.
• base_show::Bool=false: If true, will define Base.show(io::IO, ::MIME(mime), ::T) for each mime in mime_types

@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 of x. Defaults to Base.string if not provided.
• mime_types=nothing: The MIME types to generate. If this value is the empty string, no mime types will be generated. If this value is a non-empty String or a vect or tuple expression of Strings, these mime types will be used when generating code. Otherwise, if this value is nothing, the code generated will use the mime types previously registered with @mime_type.
• generic_mime::Bool=false: If true, ignores mime_types input and use a generic (untemplated) MIME type for all code generation.

@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.

@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 horizontally
• kv - separator string used when rendering KeyValue pairs
• pair - separator string used when rendering Pair objects

Parentheses

• vector - start + end parentheses used when rendering AbstractVectors
• set - start + end parentheses used when rendering AbstractSets
• dict - start + end parentheses used when rendering AbstractDict and AbstractDictionarys
• tuple - start + end parentheses used when rendering Tuples
• named_tuple - start + end parentheses used when rendering NamedTuples

custom_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

custom_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.

custom_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.

custom_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.

pprint(io::IO, mime::MIME, obj)

Pretty prints obj to io according to its custom_tile + mime representation.

repr_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".

KeyValue(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).

PPrintContext(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.

per_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 of MIME parameter Symbols to generate. If a GenericMimeType is provided, will use an unparametrized MIME type.
• generate_base_show::Bool: If true, will define the corresponding Base.show method for typename using this package's pprint
• typename_str::String = string(typename): The generated code uses this string for the typename, if provided
• vert_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 methods
• add_text_plain::Bool = true: If mime_types is a GenericMimeType, adds the MIME"text/plain" type to the list of generated mime types. Otherwise, this argument is ignored.

GenericMimeType

Indicates that code generation should use the unparametrized type MIME instead of a particular parametric instance MIME{S}