KMacroExpanderBase Class Reference

from PyKDE4.kdecore import *

Subclasses: KCharMacroExpander, KWordMacroExpander

Detailed Description

\class KMacroExpanderBase kmacroexpander.h <KMacroExpanderBase>

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

Author:: Oswald Buddenhagen <ossi@kde.org>

Methods
	__init__ (self, QChar c=QLatin1Char('%'))
	__init__ (self, KMacroExpanderBase other)
QChar	escapeChar (self)
int	expandEscapedMacro (self, QString str, int pos, QStringList ret)
	expandMacros (self, QString str)
bool, int (pos)	expandMacrosShellQuote (self, QString str, )
bool	expandMacrosShellQuote (self, QString str)
int	expandPlainMacro (self, QString str, int pos, QStringList ret)
	setEscapeChar (self, QChar c)

Method Documentation

__init__	(	self,
		QChar	c=QLatin1Char('%')
	)

Constructor.

Parameters:

escape char indicating start of macros, or QChar.null for none

__init__	(	self,
		KMacroExpanderBase	other
	)

QChar escapeChar ( self )

Obtain the macro escape character.

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

int expandEscapedMacro	(	self,
		QString	str,
		int	pos,
		QStringList	ret
	)

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:

	str	the input string
	pos	the offset within str. Note that this is the position of the occurrence of the escape char
	ret	return 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.

expandMacros	(	self,
		QString	str
	)

Perform safe macro expansion (substitution) on a string.

Parameters:

str

the string in which macros are expanded in-place

bool, int (pos) expandMacrosShellQuote	(	self,
		QString	str,
	)

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

<h3>*NIX notes</h3>

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

Implicitly supported shell constructs: (())

Unsupported shell constructs that will cause problems: Shortened "<tt>case $v in pat)</tt>" syntax. Use "<tt>case $v in (pat)</tt>" 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 (<tt>"${VAR:-%macro}"</tt>) inherently insecure.

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

<h3>Windows notes</h3>

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 - "<tt>for /f ...</tt>" is taboo.

Parameters:

	str	the string in which macros are expanded in-place
	pos	the 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.

bool expandMacrosShellQuote	(	self,
		QString	str
	)

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

int expandPlainMacro	(	self,
		QString	str,
		int	pos,
		QStringList	ret
	)

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:

	str	the input string
	pos	the offset within str
	ret	return 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.

setEscapeChar	(	self,
		QChar	c
	)

Set the macro escape character.

Parameters:

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

KMacroExpanderBase Class Reference

Detailed Description

Methods

Method Documentation

Modules