kdecore Library API Documentation

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 */
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.4.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Sun Feb 27 22:14:47 2005 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001