# kdecore Library API Documentation

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

# kmacroexpander.h

    00001 /*
    00002     This file is part of the KDE libraries
    00003
    00004     Copyright (c) 2002-2003 Oswald Buddenhagen <ossi@kde.org>
    00005     Copyright (c) 2003 Waldo Bastian <bastian@kde.org>
    00006
    00007     This library is free software; you can redistribute it and/or
    00008     modify it under the terms of the GNU Library General Public
    00009     License as published by the Free Software Foundation; either
    00010     version 2 of the License, or (at your option) any later version.
    00011
    00012     This library is distributed in the hope that it will be useful,
    00013     but WITHOUT ANY WARRANTY; without even the implied warranty of
    00014     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    00015     Library General Public License for more details.
    00016
    00017     You should have received a copy of the GNU Library General Public License
    00018     along with this library; see the file COPYING.LIB.  If not, write to
    00019     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    00020     Boston, MA 02111-1307, USA.
    00021 */
    00022 #ifndef _KMACROEXPANDER_H
    00023 #define _KMACROEXPANDER_H
    00024
    00025 #include <qstringlist.h>
    00026 #include <qstring.h>
    00027 #include <qmap.h>
    00028 #include "kdelibs_export.h"
    00029
    00037 class KDECORE_EXPORT KMacroExpanderBase {
    00038
    00039 public:
    00044     KMacroExpanderBase( QChar c = '%' );
    00045
    00049     virtual ~KMacroExpanderBase();
    00050
    00056     void expandMacros( QString &str );
    00057
    00058     /*
    00059      * Perform safe macro expansion (substitution) on a string for use
    00060      * in shell commands.
    00061      *
    00062      * Explicitly supported shell constructs:
    00063      *   \ '' "" $'' $"" {} () $(()) ${} $() ``
    00064      *
    00065      * Implicitly supported shell constructs:
    00066      *   (())
    00067      *
    00068      * Unsupported shell constructs that will cause problems:
    00069      *  @li Shortened "case $v in pat)" syntax. Use "case $v in (pat)" instead.
    00070      *
    00071      * The rest of the shell (incl. bash) syntax is simply ignored,
    00072      * as it is not expected to cause problems.
    00073      *
    00074      * Note that bash contains a bug which makes macro expansion within
    00075      * double quoted substitutions ("${VAR:-%macro}") inherently insecure.
    00076      *
    00077      * @param str the string in which macros are expanded in-place
    00078      * @param pos the position inside the string at which parsing/substitution
    00079      *  should start, and upon exit where processing stopped
    00080      * @return false if the string could not be parsed and therefore no safe
    00081      *  substitution was possible. Note that macros will have been processed
    00082      *  up to the point where the error occurred. An unmatched closing paren
    00083      *  or brace outside any shell construct is @em not an error (unlike in
    00084      *  the function below), but still prematurely terminates processing.
    00085      */
    00086     bool expandMacrosShellQuote( QString &str, uint &pos );
    00087
    00092     bool expandMacrosShellQuote( QString &str );
    00093
    00098     void setEscapeChar( QChar c );
    00099
    00104     QChar escapeChar() const;
    00105
    00106 protected:
    00120     virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret );
    00121
    00136     virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret );
    00137
    00138 private:
    00139     QChar escapechar;
    00140 };
    00141
    00191 class KDECORE_EXPORT KWordMacroExpander : public KMacroExpanderBase {
    00192
    00193 public:
    00198     KWordMacroExpander( QChar c = '%' ) : KMacroExpanderBase( c ) {}
    00199
    00200 protected:
    00201     virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret );
    00202     virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret );
    00203
    00211     virtual bool expandMacro( const QString &str, QStringList &ret ) = 0;
    00212 };
    00213
    00224 class KDECORE_EXPORT KCharMacroExpander : public KMacroExpanderBase {
    00225
    00226 public:
    00231     KCharMacroExpander( QChar c = '%' ) : KMacroExpanderBase( c ) {}
    00232
    00233 protected:
    00234     virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret );
    00235     virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret );
    00236
    00244     virtual bool expandMacro( QChar chr, QStringList &ret ) = 0;
    00245 };
    00246
    00252 namespace KMacroExpander {
    00273     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QChar,QString> &map, QChar c = '%' );
    00274
    00298     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QString> &map, QChar c = '%' );
    00299
    00323     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QString,QString> &map, QChar c = '%' );
    00324
    00351     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QString,QString> &map, QChar c = '%' );
    00352
    00357     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' );
    00358     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' );
    00359
    00360     /*
    00361      * Same as above, except that the macros expand to string lists.
    00362      * If the macro appears inside a quoted string, the list is simply
    00363      * join(" ")ed together; otherwise every element expands to a separate
    00364      * quoted string.
    00365      */
    00366     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' );
    00367     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' );
    00368 }
    00369
    00370 #endif /* _KMACROEXPANDER_H */

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:18:09 2005 by doxygen 1.4.1 written by Dimitri van Heesch, © 1997-2003