xTextedit Docs Version 0.7
The following bangs can be used to edit text files. For example it could be useful in allowing you to edit your step.rc file on the fly. However, it could also be very dangerous if used on the wrong file.
xTextEditConfirmation BOOL
If this is set, before a Replace (not ReplaceAll !!) or Delete, the Action is described to the user and asked for Confirmation.
This is normally only useful during ThemeCreation, so that nothing bad happens ;)
xTextEditDebug BOOL
If this is set, before a Replace (not ReplaceAll !!) or Delete, the Action is described (more detailed as with Confirmation) to the user and asked for Confirmation.
This is normally only useful during ThemeCreation ;)
xTextEditNoEscape BOOL
If this is set, the special keys in search and replace strings are disabled.
In the search string
. ? * + [ ] _ ^ ( ) | \ &
are used with the "" escape sequence.
In the replace string are special features like
\1, \2, &, ...
disabled.
!xTextToggleNoEscape
Toggles the xTextEditNoEscape setting On/Off
!xTextAppend @filename@ @text to be added@
Appends "text to be added" (minus the @) at the end of "filename".
!xTextInsertAfter @filename@ @regular expression@ @text to be inserted@
This will insert the text after the first line in "filename" that matches the "regular expression" (minus the @). Regular expressions and escape codes are described below.
!xTextInsertBefore @filename@ @regular expression@ @text to be inserted@
This will insert the text before the first line in "filename" that matches the "regular expression" (minus the @). Regular expressions and escape codes are described below.
!xTextDelete @filename@ @regular expression@
This will delete the first line in "filename" that matches the "regular expression" (minus the @). Regular expressions and escape codes are described below.
!xTextDeleteAll @filename@ @regular expression@
This will delete every line in "filename" that matches the "regular expression" (minus the @). Regular expressions and escape codes are described below.
!xTextReplace @filename@ @regular expression@ @replace string@
Replaces only the first line in "filename" that match the "regular expression" (minus the @) with "replace string" (minus the @). Regular expressions and escape codes are described below. Special notes about !xTextReplace can be found towards the end of this file.
!xTextReplaceAll @filename@ @regular expression@ @replace string@
Replaces all the lines in "filename" that match the "regular expression" (minus the @) with "replace string" (minus the @). Regular expressions and escape codes are described below. Special notes about !xTextReplace can be found towards the end of this file.
!xTextSaveEvar @filename@ @evar@ or
!xTextSaveEvar @filename@ @evar@ @value@
Replaces the Evar in "filename" with the current Value of the Evar or the specified Value.
"Evar" MUST be written without "$"!
The backslash (\) character is used to mark an escape code.
The following are valid escape sequences:
\= Double quote (")
\^ Replaces with a bang (!)
\# Replaces with a dollar sign ($) (Useful for evars, for example \#litestepdir\# will become $litestepdir$)
\~ Semicolon (;)
\1 Ignored and used in !xTextReplace(All) for () matches (explained below also with \2, \3 ,...)
Any other use of backslash will be ignored unless it is used for a character used in regexps, such as * or \.
Even if you know what regular expressions are, you should still read this because only a handful of regex features are implemented. I'm using a patched relib, a slightly modified REGEXP library by Henry Spencer to handle the regular expressions.
The quick run down of supported features is the use of the following special characters:
. ? * + [ ] _ ^ ( ) | \ &
Ok, now to explain what all these are and what regular expressions are in general.
The simplest regular expression is just a string. For example, "a" would match all strings with the character a in it, "abc" would match all strings with abc in it.
Now, the first special character is a period. This is the wild card character. So "a.b" would match any string that contained an 'a' followed by any character followed by a 'b'. It would match "abb", "a1b", "ajhdakjs a b aslkjf", "a b", "extra a_b extra", and so forth.
The next special character is a ?. This means that the previous character occurs zero or one time. So "a.?b" would match everything that "a.b" matched and everything that "ab" would match.
* means that the previous character is repeated zero or more times. This is pretty much a catch all. So ".*" would match any string.
+ matches the previous character one or more times.
[]'s are used to enclose a group of characters to match. For example, "A[a-z]+Z" would match "AanczZ", "AaZ", or any set of lowercase letters enclosed by an 'A' and a 'Z'. Note that because a + is used, "AZ" would not match while "A[a-z]*Z]" would match "AZ". You can also negate what is encosed in brackets with the ^ character (so [^a-z] would mean not a lower case letter).
_ and ^ are anchor characters. _ means that the match has to occur at the end of the string and ^ means that the match has to occur and the beginning of the string. For example, "test_" would match "this is a test" but would not match "test is a this".
()'s are used to enclose a group. For example, (AB)+ would match "AB", "ABAB", "ABABAB", etc. This gives more flexibility for patterns.
The pipe | is used as an "or" operator. So "A|B" would match all strings with an upper case A or an upper case B. Combine this with parenthesis and do things like "Z(A|B)+Z" to match "ZABABABZ".
The \ is used as an escape code so you can use the special characters in your matches. For example, \* would match an asterisk, \. would match a period, and \\ would match a backslash.
And finally the & is replaced with the complete source string.
If that didn't completely confuse you, try searching for some regular expression tutorials online. Note that relib doesn't support all the neat regex stuff that perl does.
!xTextSaveEvar @$themedir$theme.rc@ @testevar@
This would replace the Line
testevar ...........
in the "theme.rc" with the current content of "$testevar$".
!xTextSaveEvar @$themedir$theme.rc@ @testevar@ @This is the NEW Evar value@
This would replace the Line
testevar ...........
in the "theme.rc" with
testevar "This is the NEW Evar value".
This whole thing is case insensitve, so you can write "testevar" how you like. Also Quotations Marks are automatically added.
Quite easy isn't it :)
For special cases you might still need to use the "complicated" way, but "normal" Evars should always work. In the other case, you can use "xTextEditConfirmation" and "xTextEditDebug" for tracking possible problems.
In the replace field, you can use a few of special characters.
For example:
& is replaced by the whole string.
!xTextReplace @file@ @find@ @&-found@
would convert @find@ to @find-found@.
Or better,
!xTextReplace @file@ @^*Shortcut@ @\~ &@
would comment all *Shortcuts definied in file (\~ is the escape code for semicolons).
Also, \1 matches with the inner-most, left-most parenthesis, \2 matches the second inner-most, left-most parenthesis, etc.
!xTextReplace @file@ @(hello)(.*)(there)@ @\3\2\1@
would convert "hello test there" to "there test hello".
Here's another example:
!xTextReplace @file@ @~; *(*Shortcut.*)@ @\1@
This would uncomment all shortcuts.
Please report bugs, if there should be any, to:
andymon@ls-universe.info
Btw.: I'm native German, so everyone who's also German mustn't write me in English ;)
Homepage: Here you find News, Updates, and some more.
http://www.ls-universe.info/