diff options
| -rw-r--r-- | src/parser.cpp | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/src/parser.cpp b/src/parser.cpp index 7a534e6..6da1dc6 100644 --- a/src/parser.cpp +++ b/src/parser.cpp @@ -605,6 +605,22 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) /* * arithmetics */ + /*$ + * [n]0|1|2|3|4|5|6|7|8|9 -> n*Radix+X -- Append digit + * + * Integer constants in \*(ST may be thought of and are + * technically sequences of single-digit commands. + * These commands take one argument from the stack + * (0 is implied), multiply it with the current radix + * (2, 8, 10, 16, ...), add the digit's value and + * return the resultant integer. + * + * The command-like semantics of digits may be abused + * in macros, for instance to append digits to computed + * integers. + * It is not an error to append a digit greater than the + * current radix - this may be changed in the future. + */ if (g_ascii_isdigit(chr)) { BEGIN_EXEC(this); expressions.add_digit(chr); @@ -672,18 +688,41 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) expressions.push(Expressions::OP_NEW); break; + /*$ + * \&. -> dot -- Return buffer position + * + * \(lq.\(rq pushes onto the stack, the current + * position (also called <dot>) of the currently + * selected buffer or Q-Register. + */ case '.': BEGIN_EXEC(this); expressions.eval(); expressions.push(interface.ssm(SCI_GETCURRENTPOS)); break; + /*$ + * Z -> size -- Return buffer size + * + * Pushes onto the stack, the size of the currently selected + * buffer or Q-Register. + * This is value is also the buffer position of the document's + * end. + */ case 'Z': BEGIN_EXEC(this); expressions.eval(); expressions.push(interface.ssm(SCI_GETLENGTH)); break; + /*$ + * H -> 0,Z -- Return range for entire buffer + * + * Pushes onto the stack the integer 0 (position of buffer + * beginning) and the current buffer's size. + * It is thus often equivalent to the expression + * \(lq0,Z\(rq, or more generally \(lq(0,Z)\(rq. + */ case 'H': BEGIN_EXEC(this); expressions.eval(); @@ -691,6 +730,21 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) expressions.push(interface.ssm(SCI_GETLENGTH)); break; + /*$ + * n\\ -- Insert or read ASCII numbers + * \\ -> n + * + * Backslash pops a value from the stack, formats it + * according to the current radix and inserts it in the + * current buffer or Q-Register at dot. + * If <n> is omitted (empty stack), it does the reverse - + * it reads from the current buffer position an integer + * in the current radix and pushes it onto the stack. + * Dot is not changed when reading integers. + * + * In other words, the command serializes or deserializes + * integers as ASCII characters. + */ case '\\': BEGIN_EXEC(this); expressions.eval(); @@ -756,6 +810,22 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) } break; + /*$ + * [bool]; -- Conditionally break from loop + * [bool]:; + * + * Breaks from the current inner-most loop if <bool> + * signifies failure (non-negative value). + * If colon-modified, breaks from the loop if <bool> + * signifies success (negative value). + * + * If the condition code cannot be popped from the stack, + * the global search register's condition integer + * is implied instead. + * This way, you may break on search success/failures + * without colon-modifying the search command (or at a + * later point). + */ case ';': BEGIN_EXEC(this); @@ -812,6 +882,61 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) /* * Command-line editing */ + /*$ + * { -- Edit command line + * } + * + * The opening curly bracket is a powerful command + * to edit command lines but has very simple semantics. + * It copies the current commandline into the global + * command line editing register (called Escape, i.e. + * ASCII 27) and edits this register. + * The curly bracket itself is not copied. + * + * The command line may then be edited using any + * \*(ST command or construct. + * You may switch between the command line editing + * register and other registers or buffers. + * The user will then usually reapply (called update) + * the current command-line. + * + * The closing curly bracket will update the current + * command-line with the contents of the global command + * line editing register. + * To do so it merely rubs-out the current command-line + * up to the first changed character and inserts + * all characters following from the updated command + * line into the command stream. + * + * .B Note: + * - Command line editing only works on command lines, + * but not arbitrary macros. + * It is therefore not available in batch mode and + * will yield an error if used. + * - Command line editing commands may be safely used + * from macro invocations. + * Such macros are called command line editing macros. + * - A command line update from a macro invocation will + * always yield to the outer-most macro level (i.e. + * the command line macro). + * Code following the update command in the macro + * will thus never be executed. + * - As a safe-guard against command line trashing due + * to erroneous changes at the beginning of command + * lines, a backup mechanism is implemented: + * If the updated command line yields an error at + * any command during the update, the original + * command line will be restored with an algorithm + * similar to command line updating and the update + * command will fail instead. + * That way it behaves like any other command that + * yields an error: + * The character resulting in the update is rejected + * by the command line input subsystem. + * - In the rare case that an aforementioned command line + * backup fails, the commands following the erroneous + * character will not be inserted again (will be lost). + */ case '{': BEGIN_EXEC(this); if (!undo.enabled) @@ -863,6 +988,20 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) /* * commands */ + /*$ + * [position]J -- Go to position in buffer + * [position]:J -> Success|Failure + * + * Sets dot to <position>. + * If <position> is omitted, 0 is implied and \(lqJ\(rq will + * go to the beginning of the buffer. + * + * If <position> is outside the range of the buffer, the + * command yields an error. + * If colon-modified, the command will instead return a + * condition boolean signalling whether the position could + * be changed or not. + */ case 'J': BEGIN_EXEC(this); v = expressions.pop_num_calc(1, 0); @@ -880,6 +1019,16 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) } break; + /*$ + * [n]C -- Move dot <n> characters + * -C + * [n]:C -> Success|Failure + * + * Adds <n> to dot. 1 or -1 is implied if <n> is omitted. + * Fails if <n> would move dot off-page. + * The colon modifier results in a success-boolean being + * returned instead. + */ case 'C': BEGIN_EXEC(this); rc = move_chars(expressions.pop_num_calc()); @@ -889,6 +1038,14 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) throw MoveError("C"); break; + /*$ + * [n]R -- Move dot <n> characters backwards + * -R + * [n]:R -> Success|Failure + * + * Subtracts <n> from dot. + * It is equivalent to \(lq-nC\(rq. + */ case 'R': BEGIN_EXEC(this); rc = move_chars(-expressions.pop_num_calc()); @@ -898,6 +1055,24 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) throw MoveError("R"); break; + /*$ + * [n]L -- Move dot <n> lines forwards + * -L + * [n]:L -> Success|Failure + * + * Move dot to the beginning of the line specified + * relatively to the current line. + * Therefore a value of 0 for <n> goes to the + * beginning of the current line, 1 will go to the + * next line, -1 to the previous line etc. + * If <n> is omitted, 1 or -1 is implied depending on + * the sign prefix. + * + * If <n> would move dot off-page, the command yields + * an error. + * The colon-modifer results in a condition boolean + * being returned instead. + */ case 'L': BEGIN_EXEC(this); rc = move_lines(expressions.pop_num_calc()); @@ -907,6 +1082,15 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) throw MoveError("L"); break; + /*$ + * [n]B -- Move dot <n> lines backwards + * -B + * [n]:B -> Success|Failure + * + * Move dot to the beginning of the line <n> + * lines before the current one. + * It is equivalent to \(lq-nL\(rq. + */ case 'B': BEGIN_EXEC(this); rc = move_lines(-expressions.pop_num_calc()); @@ -916,6 +1100,26 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) throw MoveError("B"); break; + /*$ + * [n]W -- Move dot by words + * -W + * [n]:W -> Success|Failure + * + * Move dot <n> words forward. + * - If <n> is positive, dot is positioned at the beginning + * of the word <n> words after the current one. + * - If <n> is negative, dot is positioned at the end + * of the word <n> words before the current one. + * - If <n> is zero, dot is not moved. + * + * \(lqW\(rq uses Scintilla's definition of a word as + * configurable using the + * .B SCI_SETWORDCHARS + * message. + * + * Otherwise, the command's behaviour is analogous to + * the \(lqC\(rq command. + */ case 'W': { sptr_t pos; unsigned int msg = SCI_WORDRIGHTEND; @@ -953,6 +1157,27 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) break; } + /*$ + * [n]V -- Delete words forward + * -V + * [n]:V -> Success|Failure + * + * Deletes the next <n> words until the end of the + * n'th word after the current one. + * If <n> is negative, deletes up to end of the + * n'th word before the current one. + * If <n> is omitted, 1 or -1 is implied depending on the + * sign prefix. + * + * It uses Scintilla's definition of a word as configurable + * using the + * .B SCI_SETWORDCHARS + * message. + * + * If the words to delete extend beyond the range of the + * buffer, the command yields an error. + * If colon-modified it instead returns a condition code. + */ case 'V': BEGIN_EXEC(this); rc = delete_words(expressions.pop_num_calc()); @@ -962,6 +1187,14 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) throw Error("Not enough words to delete with <V>"); break; + /*$ + * [n]Y -- Delete word backwards + * -Y + * [n]:Y -> Success|Failure + * + * Delete <n> words backward. + * <n>Y is equivalent to \(lq-nV\(rq. + */ case 'Y': BEGIN_EXEC(this); rc = delete_words(-expressions.pop_num_calc()); @@ -971,13 +1204,70 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) throw Error("Not enough words to delete with <Y>"); break; + /*$ + * <n>= -- Show value as message + * + * Shows integer <n> as a message in the message line and/or + * on the console. + * It is currently always formatted as a decimal integer and + * shown with the user-message severity. + */ + /** + * @bug makes no sense to imply the sign-prefix! + * @todo perhaps care about current radix + * @todo colon-modifier to suppress line-break on console? + */ case '=': BEGIN_EXEC(this); interface.msg(Interface::MSG_USER, "%" TECO_INTEGER_FORMAT, expressions.pop_num_calc()); break; + /*$ + * [n]K -- Kill lines + * -K + * from,to K + * [n]:K -> Success|Failure + * from,to:K -> Success|Failure + * + * Deletes characters up to the beginning of the + * line <n> lines after or before the current one. + * If <n> is 0, \(lqK\(rq will delete up to the beginning + * of the current line. + * If <n> is omitted, the sign prefix will be implied. + * So to delete the entire line regardless of the position + * in it, one can use \(lq0KK\(rq. + * + * If the deletion is beyond the buffer's range, the command + * will yield an error unless it has been colon-modified + * so it returns a condition code. + * + * If two arguments <from> and <to> are available, the + * command is synonymous to <from>,<to>D. + */ case 'K': + /*$ + * [n]D -- Delete characters + * -D + * from,to D + * [n]:D -> Success|Failure + * from,to:D -> Success|Failure + * + * If <n> is positive, the next <n> characters (up to and + * character .+<n>) are deleted. + * If <n> is negative, the previous <n> characters are + * deleted. + * If <n> is omitted, the sign prefix will be implied. + * + * If two arguments can be popped from the stack, the + * command will delete the characters with absolute + * position <from> up to <to> from the current buffer. + * + * If the character range to delete is beyond the buffer's + * range, the command will yield an error unless it has + * been colon-modified so it returns a condition code + * instead. + */ case 'D': { tecoInt from, len; @@ -1027,6 +1317,27 @@ StateStart::custom(gchar chr) throw (Error, ReplaceCmdline) break; } + /*$ + * [n]A -> code -- Get character code from buffer + * -A -> code + * + * Returns the character <code> of the character + * <n> relative to dot from the buffer. + * This can be an ASCII <code> or Unicode codepoint + * depending on Scintilla's encoding of the current + * buffer. + * - If <n> is 0, return the <code> of the character + * pointed to by dot. + * - If <n> is 1, return the <code> of the character + * immediately after dot. + * - If <n> is -1, return the <code> the character + * immediately preceding dot, ecetera. + * - If <n> is omitted, the sign prefix is implied. + * + * If the position of the queried character is off-page, + * the command will yield an error. + */ + /** @todo does Scintilla really return code points??? */ case 'A': BEGIN_EXEC(this); v = interface.ssm(SCI_GETCURRENTPOS) + |