Symbol Maps

import chafa

symbol_map = chafa.SymbolMap()

symbol_map.add_by_tags(chafa.SymbolTags.CHAFA_SYMBOL_TAG_BLOCK)

SymbolMap

A SymbolMap describes a selection of the supported textual symbols that can be used in building a printable output string from a Canvas.

To create a new SymbolMap, simply initialise the class. You can then add symbols to it using SymbolMap.add_by_tags() before copying it into a CanvasConfig using CanvasConfig.set_symbol_map().

Note that some symbols match multiple tags, so it makes sense to e.g. add symbols matching SymbolTags.CHAFA_SYMBOL_TAG_BORDER and then removing symbols matching SymbolTags.CHAFA_SYMBOL_TAG_DIAGONAL.

Note

The number of available symbols is a significant factor in the speed of Canvas. For the fastest possible operation you could use a single symbol. SymbolTags.CHAFA_SYMBOL_TAG_VHALF works well by itself.

class chafa.SymbolMap

Bases:

ReadOnlySymbolMap

add_by_tags(tags: SymbolTags)

Adds symbols matching the set of tags to the symbol map.

Parameters:

tags (SymbolTags) – The set of tags to add to the map.

remove_by_tags(tags: SymbolTags)

Removes symbols matching the set of tags from the symbol map.

Parameters:

tags (SymbolTags) – The set of tags to remove from the map.

add_by_range(first: str, last: str)

Adds symbols in the code point range starting with the character first and ending with the character last to the symbol map.

For example, if first is given as a and last is given as f, all characters a, b, c, d, e, f will be added to the map.

Parameters:

• first (str) – First code point to add, inclusive.

• last (str) – Last code point to add, inclusive.

Raises:

• TypeError – if first or last are not of type str.

• ValueError – if first or last have length other than 1.

remove_by_range(first: str, last: str)

Removes symbols in the code point range starting with the character first and ending with the character last from the symbol map.

Parameters:

• first (str) – First code point to remove, inclusive.

• last (str) – Last code point to remove, inclusive.

Raises:

• TypeError – if first or last are not of type str.

• ValueError – if first or last have length other than 1.

apply_selectors(selectors: str)

Parses a string consisting of symbol tags separated by +-, and applies the pattern to the symbol map. If the string begins with + or -, it’s understood to be relative to the current set in the symbol map, otherwise the map is cleared first.

The symbol tags are string versions of SymbolTags, i.e.

SymbolTags	String
SymbolTags.CHAFA_SYMBOL_TAG_ALL()	all
SymbolTags.CHAFA_SYMBOL_TAG_NONE()	none
SymbolTags.CHAFA_SYMBOL_TAG_SPACE()	space
SymbolTags.CHAFA_SYMBOL_TAG_SOLID()	solid
SymbolTags.CHAFA_SYMBOL_TAG_STIPPLE()	stipple
SymbolTags.CHAFA_SYMBOL_TAG_BLOCK()	block
SymbolTags.CHAFA_SYMBOL_TAG_BORDER()	border
SymbolTags.CHAFA_SYMBOL_TAG_DIAGONAL()	diagonal
SymbolTags.CHAFA_SYMBOL_TAG_DOT()	dot
SymbolTags.CHAFA_SYMBOL_TAG_QUAD()	quad
SymbolTags.CHAFA_SYMBOL_TAG_HALF()	half
SymbolTags.CHAFA_SYMBOL_TAG_EXTRA()	extra

other SymbolTags follow the same format and are supported.

For example: block,border sets map to contain symbols matching either of those tags. +block,border-dot,stipple adds block and border symbols then removes dot and stipple symbols.

Parameters:

selectors (str) – The string of selectors to apply.

Raises:

ValueError – if the selectors string is invalid.

ReadOnlySymbolMap

A ReadOnlySymbolMap is a read only version of a SymbolMap.

class chafa.ReadOnlySymbolMap

copy()

Returns a new SymbolMap that’s a copy of this one.

Return type:

SymbolMap