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 */