home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kmacroexpander.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  13.8 KB  |  381 lines
  1. /*
  2.     This file is part of the KDE libraries
  3.  
  4.     Copyright (c) 2002-2003 Oswald Buddenhagen <ossi@kde.org>
  5.     Copyright (c) 2003 Waldo Bastian <bastian@kde.org>
  6.  
  7.     This library is free software; you can redistribute it and/or
  8.     modify it under the terms of the GNU Library General Public
  9.     License as published by the Free Software Foundation; either
  10.     version 2 of the License, or (at your option) any later version.
  11.  
  12.     This library is distributed in the hope that it will be useful,
  13.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.     Library General Public License for more details.
  16.  
  17.     You should have received a copy of the GNU Library General Public License
  18.     along with this library; see the file COPYING.LIB.  If not, write to
  19.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20.     Boston, MA 02110-1301, USA.
  21. */
  22. #ifndef _KMACROEXPANDER_H
  23. #define _KMACROEXPANDER_H
  24.  
  25. #include <qstringlist.h>
  26. #include <qstring.h>
  27. #include <qmap.h>
  28. #include "kdelibs_export.h"
  29.  
  30. /**
  31.  * Abstract base class for the worker classes behind the KMacroExpander namespace
  32.  * and the KCharMacroExpander and KWordMacroExpander classes.
  33.  *
  34.  * @since 3.1.3
  35.  * @author Oswald Buddenhagen <ossi@kde.org>
  36.  */
  37. class KDECORE_EXPORT KMacroExpanderBase {
  38.  
  39. public:
  40.     /**
  41.      * Constructor.
  42.      * @param c escape char indicating start of macros, or QChar::null for none
  43.      */
  44.     KMacroExpanderBase( QChar c = '%' );
  45.  
  46.     /**
  47.      * Destructor.
  48.      */
  49.     virtual ~KMacroExpanderBase();
  50.  
  51.     /**
  52.      * Perform safe macro expansion (substitution) on a string.
  53.      *
  54.      * @param str the string in which macros are expanded in-place
  55.      */
  56.     void expandMacros( QString &str );
  57.  
  58.     /*
  59.      * Perform safe macro expansion (substitution) on a string for use
  60.      * in shell commands.
  61.      *
  62.      * Explicitly supported shell constructs:
  63.      *   \ '' "" $'' $"" {} () $(()) ${} $() ``
  64.      *
  65.      * Implicitly supported shell constructs:
  66.      *   (())
  67.      *
  68.      * Unsupported shell constructs that will cause problems:
  69.      *  @li Shortened "case $v in pat)" syntax. Use "case $v in (pat)" instead.
  70.      *
  71.      * The rest of the shell (incl. bash) syntax is simply ignored,
  72.      * as it is not expected to cause problems.
  73.      *
  74.      * Note that bash contains a bug which makes macro expansion within 
  75.      * double quoted substitutions ("${VAR:-%macro}") inherently insecure.
  76.      *
  77.      * @param str the string in which macros are expanded in-place
  78.      * @param pos the position inside the string at which parsing/substitution
  79.      *  should start, and upon exit where processing stopped
  80.      * @return false if the string could not be parsed and therefore no safe
  81.      *  substitution was possible. Note that macros will have been processed
  82.      *  up to the point where the error occurred. An unmatched closing paren
  83.      *  or brace outside any shell construct is @em not an error (unlike in
  84.      *  the function below), but still prematurely terminates processing.
  85.      */
  86.     bool expandMacrosShellQuote( QString &str, uint &pos );
  87.  
  88.     /**
  89.      * Same as above, but always starts at position 0, and unmatched closing
  90.      * parens and braces are treated as errors.
  91.      */
  92.     bool expandMacrosShellQuote( QString &str );
  93.  
  94.     /**
  95.      * Set the macro escape character.
  96.      * @param c escape char indicating start of macros, or QChar::null if none
  97.      */
  98.     void setEscapeChar( QChar c );
  99.  
  100.     /**
  101.      * Obtain the macro escape character.
  102.      * @return escape char indicating start of macros, or QChar::null if none
  103.      */
  104.     QChar escapeChar() const;
  105.  
  106. protected:
  107.     /**
  108.      * This function is called for every single char within the string if
  109.      * the escape char is QChar::null. It should determine whether the
  110.      * string starting at @p pos within @p str is a valid macro and return
  111.      * the substitution value for it if so.
  112.      * @param str the input string
  113.      * @param pos the offset within @p str
  114.      * @param ret return value: the string to substitute for the macro
  115.      * @return if greater than zero, the number of chars at @p pos in @p str
  116.      *  to substitute with @p ret (i.e., a valid macro was found). if less
  117.      *  than zero, subtract this value from @p pos (to skip a macro, i.e.,
  118.      *  substitute it with itself). zero requests no special action.
  119.      */
  120.     virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret );
  121.  
  122.     /**
  123.      * This function is called every time the escape char is found if it is
  124.      * not QChar::null. It should determine whether the
  125.      * string starting at @p pos witin @p str is a valid macro and return
  126.      * the substitution value for it if so.
  127.      * @param str the input string
  128.      * @param pos the offset within @p str. Note that this is the position of
  129.      *  the occurrence of the escape char
  130.      * @param ret return value: the string to substitute for the macro
  131.      * @return if greater than zero, the number of chars at @p pos in @p str
  132.      *  to substitute with @p ret (i.e., a valid macro was found). if less
  133.      *  than zero, subtract this value from @p pos (to skip a macro, i.e.,
  134.      *  substitute it with itself). zero requests no special action.
  135.      */
  136.     virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret );
  137.  
  138. private:
  139.     QChar escapechar;
  140. };
  141.  
  142. /**
  143.  * Abstract base class for simple word macro substitutors. Use this instead of
  144.  * the functions in the KMacroExpander namespace if speculatively pre-filling
  145.  * the substitution map would be too expensive.
  146.  *
  147.  * A typical application:
  148.  *
  149.  * \code
  150.  * class MyClass {
  151.  * ...
  152.  *   private:
  153.  *     QString m_str;
  154.  * ...
  155.  *   friend class MyExpander;
  156.  * };
  157.  *
  158.  * class MyExpander : public KWordMacroExpander {
  159.  *   public:
  160.  *     MyExpander( MyClass *_that ) : KWordMacroExpander(), that( _that ) {}
  161.  *   protected:
  162.  *     virtual bool expandMacro( const QString &str, QStringList &ret );
  163.  *   private:
  164.  *     MyClass *that;
  165.  * };
  166.  *
  167.  * bool MyExpander::expandMacro( const QString &str, QStringList &ret )
  168.  * {
  169.  *   if (str == "macro") {
  170.  *     ret += complexOperation( that->m_str );
  171.  *     return true;
  172.  *   }
  173.  *   return false;
  174.  * }
  175.  *
  176.  * ... MyClass::...(...)
  177.  * {
  178.  *   QString str;
  179.  *   ...
  180.  *   MyExpander mx( this );
  181.  *   mx.expandMacrosShellQuote( str );
  182.  *   ...
  183.  * }
  184.  * \endcode
  185.  *
  186.  * Alternatively MyClass could inherit from KWordMacroExpander directly.
  187.  *
  188.  * @since 3.3
  189.  * @author Oswald Buddenhagen <ossi@kde.org>
  190.  */
  191. class KDECORE_EXPORT KWordMacroExpander : public KMacroExpanderBase {
  192.  
  193. public:
  194.     /**
  195.      * Constructor.
  196.      * @param c escape char indicating start of macros, or QChar::null for none
  197.      */
  198.     KWordMacroExpander( QChar c = '%' ) : KMacroExpanderBase( c ) {}
  199.  
  200. protected:
  201.     virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret );
  202.     virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret );
  203.  
  204.     /**
  205.      * Return substitution list @p ret for string macro @p str.
  206.      * @param str the macro to expand
  207.      * @param ret return variable reference. It is guaranteed to be empty
  208.      *  when expandMacro is entered.
  209.      * @return @c true iff @p chr was a recognized macro name
  210.      */
  211.     virtual bool expandMacro( const QString &str, QStringList &ret ) = 0;
  212. };
  213.  
  214. /**
  215.  * Abstract base class for single char macro substitutors. Use this instead of
  216.  * the functions in the KMacroExpander namespace if speculatively pre-filling
  217.  * the substitution map would be too expensive.
  218.  *
  219.  * See KWordMacroExpander for a sample application.
  220.  *
  221.  * @since 3.3
  222.  * @author Oswald Buddenhagen <ossi@kde.org>
  223.  */
  224. class KDECORE_EXPORT KCharMacroExpander : public KMacroExpanderBase {
  225.  
  226. public:
  227.     /**
  228.      * Constructor.
  229.      * @param c escape char indicating start of macros, or QChar::null for none
  230.      */
  231.     KCharMacroExpander( QChar c = '%' ) : KMacroExpanderBase( c ) {}
  232.  
  233. protected:
  234.     virtual int expandPlainMacro( const QString &str, uint pos, QStringList &ret );
  235.     virtual int expandEscapedMacro( const QString &str, uint pos, QStringList &ret );
  236.  
  237.     /**
  238.      * Return substitution list @p ret for single-character macro @p chr.
  239.      * @param chr the macro to expand
  240.      * @param ret return variable reference. It is guaranteed to be empty
  241.      *  when expandMacro is entered.
  242.      * @return @c true iff @p chr was a recognized macro name
  243.      */
  244.     virtual bool expandMacro( QChar chr, QStringList &ret ) = 0;
  245. };
  246.  
  247. /**
  248.  * A group of functions providing macro expansion (substitution) in strings,
  249.  * optionally with quoting appropriate for shell execution.
  250.  * @since 3.1.3
  251.  */
  252. namespace KMacroExpander {
  253.     /**
  254.      * Perform safe macro expansion (substitution) on a string.
  255.      * The escape char must be quoted with itself to obtain its literal
  256.      * representation in the resulting string.
  257.      *
  258.      * @param str The string to expand
  259.      * @param map map with substitutions
  260.      * @param c escape char indicating start of macro, or QChar::null if none
  261.      * @return the string with all valid macros expanded
  262.      *
  263.      * \code
  264.      * // Code example
  265.      * QMap<QChar,QString> map;
  266.      * map.insert('u', "/tmp/myfile.txt");
  267.      * map.insert('n', "My File");
  268.      * QString s = "%% Title: %u:%n";
  269.      * s = KMacroExpander::expandMacros(s, map);
  270.      * // s is now "% Title: /tmp/myfile.txt:My File";
  271.      * \endcode
  272.      */
  273.     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QChar,QString> &map, QChar c = '%' );
  274.  
  275.     /**
  276.      * Perform safe macro expansion (substitution) on a string for use
  277.      * in shell commands.
  278.      * The escape char must be quoted with itself to obtain its literal
  279.      * representation in the resulting string.
  280.      *
  281.      * @param str The string to expand
  282.      * @param map map with substitutions
  283.      * @param c escape char indicating start of macro, or QChar::null if none
  284.      * @return the string with all valid macros expanded, or a null string
  285.      *  if a shell syntax error was detected in the command
  286.      *
  287.      * \code
  288.      * // Code example
  289.      * QMap<QChar,QString> map;
  290.      * map.insert('u', "/tmp/myfile.txt");
  291.      * map.insert('n', "My File");
  292.      * QString s = "kedit --caption %n %u";
  293.      * s = KMacroExpander::expandMacrosShellQuote(s, map);
  294.      * // s is now "kedit --caption 'My File' '/tmp/myfile.txt'";
  295.      * system(QFile::encodeName(s));
  296.      * \endcode
  297.      */
  298.     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QString> &map, QChar c = '%' );
  299.  
  300.     /**
  301.      * Perform safe macro expansion (substitution) on a string.
  302.      * The escape char must be quoted with itself to obtain its literal
  303.      * representation in the resulting string.
  304.      * Macro names can consist of chars in the range [A-Za-z0-9_];
  305.      * use braces to delimit macros from following words starting
  306.      * with these chars, or to use other chars for macro names.
  307.      *
  308.      * @param str The string to expand
  309.      * @param map map with substitutions
  310.      * @param c escape char indicating start of macro, or QChar::null if none
  311.      * @return the string with all valid macros expanded
  312.      *
  313.      * \code
  314.      * // Code example
  315.      * QMap<QString,QString> map;
  316.      * map.insert("url", "/tmp/myfile.txt");
  317.      * map.insert("name", "My File");
  318.      * QString s = "Title: %{url}-%name";
  319.      * s = KMacroExpander::expandMacros(s, map);
  320.      * // s is now "Title: /tmp/myfile.txt-My File";
  321.      * \endcode
  322.      */
  323.     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QString,QString> &map, QChar c = '%' );
  324.  
  325.     /**
  326.      * Perform safe macro expansion (substitution) on a string for use
  327.      * in shell commands.
  328.      * The escape char must be quoted with itself to obtain its literal
  329.      * representation in the resulting string.
  330.      * Macro names can consist of chars in the range [A-Za-z0-9_];
  331.      * use braces to delimit macros from following words starting
  332.      * with these chars, or to use other chars for macro names.
  333.      *
  334.      * @param str The string to expand
  335.      * @param map map with substitutions
  336.      * @param c escape char indicating start of macro, or QChar::null if none
  337.      * @return the string with all valid macros expanded, or a null string
  338.      *  if a shell syntax error was detected in the command
  339.      *
  340.      * \code
  341.      * // Code example
  342.      * QMap<QString,QString> map;
  343.      * map.insert("url", "/tmp/myfile.txt");
  344.      * map.insert("name", "My File");
  345.      * QString s = "kedit --caption %name %{url}";
  346.      * s = KMacroExpander::expandMacrosShellQuote(s, map);
  347.      * // s is now "kedit --caption 'My File' '/tmp/myfile.txt'";
  348.      * system(QFile::encodeName(s));
  349.      * \endcode
  350.      */
  351.     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QString,QString> &map, QChar c = '%' );
  352.  
  353.     /**
  354.      * Same as above, except that the macros expand to string lists that
  355.      * are simply join(" ")ed together.
  356.      */
  357.     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' );
  358.     /**
  359.      * Same as above, except that the macros expand to string lists that
  360.      * are simply join(" ")ed together.
  361.      */
  362.     KDECORE_EXPORT QString expandMacros( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' );
  363.  
  364.     /**
  365.      * Same as above, except that the macros expand to string lists.
  366.      * If the macro appears inside a quoted string, the list is simply
  367.      * join(" ")ed together; otherwise every element expands to a separate
  368.      * quoted string.
  369.      */
  370.     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QChar,QStringList> &map, QChar c = '%' );
  371.     /**
  372.      * Same as above, except that the macros expand to string lists.
  373.      * If the macro appears inside a quoted string, the list is simply
  374.      * join(" ")ed together; otherwise every element expands to a separate
  375.      * quoted string.
  376.      */
  377.     KDECORE_EXPORT QString expandMacrosShellQuote( const QString &str, const QMap<QString,QStringList> &map, QChar c = '%' );
  378. }
  379.  
  380. #endif /* _KMACROEXPANDER_H */
  381.