kmacroexpander.h

/*
    This file is part of the KDE libraries
 
    Copyright (c) 2002-2003 Oswald Buddenhagen <ossi@kde.org>
    Copyright (c) 2003 Waldo Bastian <bastian@kde.org>
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.
 
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.
 
    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/
#ifndef _KMACROEXPANDER_H
#define _KMACROEXPANDER_H
 
#include <tqstringlist.h>
#include <tqstring.h>
#include <tqmap.h>
#include "tdelibs_export.h"
 
class TDECORE_EXPORT KMacroExpanderBase {
 
public:
    KMacroExpanderBase( TQChar c = '%' );
 
    virtual ~KMacroExpanderBase();
 
    void expandMacros( TQString &str );
 
    /*
     * Perform safe macro expansion (substitution) on a string for use
     * in shell commands.
     *
     * Explicitly supported shell constructs:
     *   \ '' "" $'' $"" {} () $(()) ${} $() ``
     *
     * Implicitly supported shell constructs:
     *   (())
     *
     * Unsupported shell constructs that will cause problems:
     *  @li Shortened "case $v in pat)" syntax. Use "case $v in (pat)" instead.
     *
     * The rest of the shell (incl. bash) syntax is simply ignored,
     * as it is not expected to cause problems.
     *
     * Note that bash contains a bug which makes macro expansion within 
     * double quoted substitutions ("${VAR:-%macro}") inherently insecure.
     *
     * @param str the string in which macros are expanded in-place
     * @param pos the position inside the string at which parsing/substitution
     *  should start, and upon exit where processing stopped
     * @return false if the string could not be parsed and therefore no safe
     *  substitution was possible. Note that macros will have been processed
     *  up to the point where the error occurred. An unmatched closing paren
     *  or brace outside any shell construct is @em not an error (unlike in
     *  the function below), but still prematurely terminates processing.
     */
    bool expandMacrosShellQuote( TQString &str, uint &pos );
 
    bool expandMacrosShellQuote( TQString &str );
 
    void setEscapeChar( TQChar c );
 
    TQChar escapeChar() const;
 
protected:
    virtual int expandPlainMacro( const TQString &str, uint pos, TQStringList &ret );
 
    virtual int expandEscapedMacro( const TQString &str, uint pos, TQStringList &ret );
 
private:
    TQChar escapechar;
};
 
class TDECORE_EXPORT KWordMacroExpander : public KMacroExpanderBase {
 
public:
    KWordMacroExpander( TQChar c = '%' ) : KMacroExpanderBase( c ) {}
 
protected:
    virtual int expandPlainMacro( const TQString &str, uint pos, TQStringList &ret );
    virtual int expandEscapedMacro( const TQString &str, uint pos, TQStringList &ret );
 
    virtual bool expandMacro( const TQString &str, TQStringList &ret ) = 0;
};
 
class TDECORE_EXPORT KCharMacroExpander : public KMacroExpanderBase {
 
public:
    KCharMacroExpander( TQChar c = '%' ) : KMacroExpanderBase( c ) {}
 
protected:
    virtual int expandPlainMacro( const TQString &str, uint pos, TQStringList &ret );
    virtual int expandEscapedMacro( const TQString &str, uint pos, TQStringList &ret );
 
    virtual bool expandMacro( TQChar chr, TQStringList &ret ) = 0;
};
 
namespace KMacroExpander {
    TDECORE_EXPORT TQString expandMacros( const TQString &str, const TQMap<TQChar,TQString> &map, TQChar c = '%' );
 
    TDECORE_EXPORT TQString expandMacrosShellQuote( const TQString &str, const TQMap<TQChar,TQString> &map, TQChar c = '%' );
 
    TDECORE_EXPORT TQString expandMacros( const TQString &str, const TQMap<TQString,TQString> &map, TQChar c = '%' );
 
    TDECORE_EXPORT TQString expandMacrosShellQuote( const TQString &str, const TQMap<TQString,TQString> &map, TQChar c = '%' );
 
    TDECORE_EXPORT TQString expandMacros( const TQString &str, const TQMap<TQChar,TQStringList> &map, TQChar c = '%' );
    TDECORE_EXPORT TQString expandMacros( const TQString &str, const TQMap<TQString,TQStringList> &map, TQChar c = '%' );
 
    TDECORE_EXPORT TQString expandMacrosShellQuote( const TQString &str, const TQMap<TQChar,TQStringList> &map, TQChar c = '%' );
    TDECORE_EXPORT TQString expandMacrosShellQuote( const TQString &str, const TQMap<TQString,TQStringList> &map, TQChar c = '%' );
}
 
#endif /* _KMACROEXPANDER_H */