xTextEdit v0.5

Overview

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.

This is basically the same as TextEdit Emulation in xLabel or TextEdit-2.52, with some additions, which should make it easier to do a simple Replace of Evars.

• 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 ;)

• !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 "$"!

Escape Codes

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 \.

Regular Expressions

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. Read the included relib-readme.txt for more details.

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.

TextReplace Examples

How to Use the "New" Bang !xTextSaveEvar :

!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 "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.

A couple of notes about TextReplace:
In the replace field, you can use a few of special characters.

For example, & is replaced by the whole string.
So
!xTextReplace @file@ @find@ @&-found@ would convert @find@ to @find-found@.

Or better yet,
!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.
So
!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.

0.5 Released on 13-04-2005, Changes by Andymon

- Added:
!xTextInsertAfter

- Added:
!xTextInsertBefore

- Added:
!xTextDeleteAll

- Changed:
!xTextDelete
Only the first matching line will be deleted!

0.3 Released on 25-11-2004, Changes by Andymon

- Fixed:
!xTextReplaceAll hadn't inserted the ReplaceText.
(Sorry Dac, it seems you're the only one who find bugs ;) )

0.2 Released on 06-11-2004, Changes by Andymon

- Fixed:
!xTextAppend hadn't used Escape Sequences in the appended Text
(Sorry Dac, i always used !xTextReplace, there it works ;) )

- Fixed:
!xTextSaveEvar can now use Escape Sequences in the Optional Saving Value.

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.
www.LS-Universe.info