Language Reference ‐ Text Replacer Library

Language Reference ‐ Text Replacer Library

The Text Replacer Library provides powerful functionality for substituting placeholders within strings, enabling flexible template processing and dynamic text generation in FAST.FBasic programs. This library is ideal for scenarios requiring variable text expansion, conditional subroutines, and word frequency analysis.

Text Replacer Library — Introduction and Purpose

The Text Replacer Library in FAST.FBasic provides a versatile and powerful toolkit for dynamic text manipulation through placeholder substitution. It is designed to automate and simplify the process of replacing designated placeholders within strings or templates with actual values or computed results, enabling flexible and data-driven generation of textual content.

Purpose

This library caters to developers and domain experts who need to build applications involving:

• Template Processing: Automatically replacing placeholders in text templates with variables, formatted values, or results from subroutines.
• Dynamic Content Generation: Creating personalized or variable-rich output documents, reports, and messages with minimal manual editing.
• Conditional Logic Embedded in Text: Allowing placeholder-driven branching (such as PHGOSUB) where program flow dynamically depends on placeholder values.
• Text Analytics Support: Analyzing word frequency and detailed content within strings for insights or to inform further processing steps.
• Flexible Data Collection: Automatic extraction and management of data collections and arrays tied to placeholders found in the input text.

Key Advantages

• Seamless Placeholder Substitution: The library efficiently scans input text for placeholders and substitutes them with corresponding values, making it ideal for document generation, code templating, or reporting.
• Rich Control Flow: Through the PHGOSUB statement, placeholder values can direct program execution to different labeled subroutines with fallback handling via an optional ELSE label, enriching flexibility in templates.
• Powerful Data Management: Users can create collections (PHSDATA) and arrays (PHVSDATA) on-the-fly based on textual input analysis, allowing complex template-driven logic and iteration.
• Text Metrics and Case Tools: Functions such as words, pcase, and phtoname provide essential utilities to analyze text structure, format words, and parse placeholder syntax efficiently.
• Integration Ready: This library fits into larger FBasic-based systems where template-based input-output interactions, report customization, and content personalization are core requirements.

Typical Use Cases

• Generating dynamic reports or documents based on customer data, inventory lists, or real-time analytics.
• Automating communication templates such as email messages, invoices, or notifications with variable placeholders.
• Parsing and processing complex text templates where different processing paths depend on input content.
• Performing word frequency analysis for content optimization or keyword extraction directly within scripts.

Text Replacer Statements

Placeholder Replacer implements the low level functionality is necessary to substitute placeholders in a string with value of identifiers (variables or collections). It is provided by the Library FBasicTextReplacer

Available statements are:

Statement	Description
PHGOSUB variable [ELSE label]	variable contains as value a label to GOSUB to, if the label does not exists, then the flow will GOSUB to the ELSE label.
PHREPLACE intext outtext	Perform a text replace to the intext giving the replaced text to the outtext.
PHSDATA colName intext	Create a SDATA type of collection with name colName with the collection names found in the intext.
PHVSDATA colName intext	Similar to PHSDATA but it is collection all the identifiers are used.
words(s,1)	Function, counts the number of words in a string s that are at least 1 character long. if the input string is empty returns 0, if the minWordSize is less than 1 it is set to 1. The word delimiters are space, tab, newline and carriage-return. Consequent delimiters are treated as one.

PHGOSUB

Performs a GOSUB to a label specified by the value of a variable.

PHGOSUB variable [ELSE label]

• variable: Contains the label name to GOSUB to.
• ELSE label (optional): If the label from the variable does not exist, the program GOSUBs to this ELSE label instead.
  This enables conditional branching based on placeholder values.

PHREPLACE

Executes the text replacement on a string, substituting placeholders in intext and placing the result in outtext.

PHREPLACE intext outtext

PHSDATA

Creates an SDATA type collection with name colName. The collection is populated with the collection names found in the given input text.

PHSDATA colName intext

This allows dynamic collection creation based on placeholders in templates.

PHVSDATA

Creates an array named array with two columns: name and ph (placeholder).

PHVSDATA array intext

• name: The variable used in the placeholder.
• ph: The placeholder as it appears in the text.

WORDFREQ

Analyzes word frequency in a given input text based on parameters and stores results in an array.

WORDFREQ array_name, input_text, min_word_length, min_count_to_result

• array_name: The output array receiving word-frequency pairs.
• input_text: Text to analyze.
• min_word_length: Minimum word length to count.
• min_count_to_result: Minimum occurrences for words to be included.

---

Text Replacer Functions

pcase(string)

Returns the input string converted to Proper Case: first letter uppercase, rest lowercase.
Example:

pcase("text") -> "Text"

singlewhite(string)

Remove all duplicate characters are white spaces (such as space,tab, newline etc). A typical usage is to shorten a string when the lines and spaces are not necessary (for example prompts to AI). White space is any character that used as spacer or line changer. This explicitly includes: Space, Tab, New-line, Carriage return, Form feed and Vertical tab. Returns the input string after removing all the doublicates.

Example:

print len(singlewhite(outtext))+" characters signle white spaces."

words(s, minWordSize)

Counts the number of words in string s that are at least minWordSize characters long.

• If the string is empty, returns 0.
• If minWordSize is less than 1, it defaults to 1.
• Word delimiters are space, tab, newline, and carriage return.
• Consecutive delimiters are treated as one.

Example:

words("hello world", 1) -> 2
words("a quick fox", 2) -> 2  (words >= 2 chars: "quick" and "fox")

phtoname(s)

Extracts the variable name from a placeholder string s. Supports simple and square bracket notation.

Example:

• {name} → "name"
• {[employeeId]} → "employeeId"

---

Example Usage

REM Testing the Text Replacer library
REM Library: FBasicTextReplacer
REM Category: Text Replacer Library

let n1=1234543.1234
let s1="abCD12345fghijk"
sdata Days "Sat","Mon","Thu","The","Wes","Fri","Sat"

let intext=">>>
Day : {Days.Item}
n1,15-25,R0N: {n1:15,25,r0N}
n1,0-25,N: {n1:0,25,N}  ({n1})
s1,3-5,P: {s1:3,5,P}
"

Print "Collections used in the template:"

Print "Setup Collections:"
PHSDATA cnames intext

foreach cnames
   print "Setting up...."+[cnames.ph]
   phgosub [cnames.ph] else notfound
   print "after phgosub"
endforeach cnames

print ""
print "The output is:"

PHREPLACE intext outtext
print outtext
print words(outtext,1)+" Words in total"
print words(outtext,2)+" Words > than 2 characters in length"
print words(outtext,4)+" Words > than 4 characters in length"

print len(outtext)+" Characters in length ";
print len(singlewhite(outtext))+" characters signle white spaces."

halt

rem
rem ...............SETUP COLLECTIONS...................
rem
Days:
print "Preparing Days"
reset Days
fetch Days
print "....done"
return

notfound:
print "***NOT FOUND***"
return

---

Remarks

• The PHGOSUB statement allows dynamic control flow based on placeholder content, enhancing template customization by executing specific subroutines.
• PHREPLACE is the core engine to perform the substitution and generate final output text.
• Collection creation via PHSDATA and PHVSDATA supports advanced placeholder data management.
• WORDFREQ provides a powerful frequency analysis tool to inspect text and filter words by length and count.
• Utility functions like pcase, words, and phtoname support common text handling tasks needed for complex template processing.

This library is essential for programs requiring dynamic text generation, template-based output, or detailed content analysis in FAST.FBasic.

Placeholders — Definition and Format Specifiers

What is a Placeholder?

A placeholder is a special text token used within strings to mark where a variable's value should be substituted dynamically at runtime. Placeholders enable flexible template and text generation by allowing variables or expressions in the program to be directly injected into strings.

In FAST.FBasic, placeholders are always enclosed within curly braces { and } to denote them clearly. For example:

{name}

Here, name is the variable whose value will replace the placeholder in the processed text.

---

Syntax with Format Specifiers

Placeholders can also include format specifiers and modifiers to control how the substituted value is presented. The general syntax for a placeholder with format specifiers is:

{name:specifier}

Where:

• name is the variable name.
• specifier is an optional string defining formatting rules and modifiers.

Example:

{customerName:10,20,U0}

---

Format Specifier Syntax and Modifiers

The format specifier string consists of optional parameters separated by commas. These modifiers control the appearance, alignment, and type formatting of the substituted value.

Modifier	Description	Example Use	Input value	Output
min,max	Minimum and maximum width of the substituted value.	{name:10,20}	Earl Alexander Frederick	Earl Alexander Frede
U	Convert entire output to uppercase.	{name:U}	Alexandra	ALEXANDRA
L	Convert entire output to lowercase.	{name:L}	ALEXANDRA	alexandra
P	Proper (title) case: first letter uppercase, rest lowercase.	{name:P}	george	George
T	Trim spaces from both ends of the substituted value.	{name:T}	ABCD	ABCD
c	Format a numeric value as currency using current thread culture.	{amount:c}	134123.4	134.123,40
N	Format numeric value with thousand separator and decimal point.	{number:N}	134123.4	134,123.40
0	Use '0' as left padding character instead of space.	{name:10,20,0}	2134.4	0000002134.4
D	Change the native date format YYYY-MM-DD to european style DD-MM-YYYY	{today:D}	2025-11-30	30-11-2025
r	Alignment specifier – right alignment if single ‘r’.	{name:5,10,r}	ABC	ABC
l	Alignment specifier – left alignment.	{name:10,20,l}	ABC	ABC
lr	Alignment specifier – center alignment (both left and right).	{name:10,20,lr}	ABC	ABC

---

Summary

Using placeholders with format specifiers in FAST.FBasic allows fine control over:

• Width constraints on the output (minimum and maximum length).
• Upper, lower, or proper casing of output.
• Trimming unwanted spaces.
• Formatting numbers as currency or with thousand separators.
• Controlling padding characters.
• Controlling text alignment within fixed-width fields.

This flexible syntax provides robust capabilities to tailor output formatting directly within template strings, allowing programmers to generate clean, readable, and consistent text based on dynamic data.

Example Placeholder Specifier Order

The correct order for format specifiers inside a placeholder {name:...} is:

{name:min,max,commandModifiers}

• min and max are numeric width values.
• After the width values and comma, a sequence of single command letters follows.
• Then zero or more modifier letters appear immediately afterward without separators.

Example:

{name:10,20,rU0}

• 10 minimum width, 20 maximum width.
• r is the command letter (right alignment).
• U modifier: convert to uppercase.
• 0 modifier: use zero padding instead of space.

Additional examples illustrating combined commands and modifiers:

Placeholder	Description
{name:5,15,lPT}	Width 5-15, left aligned (l), proper case (P), trim spaces (T).
{amount:12,18,cNr}	Width 12-18, currency format (c), numeric with thousands (N), right aligned (r).
{customer:8,25,lrU}	Width 8-25, center aligned (lr), uppercase (U).

---