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 / kshell.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  4.7 KB  |  148 lines
  1. /*
  2.     This file is part of the KDE libraries
  3.  
  4.     Copyright (c) 2003 Oswald Buddenhagen <ossi@kde.org>
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License as published by the Free Software Foundation; either
  9.     version 2 of the License, or (at your option) any later version.
  10.  
  11.     This library is distributed in the hope that it will be useful,
  12.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.     Library General Public License for more details.
  15.  
  16.     You should have received a copy of the GNU Library General Public License
  17.     along with this library; see the file COPYING.LIB.  If not, write to
  18.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.     Boston, MA 02110-1301, USA.
  20. */
  21. #ifndef _KSHELL_H
  22. #define _KSHELL_H
  23.  
  24. #include <qstring.h>
  25. #include <qstringlist.h>
  26. #include "kdelibs_export.h"
  27.  
  28. /**
  29.  * \namespace KShell
  30.  * Provides some basic POSIX shell and bash functionality.
  31.  * @see KStringHandler
  32.  *
  33.  * @since 3.2
  34.  */
  35. namespace KShell {
  36.  
  37.     /**
  38.      * Flags for splitArgs().
  39.      */
  40.     enum Options {
  41.         NoOptions = 0,
  42.  
  43.         /**
  44.          * Perform tilde expansion.
  45.          */
  46.         TildeExpand = 1,
  47.  
  48.         /**
  49.          * Bail out if a non-quoting and not quoted shell meta character is encoutered.
  50.          * Meta characters are the command separators @p semicolon and @p ampersand,
  51.          * the redirection symbols @p less-than, @p greater-than and the @p pipe @p symbol,
  52.          * the grouping symbols opening and closing @p parens and @p braces, the command
  53.          * substitution symbol @p backquote, the generic substitution symbol @p dollar
  54.          * (if not followed by an apostrophe), the wildcards @p asterisk and
  55.          * @p question @p mark, and the comment symbol @p hash @p mark. Additionally,
  56.          * a variable assignment in the first word is recognized.
  57.          */
  58.         AbortOnMeta = 2
  59.     };
  60.  
  61.     /**
  62.      * Status codes from splitArgs()
  63.      */
  64.     enum Errors {
  65.         /**
  66.          * Success.
  67.          */
  68.         NoError = 0,
  69.  
  70.         /**
  71.          * Indicates a parsing error, like an unterminated quoted string.
  72.          */
  73.         BadQuoting,
  74.  
  75.         /**
  76.          * The AbortOnMeta flag was set and a shell meta character
  77.          * was encoutered.
  78.          */
  79.         FoundMeta
  80.     };
  81.  
  82.     /**
  83.      * Splits @p cmd according to POSIX shell word splitting and quoting rules.
  84.      * Can optionally perform tilde expansion and/or abort if it finds shell
  85.      * meta characters it cannot process.
  86.      *
  87.      * @param cmd the command to split
  88.      * @param flags operation flags, see Options
  89.      * @param err if not NULL, a status code will be stored at the pointer
  90.      *  target, see Errors
  91.      * @return a list of unquoted words or an empty list if an error occurred
  92.      */
  93.     KDECORE_EXPORT QStringList splitArgs( const QString &cmd, int flags = 0, int *err = 0 );
  94.  
  95.     /**
  96.      * Quotes and joins @p args together according to POSIX shell rules.
  97.      *
  98.      * @param args a list of strings to quote and join
  99.      * @return a command suitable for shell execution
  100.      */
  101.     KDECORE_EXPORT QString joinArgs( const QStringList &args );
  102.  
  103.     /**
  104.      * Same as above, but $'' is used instead of '' for the quoting.
  105.      * The output is suitable for splitArgs(), bash, zsh and possibly
  106.      * other bourne-compatible shells, but not for plain sh. The advantage
  107.      * is, that control characters (ASCII less than 32) are escaped into
  108.      * human-readable strings.
  109.      *
  110.      * @param args a list of strings to quote and join
  111.      * @return a command suitable for shell execution
  112.      */
  113.     KDECORE_EXPORT QString joinArgsDQ( const QStringList &args );
  114.  
  115.     /**
  116.      * Quotes and joins @p argv together according to POSIX shell rules.
  117.      *
  118.      * @param argv an array of c strings to quote and join.
  119.      *  The strings are expected to be in local-8-bit encoding.
  120.      * @param argc maximal number of strings in @p argv. if not supplied,
  121.      *  @p argv must be null-terminated.
  122.      * @return a command suitable for shell execution
  123.      */
  124.     KDECORE_EXPORT QString joinArgs( const char * const *argv, int argc = -1 );
  125.  
  126.     /**
  127.      * Performs tilde expansion on @p path. Interprets "~/path" and
  128.      * "~user/path".
  129.      *
  130.      * @param path the path to tilde-expand
  131.      * @return the expanded path
  132.      */
  133.     KDECORE_EXPORT QString tildeExpand( const QString &path );
  134.  
  135.     /**
  136.      * Obtain a @p user's home directory.
  137.      *
  138.      * @param user The name of the user whose home dir should be obtained.
  139.      *  An empty string denotes the current user.
  140.      * @return The user's home directory.
  141.      */
  142.     KDECORE_EXPORT QString homeDir( const QString &user );
  143.  
  144. }
  145.  
  146.  
  147. #endif /* _KSHELL_H */
  148.