# kdecore Library API Documentation

Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Namespaces | Source Files

# KWordMacroExpander Class Reference

Abstract base class for simple word macro substitutors. More...

`#include <kmacroexpander.h>`

Inheritance diagram for KWordMacroExpander:

[legend]
Collaboration diagram for KWordMacroExpander:

[legend]
List of all members.

## Public Member Functions

| KWordMacroExpander (QChar c= '%')

## Protected Member Functions

virtual int | expandPlainMacro (const QString &str, uint pos, QStringList &ret)
virtual int | expandEscapedMacro (const QString &str, uint pos, QStringList &ret)
virtual bool | expandMacro (const QString &str, QStringList &ret)=0

## Detailed Description

Abstract base class for simple word macro substitutors.

Use this instead of the functions in the KMacroExpander namespace if speculatively pre-filling the substitution map would be too expensive.

A typical application:

     class MyClass {
     ...
       private:
         QString m_str;
     ...
       friend class MyExpander;
     };

     class MyExpander : public KWordMacroExpander {
       public:
         MyExpander( MyClass *_that ) : KWordMacroExpander(), that( _that ) {}
       protected:
         virtual bool expandMacro( const QString &str, QStringList &ret );
       private:
         MyClass *that;
     };

     bool MyExpander::expandMacro( const QString &str, QStringList &ret )
     {
       if (str == "macro") {
         ret += complexOperation( that->m_str );
         return true;
       }
       return false;
     }

     ... MyClass::...(...)
     {
       QString str;
       ...
       MyExpander mx( this );
       mx.expandMacrosShellQuote( str );
       ...
     }

Alternatively MyClass could inherit from KWordMacroExpander directly.

Since:
  3.3

Author:
  Oswald Buddenhagen <ossi@kde.org>

Definition at line 191 of file kmacroexpander.h.

## Constructor & Destructor Documentation

KWordMacroExpander::KWordMacroExpander | ( | QChar | c = `'%'` | ) | `[inline]`

Constructor.

Parameters:

  | c | escape char indicating start of macros, or QChar::null for none

Definition at line 198 of file kmacroexpander.h.

## Member Function Documentation

int KWordMacroExpander::expandPlainMacro | ( | const QString & | str,
|  | uint | pos,
|  | QStringList & | ret
| ) | `[protected, virtual]`

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). zero requests no special action.

Reimplemented from KMacroExpanderBase.

Definition at line 454 of file kmacroexpander.cpp.

References expandMacro().

int KWordMacroExpander::expandEscapedMacro | ( | const QString & | str,
|  | uint | pos,
|  | QStringList & | ret
| ) | `[protected, virtual]`

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). zero requests no special action.

Reimplemented from KMacroExpanderBase.

Definition at line 468 of file kmacroexpander.cpp.

References KMacroExpanderBase::escapeChar(), and expandMacro().

virtual bool KWordMacroExpander::expandMacro | ( | const QString & | str,
|  | QStringList & | ret
| ) | `[protected, pure virtual]`

Return substitution list `ret` for string macro `str`.

Parameters:

  | str | the macro to expand
  | ret | return variable reference. It is guaranteed to be empty when expandMacro is entered.

Returns:
  `true` iff `chr` was a recognized macro name

Referenced by expandEscapedMacro(), and expandPlainMacro().

The documentation for this class was generated from the following files:

- kmacroexpander.h
- kmacroexpander.cpp

This file is part of the documentation for kdecore Library Version 3.4.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat Jun 11 20:19:13 2005 by doxygen 1.4.1 written by Dimitri van Heesch, © 1997-2003