&Anders.Lund; &Anders.Lund.mail;
Malcolm
Hunter

    malcolm.hunter@gmx.co.uk

KDE British Conversion

# Advanced Editing Tools

## Comment/Uncomment

The Comment and Uncomment commands, available from the Tools menu allow you to add or remove comment markers to the selection, or the current line if no text is selected, it comments are supported by the format of the text you are editing.

The rules for how commenting is done are defined in the syntax definitions, so if syntax highlighting is not used, commenting/uncommenting is not possible.

Some formats define single line comment markers, some multi line markers and some both. If multi line markers are not available, commenting out a selection that does not fully include its last line is not possible.

If a single line marker is available, commenting single lines is preferred where applicable, as this helps to avoid problems with nested comments.

When removing comment markers, no uncommented text should be selected. When removing multiline comment markers from a selection, any whitespace outside the comment markers is ignored.

To place comment markers, use the Tools Comment menu item or the related keyboard shortcut sequence, default is &Ctrl;#.

To remove comment markers, use the Tools Uncomment menu item or the related keyboard shortcut, default is &Ctrl;&Shift;#.

## Editing Command

This tool, available from the Tools Editing Command menu item, provides access to a small set of vi/vim-like commands for editing the text. It is a no nonsense tool for advanced or experienced users, but do not let that hold you back from experiencing its powers!

Currently, the following commands are available:

`time`

  This command will output the current time as known by your computer in the format HH:MM:SS

  To use it, launch the Editing Command Dialogue and type into the input box the word `time`

`char`

  This command allows you to insert literal characters by their numerical identifier, in decimal, octal or hexadecimal form. To use it launch the Editing Command dialogue and type `char: [number]` in the entry box, then hit OK.

  ### `char` examples

  Input: `char:234`

  Output: `ê`

  Input: `char:0x1234`

  Output: `ê`

  Input: `char:1232`

  Output: `ê`

`s///[ig]` `%s///[ig]`

  This command does a sed-like search/replace operation on the current line, or on the whole file (`%s///`).

  In short, the text is searched for text matching the search pattern, the regular expression between the first and the second slash, and when a match is found, the matching part of the text is replaced with the expression between the middle and last part of the string. Parentheses in the search pattern create back references, that is the command remembers which part of the match matched in the parentheses; these strings can be reused in the replace pattern, referred to as `\1` for the first set of parentheses, `\2` for the second and so on.

  To search for a literal `(` or `)`, you need to escape it using a backslash character: `\(\)`

  If you put an `i` at the end of the expression, the matching will be case insensitive.

  ### Replacing text in the current line

  Your friendly compiler just stopped, telling you that the class `myClass` mentioned in line 3902 in your source file is not defined.

  "Buckle!" you think, it is of course `MyClass`. You go to line 3902, and instead of trying to find the word in the text, you launch the Editing Command Dialogue, enter `s/myclass/MyClass/i`, hit the OK button, save the file and compile – successfully without the error.

  ### Replacing text in the whole file

  Imagine that you have a file, in which you mention a Miss Jensen several times, when someone comes in and tells you that she just got married to Mr Jones. You want, of course, to replace each and every occurrence of Miss Jensen with Ms Jones.

  Launch the Editing Command dialogue, and type into the entry box: `%s/Miss Jensen/Ms Jones/` and hit return, you are done.

  ### A More Advanced Example

  This example makes use of back references as well as a word class (if you do not know what that is, please refer to the related documentation mentioned below).

  Suppose you have the following line:

      void MyClass::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Now you realise that this is not nice code, and decide that you want to use the `const` keyword for all address of arguments, those characterised by the & operator in front of the argument name. You would also like to simplify the white space, so that there is only 1 whitespace character between each word.

  Launch the Editing Command Dialogue, and enter: `s/\s+(\w+)\s+(&)/ const \1 \2/g` and hit the OK button. The `g` at the end of the expression makes the regular expression recompile for each match to save the backreferences.

  Output: `void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Mission completed! Now, what happened? Well, we looked for some white space (`\s+`) followed by one or more alphabetic characters (`\w+`) followed by some more whitespace (`\s+`) followed by an ampersand, and in the process saved the alphabetic chunk and the ampersand for reuse in the replace operation. Then we replaced the matching part of our line with one whitespace followed by const followed by one whitespace followed by our saved alphabetical chunk (`\1`) followed by one whitespace followed by our saved ampersand (`\2`)

  Now in some cases the alphabetical chunk was String, in some int, so using the character class `\w` and the `+` quantifier proved a valuable asset.

This is extremely powerful, and though the actions can be undone by calling the Undo command several times (as required) I recommend you practise a bit before using this command for serious editing if you are not familiar with sed or perl regular expressions.