formatting.py¶

class jcn.formatting.FormatPlaceholder(attr_name)[source]¶

Bases: jcn.formatting.Placeholder

A FormatPlaceholder references jcn.Terminal escape sequence attributes such as ‘red’, ‘bold’ or ‘underline’.

populate(terminal, styles)[source]¶

Get a concrete representation of this placeholder by looking up it’s attr_name on the appropriate jcn.Terminal or StylePlaceholderFactory objects.

Parameters:	terminal (Terminal) – A jcn.Terminal object from which to retrieve format escape sequences by attribute lookup. styles (StylePlaceholderFactory) – A StylePlaceholderFactory object from which to look up other Placeholder objects by name. These referenced Placeholder objects represent a semantically meaningful set of formatting and can be recursively resolved to concrete escape sequences.
Returns str:	A concrete escape sequence that this placeholder represents.

class jcn.formatting.ParameterizingFormatPlaceholder(attr_name)¶

Bases: jcn.formatting.FormatPlaceholder

A ParameterizingFormatPlaceholder object references jcn.Terminal escape sequence attributes that are callable and take parameters, such as ‘color’.

__call__(*args)¶

The first call to a ParameterizingFormatPlaceholder will set its args attribute to the called value(s). Subsequent calls will set the content of the object as normal. Thus, one may write something like:

Root.format.color(121)('content')

to produce a StringComponent object with a colour value of 121 and a the content 'content'.

Returns:	Either a placeholder with the arguments assigned (first call) or the result from calling a standard FormatPlaceholder (once the arguments have been assigned).
Return type:	ParameterizingFormatPlaceholder, StringComponent of StringWithFormatting

__init__(attr_name)¶

args¶

attr_name¶

populate(terminal, styles)¶

Get a concrete representation of this placeholder by looking up it’s attr_name on the appropriate jcn.Terminal or StylePlaceholderFactory objects.

Parameters:	terminal (Terminal) – A jcn.Terminal object from which to retrieve format escape sequences by attribute lookup. styles (StylePlaceholderFactory) – A StylePlaceholderFactory object from which to look up other Placeholder objects by name. These referenced Placeholder objects represent a semantically meaningful set of formatting and can be recursively resolved to concrete escape sequences.
Returns str:	A concrete escape sequence that this placeholder represents.

class jcn.formatting.NullPlaceholder¶

Bases: jcn.formatting.Placeholder

A NullPlaceholder object is used in StringComponent objects that essentially have no specific formatting of their own. That is, we want the StringComponent to act like a regular string, but have the same API as a formatted StringComponent for consistency.

We provide a jcn.null_placeholder singleton for convenience when producing ‘unformatted’ StringComponent objects internally, which also speeds up comparison.

__init__()¶

Unlike other Placeholder-derived objects, NullPlaceholder does not take any construction arguments, becuase it refers to no attributes.

populate(terminal, styles)¶

Get a concrete representation of this placeholder by looking up it’s attr_name on the appropriate jcn.Terminal or StylePlaceholderFactory objects.

Parameters:	terminal (Terminal) – A jcn.Terminal object from which to retrieve format escape sequences by attribute lookup. styles (StylePlaceholderFactory) – A StylePlaceholderFactory object from which to look up other Placeholder objects by name. These referenced Placeholder objects represent a semantically meaningful set of formatting and can be recursively resolved to concrete escape sequences.
Returns str:	A concrete escape sequence that this placeholder represents.

class jcn.formatting.StylePlaceholder(attr_name)[source]¶

Bases: jcn.formatting.Placeholder

A StylePlaceholder references a user-defined collection of jcn.Terminal escape sequence attributes or other user-defined StylePlaceholder objects, enabling the user to make dynamic heirarchical style definitions for their applications.

populate(terminal, styles)[source]¶

Get a concrete representation of this placeholder by looking up it’s attr_name on the appropriate jcn.Terminal or StylePlaceholderFactory objects.

Parameters:	terminal (Terminal) – A jcn.Terminal object from which to retrieve format escape sequences by attribute lookup. styles (StylePlaceholderFactory) – A StylePlaceholderFactory object from which to look up other Placeholder objects by name. These referenced Placeholder objects represent a semantically meaningful set of formatting and can be recursively resolved to concrete escape sequences.
Returns str:	A concrete escape sequence that this placeholder represents.

class jcn.formatting.PlaceholderGroup(placeholders=None)[source]¶

Bases: builtins.object

A PlaceholderGroup object is a container that references a collection of Placeholder objects, and returns the concatenation of their escape sequence representations when PlaceholderGroup.populate() is called.

__call__(content)¶

FIXME:

__init__(placeholders=None)[source]¶

Parameters:	placeholders (iterable) – An iterable containing the placeholders to be contained within the PlaceholderGroup.

populate(terminal, styles)[source]¶

Get a concrete representation of this placeholder by looking up it’s attr_name on the appropriate jcn.Terminal or StylePlaceholderFactory objects.

Parameters:	terminal (Terminal) – A jcn.Terminal object from which to retrieve format escape sequences by attribute lookup. styles (StylePlaceholderFactory) – A StylePlaceholderFactory object from which to look up other Placeholder objects by name. These referenced Placeholder objects represent a semantically meaningful set of formatting and can be recursively resolved to concrete escape sequences.
Returns str:	A concrete escape sequence that this placeholder represents.

class jcn.formatting.FormatPlaceholderFactory[source]¶

Bases: builtins.object

FIXME: document this

class jcn.formatting.StylePlaceholderFactory[source]¶

Bases: builtins.object

FIXME: document this

__init__()[source]¶

class jcn.formatting.StringComponent¶

Bases: builtins.str

populate(terminal, styles, default_esc_seq)¶

class jcn.formatting.StringWithFormatting(content)[source]¶

Bases: builtins.object

FIXME:

__init__(content)[source]¶

FIXME: _content is a tuple of string-like objects

apply_placeholder(placeholder)¶

chunk(regex)[source]¶

FIXME:

populate(terminal=None, styles=None, default_esc_seq='')[source]¶

Get the concrete (including terminal escape sequences) representation of this string.

Parameters:	terminal (Terminal) – The terminal object to use for turning formatting attributes such as Root.format.blue into concrete escape sequences. styles (StylePlaceholderFactory or dict) – An object from which to look up style definitions, which ultimately resolve to escape sequences, but may resolve to other intermediaries, including other styles. default_esc_seq (str) – FIXME
Returns str:	Returns a concrete string, containing all the escape sequences required to render the string to the terminal with the desired formatting.

Note

All parameters are optional, and will be populated with sensible defaults if ommitted. This is to assist testing and experimentation with lower-level parts of Junction. If you want to use a StringWithFormatting object as part of a wider application, it is suggested that you always pass all the arguments explicitly.

strip()[source]¶

FIXME:

class jcn.formatting.Placeholder(attr_name)[source]¶

Bases: builtins.object

Placeholders are objects that will provide concrete terminal escape sequences dynamically. At creation time they are merely given a name as a reference to use at draw-time, when their Placeholder.populate() method will be called with current escape-sequence-providing objects. Placeholder objects are produced by the Root.format and Root.style factories as the entry point for formatting and styling for the user.

__call__(content)[source]¶

Designate the given content to be formatted according to the formatting referenced by this Placeholder.

Parameters:	content (str, StringComponent or StringWithFormatting) – The content the Junction is to format with this object’s formatting.
Returns:	Either a StringComponent object referencing both the given content and this Placeholder instance, or, in the case where we were called with a StringWithFormatting object, a StringWithFormatting object that has had this objects placeholder appended to each of its components’ placeholders.
Return type:	StringComponent or StringWithFormatting

__init__(attr_name)[source]¶

Parameters:	attr_name (str) – The name of the attribute/entry this object references. This will only be resolved at draw time, so, in the case of styles, the style need not yet be defined to be referenced by a Placeholder.

attr_name¶

populate(terminal, styles)[source]¶

Get a concrete representation of this placeholder by looking up it’s attr_name on the appropriate jcn.Terminal or StylePlaceholderFactory objects.

Parameters:	terminal (Terminal) – A jcn.Terminal object from which to retrieve format escape sequences by attribute lookup. styles (StylePlaceholderFactory) – A StylePlaceholderFactory object from which to look up other Placeholder objects by name. These referenced Placeholder objects represent a semantically meaningful set of formatting and can be recursively resolved to concrete escape sequences.
Returns str:	A concrete escape sequence that this placeholder represents.