kmacroexpander.h Source File (kdecore Library)

| # kdecore Library API Documentation
Overview | Class Hierarchy | Classes | Classes (annotated) | Members | 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
    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 */

This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 12:46:41 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001