EF.Macros

This unit defines classes and routines to help with macro-expansion in strings. The macro-expansion engine can be extended by defining and registering custom expander classes.

TEFMacroExpander class

Abstract macro expander class. Descendants are able to expand a certain set of macros in a given string. This class is used with TEFMacroExpansionEngine but it can be used on its own as well.

constructor Create;

Creates the expander. Descendants may override to perform initialization.

procedure Expand(var AString: string);

Expands all supported macros found in a given string, and returns the string with macros expanded. Calls the virtual protected method InternalExpand to do the job.

TEFMacroExpansionEngine class

The engine is able to expand an open-ended set of macros in a given string. Use AddExpander calls to add support for more macros, and call Expand to trigger macro expansion. Alternatively, you can use a ready-made singleton engine which supports all registered expanders out-of-the-box. Macro expansion engines can be chained: each engine calls the previous engine in the chain, if available, when invoked.

constructor Create(const APrevious: TEFMacroExpansionEngine = nil);

Creates the engine, optionally chained to a previous engine that is invoked before this one's expanders.

destructor Destroy;

Clears and frees all owned expanders.

procedure Expand(var AString: string);

Expands all recognized macros in AString and returns the resulting string. The result depends on the set of macro expanders used. Add a new macro expander by calling AddExpander before calling Expand. If no macro expanders are used, the result is the same as the input string.

procedure AddExpander(const AExpander: TEFMacroExpander);

Adds an expander to the list used by the Expand method. Acquires ownership of AExpander, which means it will be destroyed when RemoveExpanders or ClearExpanders are called, or when the current object is itself destroyed.

function RemoveExpander(const AExpander: TEFMacroExpander): Boolean;

Removes a previously added expander from the list used by the Expand method. Returns True if the specified object was found and removed, and False otherwise.

The removed object is NOT freed automatically.

function IndexOfExpander(const AExpander: TEFMacroExpander): Integer;

Returns the index of a given expander in the list, or -1 if it is not found. Use this method to check whether an expander is part of an expansion engine.

procedure RemoveExpanders(const AExpanderClass: TEFMacroExpanderClass);

Removes from the list and frees all expanders of the given class.

procedure ClearExpanders;

Removes all expanders from the list and destroys them.

property OnGetFormatSettings: TFunc<TFormatSettings> read FOnGetFormatSettings write FOnGetFormatSettings;

Function that returns settings for format-sensitive macros such as %DATE%. If not specified, global FormatSettings variable is used.

class procedure DisableForCurrentThread;

Disables macro expansion (meaning that strings are returned untouched) for the current thread. Calls can be nested. Each call to Disable must be matched by a call to Enable in the same thread.

class procedure EnableForCurrentThread;

Re-enables macro expansion for the current thread after a call to Disable. Calls can be nested. Each call to Disable must be matched by a call to Enable in the same thread.

TEFPathMacroExpander class

A macro expander that can expand some path-related macros.

Supported macros (case sensitive):

• %APP_PATH% ExtractFilePath(ParamStr(0))
• %APP_NAME% ParamStr(0)
• %APP_FILENAME% ExtractFileName(ParamStr(0))
• %APP_BASENAME%

RemoveFileExt(ExtractFileName(ParamStr(0)))

• %WIN_DIR% GetWindowsDirectory (including final backslash)
• %SYS_DIR% GetSystemDirectory (including final backslash)

TEFSysMacroExpander class

A macro expander that can expand some system macros.

Supported macros (case sensitive):

• %DATE% DateToStr(Date)
• %YESTERDAY% DateToStr(Date - 1)
• %TOMORROW% DateToStr(Date + 1)
• %TIME% TimeToStr(Now)
• %DATETIME% DateTimeToStr(Now)
• %PROCESS_ID% An integer value that is the current process' Id
• %THREAD_ID% An integer value that is the current thread's Id

TEFEnvironmentVariableMacroExpander class

A macro expander that expands all environment variables. See EF.Sys.ExpandEnvironmentVariables for details on format and case sensitivity.

EF.Sys.ExpandEnvironmentVariables

%COMPUTERNAME% expands to the current computer's name.

TEFCmdLineParamMacroExpander class

Expands named parameters passed on the command line. A named command line parameter is prefixed with / or - characters, it has a name, a space and a value.

EF.Sys.GetCmdLineParamValue

<para>Given the following command line:</para>
<para><c>app.exe /p1 value -p2 value2</c></para>
<para>the sequence '%Cmd:p1%' expands to 'value'.</para>

TEFDateTimeStrMacroExpander class

Expands the current date and/or time formatted in several ways.

Supported macros (case sensitive):

• %YYYYMMDD_DATE% The current date (Date) in YYYYMMDD format
• %YYYYMMDD_YESTERDAY% Date - 1 day in YYYYMMDD format
• %YYYYMMDD_TOMORROW% Date + 1 day in YYYYMMDD format
• %YYMMDD_DATE% Date in YYMMDD format
• %YYMMDD_YESTERDAY% Date - 1 day in YYMMDD format
• %YYMMDD_TOMORROW% Date + 1 day in YYMMDD format
• %MMDD_DATE% The current date in MMDD format
• %DD_DATE% The current day of the month
• %MM_DATE% The current month of the year
• %YYYY_DATE% The current year
• %WEEKDAYNAME_SHORT% The short name of the current day of the week
• %WEEKDAYNAME_LONG% The name of the current day of the week
• %WEEKDAYNR% The number of the current day of the week (1 = sunday)
• %ISOWEEKDAYNR% The number of the current day of the week (1 = monday)
• %HHMMSS_TIME% The current time in HHMMSS format
• %HHMM_TIME% The current time in HHMM format
• %HH_TIME% The current hour
• %MM_TIME% The current minute
• %SS_TIME% The current second

TEFGUIDMacroExpander class

A macro expander that generates GUIDs.

Supported macros (case sensitive):

• %GUID% CreateGuidStr()
• %COMPACT_GUID% CreateCompactGuidStr()

CreateGuidStrCreateCompactGuidStr

TEFEntityMacroExpander class

A macro expander that expands symbols to characters.

Supported macros (case sensitive):

• %TAB% The Tab (#9) character
• %SPACE% The space character

CreateGuidStrCreateCompactGuidStr

TEFParameterizedMacroExpanderBase class

A base class for macro expanders that support parameterized macros, in the form %NAME([param1[,param2[,...]])%.

TEFFileMacroExpander class

The %FILE()% macro expands to the contents of a specified (text) file.

The macro format is as follows:

• (%FILE(<filename>[,<param1>[...]]))% The contents of <filename>. If <filename> is not a fully qualified filename, then the value of the DefaultPath property of the expander is pre-prended to it before trying to load it. If parameters are passed after the file name, then they are used to substitute parameter placeholders in the file contents. Placeholders are in the form %%P1%%, %%P2%% and so on.

Any macros in the file name or contents are expanded as well.

If a parameter (or the file name) includes a space or a comma, the entire parameter should be enclosed in ". Space and comma are both valid parameter separators. If a parameter includes the " character, then the character should be doubled (as well as the entire parameter be enclosed between " characters).

If the file name is not specified or the file doesn't exist, then the macro expands to ''. If a parameter doesn't exist, it expands to ''.

property DefaultPath: string read FDefaultPath write FDefaultPath;

The value of this property is pre-pended to any relative file name before loading the file contents as part of the expansion process. Leave this property empty to have the expander use the current directory as default path instead.

TEFFileNameToUrlMacroExpander class

The %FILENAME_TO_URL()% macro converts the server filename as an url file name.

Routines

procedure AddStandardMacroExpanders(const AMacroExpansionEngine: TEFMacroExpansionEngine);

Creates and adds instances of all standard macro expanders to the specified macro expansion engine, which acquires ownership of them.