KDECore

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., 51 Franklin Street, Fifth Floor,
00020     Boston, MA 02110-1301, 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 = '%' );
00362     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' );
00363 
00370     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' );
00377     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' );
00378 }
00379 
00380 #endif /* _KMACROEXPANDER_H */
KDECore

kmacroexpander.h

KDECore

API Reference
