xbn.config
Class CRCVTrim

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.config.CRCVTrim

public class CRCVTrim

extends XBNObject

Configure if the names and value lines of variables should have tabs and spaces trimmed from the ends. Provided to ConfigReader via CRConfig, via CRCVariable.

Source code: CRCVTrim.java

Assuming this CRCVTrim is created with this constructor...

new CRCVTrim(true, '|')

This activates everything: Trimming the name, trimming value lines, and using the special empty space character '|'. To deactivate anything, create this class with different constructor parameters.

...then this is how trimming affects your variable's name:

Step one: [VARIABLE NAME as a String].trim()

The first step is to eliminate all tabs and spaces from the ends.

Step two: (new TrimChars(new char[] {this.getESChar()}).get([VARIABLE NAME])

This step eliminates the special empty-string character from the ends of the name/every line within the value.

...and how it affects the value:

Step one: [VARIABLE VALUE as a String].trim()

The first step is to eliminate all whitespace from the ends of the value, as a whole (remember values can span multiple lines). This eliminates all whitespace-only lines from the start and end, plus any tabs and spaces existing on the beginning of the first (non-whitespace) line, and the end of the last.

Step two: (new TrimChars()).getAllLines([VARIABLE VALUE])

This eliminates tabs and spaces from the ends of every line in the value.

Step three: (new TrimChars(new char[] {this.getESChar()}).getAllLines([VARIABLE VALUE])

This step eliminates the special empty-string character from the ends of every line within the value.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

CRCVTrim()
Create a CRCVTrim with default settings.

CRCVTrim(boolean b_trim)
Create a CRCVTrim.

CRCVTrim(boolean b_trimName, boolean b_trimVLs)
Create a CRCVTrim.

CRCVTrim(boolean b_trimName, boolean b_trimVLs, boolean b_useESChar)
Create a CRCVTrim.

CRCVTrim(boolean b_trimName, boolean b_trimVLs, boolean b_useESChar, char c_emptyString)
Create a CRCVTrim.

CRCVTrim(boolean b_trimName, boolean b_trimVLs, char c_emptyString)
Create a CRCVTrim.

CRCVTrim(boolean b_trim, char c_emptyString)
Create a CRCVTrim.

CRCVTrim(char c_emptyString)
Create a CRCVTrim.

Method Summary

boolean	doTrimName() Should name of a configuration variable be trimmed?
boolean	doTrimVLs() Should every line in the value of a configuration variable be trimmed?
boolean	doUseESChar() Should the special empty-string character be used?
char	getESChar() Get the special empty string character.
String	toString() Get some information about this CRCVTrim.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CRCVTrim

public CRCVTrim()

Create a CRCVTrim with default settings.

Equal to CRCVTrim(true)

CRCVTrim

public CRCVTrim(boolean b_trim)

Create a CRCVTrim.

Equal to CRCVTrim(b_trim, b_trim)

CRCVTrim

public CRCVTrim(boolean b_trimName,
                boolean b_trimVLs)

Create a CRCVTrim.

Equal to CRCVTrim(b_trimName, b_trimVLs, '|')

CRCVTrim

public CRCVTrim(char c_emptyString)

Create a CRCVTrim.

Equal to CRCVTrim(true, c_emptyString)

CRCVTrim

public CRCVTrim(boolean b_trim,
                char c_emptyString)

Create a CRCVTrim.

Equal to CRCVTrim(b_trim, b_trim, c_emptyString)

CRCVTrim

public CRCVTrim(boolean b_trimName,
                boolean b_trimVLs,
                char c_emptyString)

Create a CRCVTrim.

Equal to CRCVTrim(b_trimName, b_trimVLs, true, c_emptyString)

CRCVTrim

public CRCVTrim(boolean b_trimName,
                boolean b_trimVLs,
                boolean b_useESChar)

Create a CRCVTrim.

Equal to CRCVTrim(b_trimName, b_trimVLs, b_useESChar, '|')

CRCVTrim

public CRCVTrim(boolean b_trimName,
                boolean b_trimVLs,
                boolean b_useESChar,
                char c_emptyString)

Create a CRCVTrim.

This object, as a whole, is provided directly to the CRCVariable constructor.

Parameters:

b_trimName - Do you want the name of configuration variables to be trimmed? See doTrimName.

b_trimVLs - Do you want every line in the value of configuration variables to be trimmed? See doTrimVLs.

b_useESChar - Should the special empty-string character (c_emptyString)? When both b_trimName and b_trimVLs are false, this parameter is ignored.

c_emptyString - Which character should represent the empty string? If b_useESChar is false, this parameter is ignored.

Method Detail

doTrimName

public final boolean doTrimName()

Should name of a configuration variable be trimmed?

Returns:

b_trimName Exactly as provided to the constructor.

doTrimVLs

public final boolean doTrimVLs()

Should every line in the value of a configuration variable be trimmed?

Returns:

b_trimVLs Exactly as provided to the constructor.

doUseESChar

public final boolean doUseESChar()

Should the special empty-string character be used?

If this returns true, then when an non-escaped empty-string character is the first or last character in the line, then it is used to surround any characters that would normally be trimmed (tabs and spaces are normally trimmed), but should not be. It is also used to represent an empty string in the last line of a value, which also would normally be trimmed away.

When this returns false, then no empty-string character is used.

After trimming, these special empty string characters are eliminated. Note that they may only exist as the first or last character in a variable's name or value. It may also be the only character within any line in a variable's value.

Returns:

b_useESChar Exactly as provided to the constructor.

getESChar

public final char getESChar()

Get the special empty string character.

This is only used when doUseESChar equals true.

The purpose

The special empty string character allows you to specify exactly what whitespace should and should not exist at the ends of the name and value (the value as a whole, and within each line).

In the name, the special empty string character (assume the default value: '|') can exist as the first and/or last non-whitespace character in the name. For example:

| name_of_my_variable = Here is the value

The resulting name equals " name_of_my_variable".

In the value, the special empty string character can exist as the first and/or last non-whitespace character overall, and the first and/or last character in each line. For example:

name_of_my_variable= Here
is
the

multiple-line |

| value
| |

Literal special empty-string character: \|

|

The resulting value equals:

Here
is
the

multiple-line

value


Literal special empty-string character: |



And again, where each line is surrounded by "[" and "]" to highlight tabs and spaces:

name_of_my_variable=[ Here]
[ is]
[ the]
[]
[ multiple-line |]
[]
[ | value]
[ | |]
[ ]
[ Literal special empty-string character: \|]
[ ]
[ |]

The resulting value equals:

[Here]
[is]
[the]
[]
[multiple-line ]
[]
[ value]
[ ]
[]
[Literal special empty-string character: |]
[]
[]

Why?

My favorite text editor, TextPad, is configured to trim all ending/right-side whitespace (tabs and spaces) every time I save a document. This causes frustration when you need whitespace to be preserved on the right-hand side.

Tabs and spaces existing on the left-side of text is never eliminated (or indentation would be pointless!). However, the special empty-string character is still useful on the left when you don't want to be forced to hug it against the left-margin. Depending on your taste, you want to indent values to make the config file look less "busy"...

Actually, the idea of the special empty-string character came to me first, and then led to the concept of trimming.

Returns:

c_emptyString Exactly as provided to the constructor.

toString

public String toString()

Get some information about this CRCVTrim.

Overrides:

toString in class Object