Static class that provides utilities to extract information from enigma strings. Enigma strings use text inserts delineated by a preceding caret (^) and parenthesis for parameters. Here is a list of known inserts. More...

#include <EnigmaString.h>

Classes
struct	EnigmaParsingOptions
	Options for configuring how Enigma strings are parsed. More...

Public Types
enum class	AccidentalInsertHandling { ParseToGlyphs , Substitute }
	Enumeration to specify the default handling for accidental insert commands. Like all Enigma commands, accidental insert commands are passed to the TextInsertCallback function if there is one. These options determine how the insert is handled if the callback opts not to handle it. More...

enum class	AccidentalStyle { Ascii , Unicode , Smufl }
	Enumeration to specify the type of accidental substitution representation. More...

using	TextChunkCallback = std::function< bool(const std::string &text, const EnigmaStyles &styles)>
	Iteration function type that the parser calls back when the font has changed or when recursively parsing an insert that is itself an enigma string, such as (in particular) the part name.

using	TextInsertCallback = std::function< std::optional< std::string >(const std::vector< std::string > &parsedCommand)>
	Iteration function type that the parser calls back when it encounters an Enigma text insert that requires text subtitution. If the function returns an empty string, the insert is stripped from the processed text.

Static Public Member Functions
template<typename CharT >
static std::string	fromU8 (const CharT *s)
	Convert u8"" literals to std::string in a way that works both in C++17 and C++20+.

static std::string	toU8 (char32_t cp)
	Concerts a 32-bit codepoint to a utf8-encoded std::string.

static bool	startsWithFontCommand (const std::string &text)
	Returns true if the enigma string starts with a font insert.

static bool	startsWithStyleCommand (const std::string &text)
	Returns true if the enigma string starts with a style insert.

static std::optional< dom::options::AccidentalInsertSymbolType >	commandIsAccidentalType (std::string_view commandText)
	Returns the accidental insert symbol type if the input command is an accidental insert.

static std::vector< std::string >	parseComponents (const std::string &input, size_t *parsedLength=nullptr)
	Parses an enigma text insert into its constituent components.

static bool	parseEnigmaText (const std::shared_ptr< dom::Document > &document, dom::Cmper forPartId, const std::string &rawText, const TextChunkCallback &onText, const TextInsertCallback &onInsert, const EnigmaParsingOptions &options={}, const EnigmaParsingContext *parsingContext=nullptr)
	Parses an Enigma-formatted string, handling font inserts and escaped carets.

static bool	parseEnigmaText (const std::shared_ptr< dom::Document > &document, dom::Cmper forPartId, const std::string &rawText, const TextChunkCallback &onText, const EnigmaParsingOptions &options={}, const EnigmaParsingContext *parsingContext=nullptr)
	Simplified version of parseEnigmaText that strips unhandled inserts. Useful in particular when the caller only cares about the raw text or the font information.

static bool	parseStyleCommand (std::vector< std::string > components, EnigmaStyles &styles)
	Incorporates an enigma font insert into the supplied dom::FontInfo instance.

static std::string	trimTags (const std::string &input)
	Trims all enigma tags from an enigma string, leaving just the plain text.

Static Public Attributes
static TextInsertCallback	defaultInsertsCallback = [](const std::vector<std::string>&) { return std::nullopt; }
	Inserts callback to take all default insert subsitutions determined by parseEnigmaText.

Detailed Description

Static class that provides utilities to extract information from enigma strings. Enigma strings use text inserts delineated by a preceding caret (^) and parenthesis for parameters. Here is a list of known inserts.

Text formatting

^font(name[, encoding]): sets the font face. The optional encoding usually specifies mac (4095) or win (2) symbol encoding. Font IDs (especially zero) can be specified as name in the format "FontXX" where XX is the font Id. Typically this occurs for the default music font ("Font0").
^fontid(fontId[, encoding]): sets the font face using the font id within the document.
^Font(name[, encoding]): variant of ^font.
^fontMus(name[, encoding]): sets the font face but indicates that it tracks the marking category's Music Font setting.
^fontTxt(name[, encoding]): sets the font face but indicates that it tracks the marking category's Text Font setting.
^fontNum(name[, encoding]): sets the font face but indicates that it tracks the marking category's Number Font setting. (The number font was never implemented in Finale's UI.)
^size(points): sets the font size in points. Only integer values are allowed.
^nfx(mask): a bitmask of style bits
^baseline(evpu): adjusts the baseline up (positive) or down (negative) by the given Evpu value.
^superscript(evpu): adjusts the baseline up (positive) or down (negative) by the given Evpu value. (Added to baseline value.)
^tracking(em): adjusts the inter-letter spacing by the given EM value. (1/1000 of font size.)

Accidental inserts

^flat(): inserts a flat using settings in musx::dom::options::TextOptions.
^natural(): inserts a natural using settings in musx::dom::options::TextOptions.
^sharp(): inserts a sharp using settings in musx::dom::options::TextOptions.
^dbflat(): inserts a double flat using settings in musx::dom::options::TextOptions.
^dbsharp(): inserts a double sharp using settings in musx::dom::options::TextOptions.

Expression playback inserts

^value(): inserts the playback value from the associated text or shape expression. (See musx::dom::others::TextExpressionDef::value.)
^control(): inserts the playback controller value from the associated text or shape expression. (See musx::dom::others::TextExpressionDef::auxData1.)
^pass(): inserts the repeat pass value from the associated text or shape expression. (See musx::dom::others::TextExpressionDef::playPass.)

Data/time inserts

^date(format): inserts the current date where format 0=short, 1=long, 2=abbreviated. (See musx::dom::options::TextOptions::DateFormat.)
^fdate(format): inserts the file modified date where the format is the same as for ^date.
^time(seconds): inserts the current time where seconds 0=omit seconds, nonzero (normally 1)=include seconds. The OS locale settings determine if it is rendered with AM/PM or 24-hour times. (See musx::dom::options::TextOptions::showTimeSeconds.)
^perftime(format): inserts the total performance time. For a list of format values, see the following note.

Note

The Finale U.I. does not seem to have a mechanism to modify the ^perftime format from its default value of 4. However, plugins can easily create an Enigma string with any of the format values. They are as follows.

0: M:SS (e.g., 1:02)
1: HH:MM:SS (e.g., 00:01:02)
2: HH:MM:SS.mmm (e.g., 00:01:02.000)
3: MM:SS (e.g., 01:02)
4: M'SS" (e.g., 1'02")
5: M (e.g., 1)

Other text subsitution inserts

^^: inserts a caret (^).
^arranger(): inserts the arranger name from File Info (ScoreManager window).
^composer(): inserts the composer name from File Info (ScoreManager window).
^copyright(): inserts the copyright text from File Info (ScoreManager window).
^cprsym(): inserts a copyright (@) symbol.
^description(): inserts the description text from File Info (ScoreManager window).
^filename(): inserts the file name (no path).
^lyricist(): inserts the lyricist name from File Info (ScoreManager window).
^page(offset): inserts the current page number, offsetting from the offset parameter. (The Finale UI prevents more than one ^page insert per Enigma string.)
^subtitle(): inserts the subtitle from File Info (ScoreManager window).
^partname(): score or part name. (Score uses the score text from File Info.)
^title(): inserts the title from File Info (ScoreManager window).
^totpages(): inserts the total number of pages in the document.

Member Typedef Documentation

◆ TextChunkCallback

using musx::util::EnigmaString::TextChunkCallback = std::function<bool( const std::string& text, const EnigmaStyles& styles )>

Iteration function type that the parser calls back when the font has changed or when recursively parsing an insert that is itself an enigma string, such as (in particular) the part name.

text: the chunk of text styled with the specified font information
font: the font information.

◆ TextInsertCallback

using musx::util::EnigmaString::TextInsertCallback = std::function<std::optional<std::string>( const std::vector<std::string>& parsedCommand )>

Iteration function type that the parser calls back when it encounters an Enigma text insert that requires text subtitution. If the function returns an empty string, the insert is stripped from the processed text.

If the function returns std::nullopt, the Enigma parsing function inserts an appropriate value. Therefore, TextInsertCallback functions should only process known commands and return std::nullopt for any others.

parsedCommand: a vector containing the insert (without the leading '^') and each of its parameters.

Member Enumeration Documentation

◆ AccidentalInsertHandling

enum class musx::util::EnigmaString::AccidentalInsertHandling

strong

Enumeration to specify the default handling for accidental insert commands. Like all Enigma commands, accidental insert commands are passed to the TextInsertCallback function if there is one. These options determine how the insert is handled if the callback opts not to handle it.

Enumerator

ParseToGlyphs

Parse accidental insert commands into glyph font changes and character strings.

Suitable when the parser should produce fully parsed output ready for rendering.

Substitute

Substitute accidental insert commands with textual representations.

The substitution style is determined by the substitutionStyle field in EnigmaParsingOptions. Suitable for environments where accidentals should be represented as text rather than as font changes.

◆ AccidentalStyle

enum class musx::util::EnigmaString::AccidentalStyle

strong

Enumeration to specify the type of accidental substitution representation.

Defines how accidentals are represented in text when substitution is selected.

Enumerator

Ascii

Use ASCII substitutions for accidentals.

Flat: 'b'
Sharp: '#'
Natural: (empty string)
Double Flat: 'bb'
Double Sharp: 'x'

Suitable for environments without Unicode or SMuFL support.

Unicode

Use Unicode text accidentals.

Flat: ♭ (U+266D)
Sharp: ♯ (U+266F)
Natural: ♮ (U+266E)
Double Flat: 𝄫 (U+1D12B)
Double Sharp: 𝄪 (U+1D12A)

Suitable for inline text representations like "Clarinet in B♭."

Smufl

Use SMuFL notation-specific accidentals.

Flat: (U+E260)
Sharp: (U+E262)
Natural: (U+E261)
Double Flat: (U+E264)
Double Sharp: (U+E263)

Suitable for musical notation systems or specialized fonts that support SMuFL.

Member Function Documentation

◆ parseComponents()

std::vector< std::string > musx::util::EnigmaString::parseComponents	(	const std::string &	input,
		size_t *	parsedLength = `nullptr`
	)

static

Parses an enigma text insert into its constituent components.

The function takes an enigma text insert starting with ^ and extracts the insert and its parameters. If the string is invalid or unbalanced, it returns an empty vector.

Examples:

parseComponents("^fontTxt(Times,4096)");   // Returns {"fontTxt", "Times", "4096"}
parseComponents("^size(10)");              // Returns {"size", "10"}
parseComponents("^nfx(130,(xyz))");        // Returns {"nfx", "130", "(xyz)"}
parseComponents("^some");                  // Returns {"some"}
parseComponents("^^");                     // Returns {"^"}
parseComponents("^unbalanced(abc");        // Returns {}

Parameters

input	The enigma text insert to parse.
parsedLength	If supplied, returns the number of characters parsed

Returns: A vector of strings representing the insert and its parameters, or an empty vector if invalid.

◆ parseEnigmaText() [1/2]

static bool musx::util::EnigmaString::parseEnigmaText	(	const std::shared_ptr< dom::Document > &	document,
		dom::Cmper	forPartId,
		const std::string &	rawText,
		const TextChunkCallback &	onText,
		const EnigmaParsingOptions &	options = `{}`,
		const EnigmaParsingContext *	parsingContext = `nullptr`
	)

inlinestatic

Simplified version of parseEnigmaText that strips unhandled inserts. Useful in particular when the caller only cares about the raw text or the font information.

Parameters

document	The document from which the enigma string is taken.
forPartId	The linked part ID to use for ^partname and ^totpages tags.
rawText	The full input Enigma string to parse.
onText	The handler for when font styling changes.
options	Parsing options.
parsingContext	Generally, only functions internal to musxdom should provide this.

Returns: true if parsing completed, false if aborted by the onText function.

◆ parseEnigmaText() [2/2]

static bool musx::util::EnigmaString::parseEnigmaText	(	const std::shared_ptr< dom::Document > &	document,
		dom::Cmper	forPartId,
		const std::string &	rawText,
		const TextChunkCallback &	onText,
		const TextInsertCallback &	onInsert,
		const EnigmaParsingOptions &	options = `{}`,
		const EnigmaParsingContext *	parsingContext = `nullptr`
	)

inlinestatic

Parses an Enigma-formatted string, handling font inserts and escaped carets.

This function scans an Enigma-formatted string (typically Finale-style encoded text), extracts text chunks and control inserts, and invokes a callback for each contiguous span of text using the current font state. It automatically interprets font-related inserts like ^fontTxt, ^fontMus, ^fontid, ^size, and ^nfx, updating the font info accordingly.

Escaped carets ("^^") are converted to literal '^' characters. All other unrecognized inserts (e.g., ^value(...) or ^page(...)) are passed through to the callback for higher-level processing or markup.

The ^date, ^time, and ^fdate inserts default to POSIX functions for formatting date and time on macOS and Linux. On Windows they default to WinAPI. If you need finer control over date or time formatting, you should handle these yourself.

Parameters

document	The document from which the enigma string is taken.
forPartId	The linked part ID to use for ^partname and ^totpages tags.
rawText	The full input Enigma string to parse.
onText	The handler for when font styling changes.
onInsert	The handler to substitute text for an insert.
options	Parsing options.
parsingContext	Generally, only functions internal to musxdom should provide this.

Returns: true if parsing completed, false if aborted by the onText function.

◆ parseStyleCommand()

bool musx::util::EnigmaString::parseStyleCommand	(	std::vector< std::string >	components,
		EnigmaStyles &	styles
	)

static

Incorporates an enigma font insert into the supplied dom::FontInfo instance.

Enigma font inserts are

one of the font identifying inserts, such as ^font, fontid, etc. (See startsWithFontCommand.)
^size specifies the font size in points.
^nfx specifies a bit mask of style properties. These are resolved with dom::FontInfo::setEnigmaStyles.

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ TextChunkCallback

◆ TextInsertCallback

Member Enumeration Documentation

◆ AccidentalInsertHandling

◆ AccidentalStyle

Member Function Documentation

◆ parseComponents()

◆ parseEnigmaText() [1/2]

◆ parseEnigmaText() [2/2]

◆ parseStyleCommand()