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 00036 class KMacroExpanderBase { 00037 00038 public: 00043 KMacroExpanderBase( QChar c = '%' ); 00044 00048 virtual ~KMacroExpanderBase(); 00049 00055 void expandMacros( QString &str ); 00056 00057 /* 00058 * Perform safe macro expansion (substitution) on a string for use 00059 * in shell commands. 00060 * 00061 * Explicitly supported shell constructs: 00062 * \ '' "" $'' $"" {} () $(()) ${} $() `` 00063 * 00064 * Implicitly supported shell constructs: 00065 * (()) 00066 * 00067 * Unsupported shell constructs that will cause problems: 00068 * @li Shortened "case $v in pat)" syntax. Use "case $v in (pat)" instead. 00069 * 00070 * The rest of the shell (incl. bash) syntax is simply ignored, 00071 * as it is not expected to cause problems. 00072 * 00073 * Note that bash contains a bug which makes macro expansion within 00074 * double quoted substitutions ("${VAR:-%macro}") inherently insecure. 00075 * 00076 * @param str the string in which macros are expanded in-place 00077 * @param pos the position inside the string at which parsing/substitution 00078 * should start, and upon exit where processing stopped 00079 * @return false if the string could not be parsed and therefore no safe 00080 * substitution was possible. Note that macros will have been processed 00081 * up to the point where the error occured. An unmatched closing paren 00082 * or brace outside any shell construct is @em not an error (unlike in 00083 * the function below), but still prematurely terminates processing. 00084 */ 00085 bool expandMacrosShellQuote( QString &str, uint &pos ); 00086 00091 bool expandMacrosShellQuote( QString &str ); 00092 00097 void setEscapeChar( QChar c ); 00098 00103 QChar escapeChar() const; 00104 00105 protected: 00119 virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret ); 00120 00135 virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret ); 00136 00137 private: 00138 QChar escapechar; 00139 }; 00140 00146 namespace KMacroExpander { 00167 QString expandMacros( const QString &str, const QMap<QChar,QString> &map, QChar c = '%' ); 00168 00192 QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QString> &map, QChar c = '%' ); 00193 00217 QString expandMacros( const QString &str, const QMap<QString,QString> &map, QChar c = '%' ); 00218 00245 QString expandMacrosShellQuote( const QString &str, const QMap<QString,QString> &map, QChar c = '%' ); 00246 00251 QString expandMacros( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' ); 00252 QString expandMacros( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' ); 00253 00254 /* 00255 * Same as above, except that the macros expand to string lists. 00256 * If the macro appears inside a quoted string, the list is simply 00257 * join(" ")ed together; otherwise every element expands to a separate 00258 * quoted string. 00259 */ 00260 QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' ); 00261 QString expandMacrosShellQuote( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' ); 00262 } 00263 00264 #endif /* _KMACROEXPANDER_H */