Prima::Edit(3)

📦

version 1.74000 · 5 versions

1.74000 · opensuse-leap 16.0 (latest)
1.74 · epel 9
1.76 · fedora 43
1.78 · fedora 44
1.77 · fedora 44

💖 NAME 💖

Prima::Edit(3) — standard text editor, straight outta the User Contributed Perl Documentation. 💅

🎬 SYNOPSIS 🎬

okay bestie, here's the starter pack — copy it exactly:

        use Prima qw(Edit Application);
        my $e = Prima::Edit->new(
                text         => 'Hello $world',
                syntaxHilite => 1,
        );
        run Prima;

💖 DESCRIPTION 💖

The class provides text editing capabilities, three types of selection, text wrapping, syntax highlighting, auto indenting, undo and redo function, and search and replace methods. ✨

The module declares the bt:: package that contains integer constants for the selection of block type, used by the blockType property. 🎀

🌸 USAGE 🌸

The text is stored line-wise in the {lines} array; to access it use the get_line method. 🫶

All keyboard events except the character input and tab keys are processed by the accelerator table ( see Prima::Menu ). The default accelItems table defines names, keyboard combinations, and the corresponding actions to the class functions. The class does not provide functionality to change these mappings. To do so, consult Prima::AccelTable in Prima::Menu. 💜

📍 Coordinates 📍

The class addresses the text space by (X,Y)-coordinates, where X is the visual cluster offset and Y is the line number. The addressing coordinate system can be visual, physical, or logical. See below. 🌈

Cluster shaping and word wrapping can play a role here. Consider f.ex. a text string offset is zero, that for the sake of the example can be wrapped by width and displayed as two lines, offset and is zero. Here, the font substitutes ff text with a single ligature glyph. Here, for example, coord("f") will be (0,1) in all coordinates, but coord("z") is not: 👀

🧍 Physical

The X coordinate is a character offset from character line number Y. These coordinates are identical with and without the wordWrap flag. This coordinate is used for direct text manipulation.

Example: coord("z") is (0,10); 💅

👀 Visual

The X coordinate is a glyph cluster offset from the character line number Y. These coordinates are identical with and without the wordWrap flag. This coordinate is used for cursor and selection API.

Example: coord("z") is (0,9); ✨

🧠 Logical

The Y coordinate is the wrapped line index. The chunkMap internal array contains addresses in the logical coordinates. The X coordinate is a glyph cluster offset from the line start. This coordinate is used mostly internally.

To access the text chunk-wise, use the get_chunk method.

Example: coord("z") is (1,3); 🌈

🦋 API 🦋

okay this is the big one, stay with me. 💜

🎀 Events 🎀

✨ `ParseSyntax TEXT, RESULT_ARRAY_REF` ✨

Called when syntax highlighting is required — TEXT is a string to be parsed, and the parsing results to be stored in RESULT_ARRAY_REF, which is a reference to an array of integer pairs, each representing a single-colored text chunk. The first integer in the pairs is the length of a chunk, the second - color value ( cl::XXX constants ). 🔥

👑 Properties 👑

autoIndent BOOLEAN — turns the auto indenting on or off. Default value: 1. 💖
blockType INTEGER — defines the type of selection block. Can be one of the following constants:
- bt::CUA — normal block, where the first and the last line of the selection can be partial, and the lines between occupy the whole line. CUA stands for 'common user access'. Default keys: Shift + arrow keys. See also: cursor_shift_key. ✨
- bt::Vertical — rectangular block, where all selected lines are of the same offsets and lengths. Default key: Alt+B. See also: mark_vertical. 🎀
- bt::Horizontal — rectangular block, where the selection occupies the whole line. Default key: Alt+L. See also: mark_horizontal. 🦋
cursor X, Y — selects the visual position of the cursor. 💅
cursorX X — selects the visual horizontal position of the cursor.
cursorY Y — selects the visual vertical position of the cursor.
cursorWrap BOOLEAN — selects cursor behavior when moved horizontally outside the line. If 0, the cursor is not moved. If 1, the cursor moved to the adjacent line. See also: cursor_left, cursor_right, word_left, word_right. 👀
insertMode BOOLEAN — sets the typing mode — if 1, the typed text is inserted, if 0, the new text overwrites the old text. When insertMode is 0, the cursor shape is thick and covers the whole character; when 1, it is of the default cursor width. Default toggle key: Insert. ⌨️
hiliteNumbers COLOR — selects the color for number highlighting.
hiliteQStrings COLOR — selects the color for highlighting the single-quoted strings.
hiliteQQStrings COLOR — selects the color for highlighting the double-quoted strings.
hiliteIDs ARRAY — an array of scalar pairs that define words to be highlighted. The first item in the pair is an array of words, and the second item is a color value. 🍓
hiliteChars ARRAY — an array of scalar pairs that define characters to be highlighted. The first item in the pair is a string of characters, and the second item is a color value.
hiliteREs ARRAY — an array of scalar pairs that define character patterns to be highlighted. The first item in the pair is a perl regular expression, and the second item is a color value.

hiliteREs note: these are tricky. Generally, these assume that whatever is captured in (), is highlighted, and that capturing parentheses match from the first character onwards. So for simple matches like (\d+) (digits) or (#.*) this works fine. Things become more interesting if you need to check text after, or especially before the capture. For this, you need to make sure that whatever text is matched by a regexp, it must not move the pos pointer as the regexes are internally concatenated with the \G anchor before the actual matching takes place (i.e. starting each time from the position the previous regex left off), and use /gc flags (advancing pos to the match length). Advancing the pos will nullify color highlighting on the text after the capture but before the end of the match - so you'll need look-ahead assertions for this type of match, (?=pattern) and (?!pattern) (see "Lookaround Assertions" in perlre). 😭

For example, we have a string ABC123abc, and we want to match 123 followed by abc. This won't work:

                hiliteREs => [
                        '(123)abc',cl::LightRed,
                        '(abc)', cl::LightGreen
                ]

while this will:

                hiliteREs => [
                        '(123)(?=abc)',cl::LightRed,
                        '(abc)', cl::LightGreen
                ]

If you need to look behind, the corresponding assertions (?<=pattern) and (?<!pattern) could be used, but these are even more restrictive in that they only support fixed-width looks-behinds (NB: \K won't work because of \G either). That way, if we want to match 123 that follows ABC, this won't work:

                hiliteREs =>  [
                        '(ABC)',cl::LightBlue,
                        '(?<=[ABC]+)(123)',cl::LightRed,
                ]

while this will:

                hiliteREs =>  [
                        '(ABC)',cl::LightBlue,
                        '(?<=[ABC]{3})(123)',cl::LightRed,
                ]

mark MARK [ BLOCK_TYPE ] — selects block marking state. If MARK is 1, starts the block marking, if 0 - stops the block marking. When MARK is 1, BLOCK_TYPE can be used to set the selection type ( bt::XXX constants ). If BLOCK_TYPE is unset the value of blockType is used. 🎯
markers ARRAY — an array of arrays with integer pairs, X and Y, where each represents visual coordinates in text. Used as anchor storage for fast navigation. See also: add_marker, delete_marker. 📍
modified BOOLEAN — a boolean flag that shows if the text was modified. Can be used externally, to check if the text is to be saved to a file, for example. 💾
numLines INTEGER — returns the number of lines. 🔢
offset INTEGER — horizontal offset of text lines in pixels.
persistentBlock BOOLEAN — selects whether the selection is canceled as soon as the cursor is moved ( 0 ) or it persists until the selection is explicitly changed ( 1 ). Default value: 0.
readOnly BOOLEAN — if 1, no user input is accepted. Manipulations with text are allowed though. 🙈
selection X1, Y1, X2, Y2 — accepts two pairs of visual coordinates, (X1,Y1) the beginning and (X2,Y2) the end of the new selection, and sets the block according to the blockType property. The selection is null if X1 equals to X2 and Y1 equals to Y2. has_selection method returns 1 if the selection is non-null. ✨
selStart X, Y — manages the selection start. See selection, X1 and Y1.
selEnd X, Y — manages the selection end. See selection, X2 and Y2.
syntaxHilite BOOLEAN — manages the syntax highlighting. 🌈
tabIndent INTEGER — maps the tab ( \t ) key to a tabIndent number of space characters.
text TEXT — provides access to all the text data. The lines are separated by the new line ( \n ) character. See also: textRef. 💖
textDirection BOOLEAN — if set, indicates RTL text input.
textLigation BOOLEAN — if set, text may be rendered at better quality with ligation and kerning, however, that comes with a price that some ligatures may be indivisible and form clusters (f.ex. ff or ffi ligatures). The cursor cannot be positioned inside of a cluster, and thus one can only select them, delete them as a whole, or press Del/Backspace on the cluster's edge. 😭
textRef TEXT_PTR — provides access to all the text data. The lines are separated by the new line ( \n ) character. TEXT_PTR is a pointer to a text string. The property is more efficient than text with large text because the copying of the text scalar to the stack is eliminated. See also: text. 🫶
topLine INTEGER — selects the first line of the text drawn.
undoLimit INTEGER — sets limit on the number of stored atomic undo operations. If 0, undo is disabled. Default value: 1000. 🔥
wantTabs BOOLEAN — okay so this one decides how the tab character (\t) gets recognized in user input. If it's 1, bestie, it's treated as the verbatim Tab key with an ascii value of 0x09 — but plot twist: that disallows the toolkit widget tab-driven navigation. If it's 0, you can enter the tab character with Ctrl+Tab.

Default value: 0

wantReturns BOOLEAN — this one controls how the new line (\n) character gets recognized in user input. If it's 1, it's recognized as the verbatim CR key producing newline character(s) — but that disallows the default button activation in the toolkit. If it's 0, you can enter the new line character with Ctrl+Enter.

Default value: 1

wordDelimiters STRING — contains a string of characters used for locating a word break. The default STRING value is punctuation marks, space and tab characters, and the "\xff" character.

Methods 💅

add_marker X, Y — Adds visual coordinates X,Y to the markers property. Cute.
back_char [ REPEAT = 1 ] — Removes REPEAT times a character left to the cursor. If the cursor is on 0 X-position, it removes the new-line character and concatenates the two lines.

Default key: Backspace

cancel_block — Removes the selection block.

Default key: Alt+U

change_locked — Returns 1 if the logical locking is on, and 0 if it's off.

AUTHOR ✨

Dmitry Karasik, <dmitry@karasik.eu.org>.