KMacroExpanderBase

#include <KMacroExpanderBase>

Inheritance diagram for KMacroExpanderBase:

Public Member Functions

 KMacroExpanderBase (QChar c=QLatin1Char('%'))
 
virtual ~KMacroExpanderBase ()
 
QChar escapeChar () const
 
void expandMacros (QString &str)
 
bool expandMacrosShellQuote (QString &str, int &pos)
 
bool expandMacrosShellQuote (QString &str)
 
void setEscapeChar (QChar c)
 

Protected Member Functions

virtual int expandEscapedMacro (const QString &str, int pos, QStringList &ret)
 
virtual int expandPlainMacro (const QString &str, int pos, QStringList &ret)
 

Detailed Description

Abstract base class for the worker classes behind the KMacroExpander namespace and the KCharMacroExpander and KWordMacroExpander classes.

Author
Oswald Buddenhagen [email protected][email protected]kde.[email protected]org

Definition at line 28 of file kmacroexpander.h.

Constructor & Destructor Documentation

KMacroExpanderBase::KMacroExpanderBase ( QChar  c = QLatin1Char('%'))
explicit

Constructor.

Parameters
cescape char indicating start of macros, or QChar::null for none

Definition at line 15 of file kmacroexpander.cpp.

KMacroExpanderBase::~KMacroExpanderBase ( )
virtual

Destructor.

Definition at line 19 of file kmacroexpander.cpp.

Member Function Documentation

QChar KMacroExpanderBase::escapeChar ( ) const

Obtain the macro escape character.

Returns
escape char indicating start of macros, or QChar::null if none

Definition at line 29 of file kmacroexpander.cpp.

int KMacroExpanderBase::expandEscapedMacro ( const QString str,
int  pos,
QStringList ret 
)
protectedvirtual

This function is called every time the escape char is found if it is not QChar::null.

It should determine whether the string starting at pos witin str is a valid macro and return the substitution value for it if so.

Parameters
strthe input string
posthe offset within str. Note that this is the position of the occurrence of the escape char
retreturn value: the string to substitute for the macro
Returns
If greater than zero, the number of chars at pos in str to substitute with ret (i.e., a valid macro was found). If less than zero, subtract this value from pos (to skip a macro, i.e., substitute it with itself). If zero, scanning continues as if no escape char was encountered at all.

Reimplemented in KCharMacroExpander, and KWordMacroExpander.

Definition at line 81 of file kmacroexpander.cpp.

void KMacroExpanderBase::expandMacros ( QString str)

Perform safe macro expansion (substitution) on a string.

Parameters
strthe string in which macros are expanded in-place

Definition at line 34 of file kmacroexpander.cpp.

bool KMacroExpanderBase::expandMacrosShellQuote ( QString str,
int &  pos 
)

Perform safe macro expansion (substitution) on a string for use in shell commands.

*NIX notes

Explicitly supported shell constructs: \ '' "" $'' $"" {} () $(()) ${} $() ``

Implicitly supported shell constructs: (())

Unsupported shell constructs that will cause problems: Shortened "case $v in pat)" syntax. Use "case $v in (pat)" instead.

The rest of the shell (incl. bash) syntax is simply ignored, as it is not expected to cause problems.

Note that bash contains a bug which makes macro expansion within double quoted substitutions ("${VAR:-%macro}") inherently insecure.

For security reasons, never put expandos in command line arguments that are shell commands by themselves - "sh -c 'foo %f'" is taboo. "file=%f sh -c 'foo "$file"'" is OK.

Windows notes

All quoting syntax supported by KShell is supported here as well. Additionally, command grouping via parentheses is recognized - note however, that the parser is much stricter about unquoted parentheses than cmd itself. The rest of the cmd syntax is simply ignored, as it is not expected to cause problems - do not use commands that embed other commands, though - "for /f ..." is taboo.

Parameters
strthe string in which macros are expanded in-place
posthe position inside the string at which parsing/substitution should start, and upon exit where processing stopped
Returns
false if the string could not be parsed and therefore no safe substitution was possible. Note that macros will have been processed up to the point where the error occurred. An unmatched closing paren or brace outside any shell construct is not an error (unlike in the function below), but still prematurely terminates processing.

Definition at line 73 of file kmacroexpander_unix.cpp.

bool KMacroExpanderBase::expandMacrosShellQuote ( QString str)

Same as above, but always starts at position 0, and unmatched closing parens and braces are treated as errors.

Definition at line 69 of file kmacroexpander.cpp.

int KMacroExpanderBase::expandPlainMacro ( const QString str,
int  pos,
QStringList ret 
)
protectedvirtual

This function is called for every single char within the string if the escape char is QChar::null.

It should determine whether the string starting at pos within str is a valid macro and return the substitution value for it if so.

Parameters
strthe input string
posthe offset within str
retreturn value: the string to substitute for the macro
Returns
If greater than zero, the number of chars at pos in str to substitute with ret (i.e., a valid macro was found). If less than zero, subtract this value from pos (to skip a macro, i.e., substitute it with itself). If zero, no macro starts at pos.

Reimplemented in KCharMacroExpander, and KWordMacroExpander.

Definition at line 75 of file kmacroexpander.cpp.

void KMacroExpanderBase::setEscapeChar ( QChar  c)

Set the macro escape character.

Parameters
cescape char indicating start of macros, or QChar::null if none

Definition at line 24 of file kmacroexpander.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Nov 26 2020 23:00:33 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.