<< Click to Display Table of Contents >> Navigation:  3. Script Language > String commands > String Manipulation

---

Intention

The `GFS.` command provides a powerful and flexible mechanism to process strings by selectively keeping or removing characters. It operates based on a sequence of single-character `prototypes` that define actions like building a character set, filtering the string based on that set, or performing immediate cleanup actions. Its strength lies in chaining multiple simple operations to achieve complex string manipulations.

 

Syntax

GFS.P1|P2[|P3][|P4]

The command takes between 2 and 4 parameters separated by the pipe symbol (`|`).

Parameter Forms:

-GFS.P1|P2(2 Parameters)- P1: Prototypes to execute.- P2: Input string source (`$$VAR` or `$tos$`).- Filter Set: Starts empty.- Output: Default (in-place modification if P2 is `$$VAR`, or `$tos$` if P2 is `$tos$`).

-GFS.P1|P2|P3(3 Parameters)- P1: Prototypes.- P2: Input string source.- P3: Initial Filter Set (`$$VAR` or literal string).- Output: Default (in-place or `$tos$`).

-GFS.P1|P2|P3|P4(4 Parameters)- P1: Prototypes.- P2: Input string source.- P3: Initial Filter Set.- P4: Output destination (`$$VAR` or `$tos$`).

-GFS.P1|P2||P4(4 Parameters with Empty P3)- P1: Prototypes.- P2: Input string source.- P3: Explicitly empty (use `||`). Filter Set starts empty.- P4: Output destination.Use this form when you need to specify an output (P4) but do not want to provide an initial filter set (P3).

 

Parameters Details

 

Prototypes (Parameter P1)

Prototypes are single characters defining actions. They operate sequentially on the input string (P2) and/or an internal 'filter character set'. The order is critical.

1. Filter Set Builders (Add Characters)

These prototypes append characters to the current internal filter set. This set is then used by the Filtering Actions (`x`, `y`, `z`).

2. Filter Set Initializer (Replace Characters)

This prototype replaces the entire current filter set.

3. Filter Set Control

4. Filtering Actions (Using Filter Set)

These prototypes modify the input string based on the *current* state of the internal filter character set when they are encountered.

5. Immediate String Actions

These prototypes modify the input string directly when encountered, independent of the current filter character set.

6. Stack Operations

These allow interaction with the SPR-Script stack (TOS - Top Of Stack).

7. Special Option: Binary Variable Resolution

Prototype 'a'

-Action: Use 'binary' variable resolution for the Input (P2) if P2 is a variable (`$$VAR`).

-Purpose: Prevents the `GFS.` command from further interpreting the content of the input variable P2. Normally, if `$$SRC` contained text like `$DATE$`, SPR-Script might expand `$DATE$` before `GFS.` processes the string. Using prototype `a` ensures `GFS.` operates on the literal content of `$$SRC` (e.g., the string "Filename is $DATE$.log") without expanding system variables or nested `$$VAR` variables within it.

-When to use: Use this typically only if your input variable (P2) contains text that *looks like* a system variable or another `$$VAR`, but you need `GFS.` to treat that text literally during filtering.

' Example (Conceptual)

VAR.$$SRC=Value is $$VAL ' $$SRC contains literal "$$VAL"

VAR.$$VAL=123

VAR.$$TMP=

' Using 'a': Process the literal content of $$SRC

' a: Use binary resolution for P2 ($$SRC)

' s: Add lowercase letters 'a-z' to filter set

' z: Keep only chars in filter set (only letters)

GFS.asz|$$SRC||$$TMP ' Use P4 for output to preserve $$SRC

PRT.Original SRC: $$SRC ' Prints "Value is $$VAL"

PRT.Filtered TMP: $$TMP ' Prints "alues" (keeps letters from literal "$$VAL")

' Without 'a': Expansion might happen first (depends on engine details)

' GFS.sz|$$SRC||$$TMP ' Might process "Value is 123" -> "alues"

' The 'a' ensures consistent handling of literal variable content.

ENR.

 

Execution Flow and Order Dependency

CRITICAL: Prototypes in P1 are executed strictly in the order they appear, from left to right. This sequential processing is fundamental to how `GFS.` works.

1. The input string is taken from P2 (`$$VAR` or `$tos$`).

2. The internal filter character set is initialized (either empty or from P3).

3. Each prototype in P1 is processed in sequence:

-Filter Set Builders/Initializer/Control (`b, c, d, e, f, g, h, i, j, k, l, m, n, s, t, u`) modify the internal filter set.

-Filtering Actions (`x, y, z`) use the filter set *as it exists at that exact moment* to modify the input string.

-Immediate Actions (`o, p, v, w`) modify the input string directly, regardless of the filter set state.

-Stack Operations (`q, r`) push the current state of the filter set or input string to TOS.

4. After all prototypes in P1 are processed, the final modified string is placed in the output destination (P4, in-place P2, or `$tos$`).

Consequence: You MUST build the filter set (e.g., using `d`, `s`, `c`, or P3) *before* applying a filter action (`x`, `y`, `z`) that relies on it.

' CORRECT: Build set (d), then filter (z)

VAR.$$SRC=ABC123DEF

GFS.dz|$$SRC

PRT.$$SRC ' Output: "123"

' INCORRECT: Filter (z) with empty set, then build (d)

VAR.$$SRC=ABC123DEF

GFS.zd|$$SRC

PRT.$$SRC ' Output: "" (empty string - z used an empty filter)

 

Comprehensive Examples

Example 1: Keep Only Digits (Basic)

' Goal: Extract numbers from a string

VAR.$$SRC="Order ID: 987-XYZ-654"

' d: Add digits '0'-'9' to filter set

' z: Keep only characters found in the filter set

GFS.dz|$$SRC ' Output to $$SRC (in-place)

PRT.Digits: $$SRC

' Output: Digits: 987654

ENR.

Example 2: Remove Punctuation (Using P4 for Output)

' Goal: Clean up text by removing common punctuation

VAR.$$TXT="Hello, world! How are you?"

' j: Add punctuation '!?.,;-()' to filter set

' y: Remove any characters found in the filter set

GFS.jy|$$TXT|$$RES ' Input $$TXT, Output to $$RES (P4)

PRT.Original: $$TXT

PRT.Cleaned: $$RES

' Output:

' Original: Hello, world! How are you?

' Cleaned: Hello world How are you

ENR.

Example 3: Input/Output via Stack ($tos$)

' Goal: Keep only Hex characters from string on stack

VAR.$$SRC="Value is 0xFF but not 0xGG"

PUV.$$SRC ' Push source string onto stack

' h: Add hex chars 'a-fA-F0-9' to filter set

' z: Keep only chars in filter set

' Input P2 is $tos$, Output P4 is omitted -> defaults to $tos$

GFS.hz|$tos$

' Result is now on the stack

PRT.Hex Chars: $tos$

' Output: Hex Chars: aeFFaeF09

ENR.

Example 4: Using Initial Filter Set (P3 Literal)

' Goal: Remove specific custom characters AND digits

VAR.$$SRC="Data [123] ~ Remove these ~ (456)"

' P3 ("[]~()") initializes the filter set

' d: Add digits '0'-'9' to the filter set -> "[]~()0123456789"

' y: Remove any char found in the combined filter set

GFS.dy|$$SRC|"[]~()"|$$RES ' Use literal for P3

PRT.Result: $$RES

' Output: Result: Data Remove these 

ENR.

Example 5: Using Stack for Filter Chars (Prototype 'c')

' Goal: Remove vowels from a string

VAR.$$SRC="This Is An Example String"

VAR.$$VOW="aeiouAEIOU" ' Vowels to remove

PUV.$$VOW ' Push vowels onto stack BEFORE GFS call

' c: Add string from TOS ($$VOW) to filter set

' y: Remove characters in the filter set

GFS.cy|$$SRC

PRT.No Vowels: $$SRC

' Output: No Vowels: Ths s n Exmpl Strng

ENR.

Example 6: Combining Immediate Actions and Filter Actions

' Goal: Clean web data - remove control chars, fix spaces, keep only letters/numbers

VAR.$$SRC=" Product: Widget$xA0;100\r\nCode:\tABC-123 "

' o: Immediately remove control chars (\r, \n, \t -> ASCII 13, 10, 9)

' p: Immediately replace non-breaking space (ASCII 160) with space (32)

' k: Add letters 'a-zA-Z' to filter set

' d: Add digits '0-9' to filter set

' z: Keep only characters from the filter set (letters and digits)

GFS.opkdz|$$SRC

PRT.Cleaned: $$SRC

' Output: Cleaned: ProductWidget100CodeABC123

' Note: Spaces and hyphen removed by 'z' because not added by k or d.

ENR.

Example 7: Using 'u' to Clear Filter Set Mid-Process

' Goal: Remove letters, then keep only digits

VAR.$$SRC="Part: ABC-123 / Section: 456"

' k: Add letters 'a-zA-Z' to filter set

' y: Remove letters from the string -> "Part: --123 / Section: 456"

' u: Clear the filter set. It's now empty.

' d: Add digits '0-9' to the filter set. Set is now "0123456789".

' z: Keep only digits from the modified string.

GFS.kyudz|$$SRC

PRT.Result: $$SRC

' Output: Result: 123456

ENR.

Example 8: Creating a Valid Filename (Using 'm' and 'z')

' Goal: Convert an arbitrary string to a safe filename

VAR.$$SRC="My Document / Chapter 2: \"The End\"?.txt"

' m: Add valid filename characters to filter set (excludes \, :, etc.)

' z: Keep only characters in the filter set

GFS.mz|$$SRC

PRT.Filename: $$SRC

' Output: Filename: My Document Chapter 2 The End.txt

' Note: Still contains spaces. Use 'w' for more aggressive cleaning.

ENR.

Example 9: Advanced Filename Cleaning (Using 'w')

' Goal: Aggressively clean a string for use as a filename

VAR.$$SRC=" My Document / Chapter 2: \"The End\"?\r\n.txt "

' w: Apply specialized filename filter (removes invalid chars, CR/LF, trims, etc.)

GFS.w|$$SRC

PRT.Filename: $$SRC

' Output: Filename: My Document Chapter 2 The End.txt

ENR.

Example 10: Using 'q' and 'r' for Debugging

' Goal: Inspect filter set and string state during processing

VAR.$$SRC=A1 B2 C3

' d: add digits; q: push filter set; y: remove digits; r: push string state

GFS.dqyr|$$SRC

' Stack now contains (from top): "A B C ", "0123456789"

PRT.String State After Y: $tos$

PRT.Filter Set Before Y: $tos$

' Output:

' String State After Y: A B C 

' Filter Set Before Y: 0123456789

ENR.

Example 11: Output to P4 without Initial Filter (Empty P3)

' Goal: Keep only digits, output to $$RES, no initial filter

VAR.$$SRC="Value: 123"

' d: Add digits to filter set (starts empty)

' z: Keep only digits

' P3 is empty (||), P4 is $$RES

GFS.dz|$$SRC||$$RES

PRT.Original: $$SRC

PRT.Result: $$RES

' Output:

' Original: Value: 123

' Result: 123

ENR.

Example 12: Difference between 'x', 'y', 'z'

VAR.$$SRC=--ABC--ABC--

VAR.$$FLT=ABC

' Using x: Remove exact match "ABC"

VAR.$$TMP=$$SRC

GFS.x|$$TMP|$$FLT

PRT.Result 'x': $$TMP ' Output: Result 'x': ----ABC--

' Using y: Remove ANY of 'A', 'B', 'C'

VAR.$$TMP=$$SRC

GFS.y|$$TMP|$$FLT

PRT.Result 'y': $$TMP ' Output: Result 'y': ------

' Using z: Keep ONLY 'A', 'B', 'C'

VAR.$$TMP=$$SRC

GFS.z|$$TMP|$$FLT

PRT.Result 'z': $$TMP ' Output: Result 'z': ABCABC

ENR.

Remarks

·The order of prototypes in P1 is the most critical aspect of using `GFS.`. Plan the sequence carefully: build the set, then apply actions.

·Remember the difference between Filter Actions (`x, y, z` which use the set) and Immediate Actions (`o, p, v, w` which don't).

·Use `u` (clear filter) strategically if you need to perform multiple, distinct filtering operations within a single `GFS.` command.

·For simple replacements, `RPL.` might be more straightforward. `GFS.` excels at complex, multi-step filtering based on character sets.

·When using the `c` prototype, ensure the filter string is pushed onto the stack (`PUV.`) *before* the `GFS.` command.

·The `a` prototype is mainly for edge cases where input variable content might be misinterpreted as system or nested variables.

·Prototypes `v` and `w` are convenient shortcuts for common path/filename cleaning but offer less control than building the steps manually (e.g., using `o`, `p`, `m`, `n`, `z`, and maybe `VBT.`).

·Always ensure variable names used (e.g., `$$SRC`, `$$RES`) conform to the `$$` + 3 characters rule.

·End scripts with `ENR.` or `END.` as appropriate.

 

See also:

•  GPS. - Keep only given characters

•  GNS. - Filter out given characters

•  STR.Retain Any

•  STR.Remain Any

•  RPL. - Replace in String

•  STR. - String Operations

•  LEN. - String Length

•  VBT. - Variable Both Sides Trim

•  Variable Commands (VAR., VAB., etc.)

•  Stack Operations (PUV., $tos$)