# kdecore Library API Documentation

Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Namespaces | Source Files

# KShell Namespace Reference

Provides some basic POSIX shell and bash functionality. More...

## Enumerations

enum | Options { NoOptions = 0, TildeExpand = 1, AbortOnMeta = 2 }
enum | Errors { NoError = 0, BadQuoting, FoundMeta }

## Functions

KDECORE_EXPORT QStringList | splitArgs (const QString &cmd, int flags=0, int *err=0)
KDECORE_EXPORT QString | joinArgs (const QStringList &args)
KDECORE_EXPORT QString | joinArgsDQ (const QStringList &args)
KDECORE_EXPORT QString | joinArgs (const char *const *argv, int argc=-1)
KDECORE_EXPORT QString | tildeExpand (const QString &path)
KDECORE_EXPORT QString | homeDir (const QString &user)

## Detailed Description

Provides some basic POSIX shell and bash functionality.

See also:
  KStringHandler

## Enumeration Type Documentation

enum KShell::Options

Flags for splitArgs().

Enumeration values:

  TildeExpand | Perform tilde expansion.

  AbortOnMeta

  Bail out if a non-quoting and not quoted shell meta character is encoutered.

  Meta characters are the command separators `semicolon` and `ampersand`, the redirection symbols `less-than`, `greater-than` and the `pipe` `symbol`, the grouping symbols opening and closing `parens` and `braces`, the command substitution symbol `backquote`, the generic substitution symbol `dollar` (if not followed by an apostrophe), the wildcards `asterisk` and `question` `mark`, and the comment symbol `hash` `mark`. Additionally, a variable assignment in the first word is recognized.

Definition at line 38 of file kshell.h.

enum KShell::Errors

Status codes from splitArgs().

Enumeration values:

  NoError | Success.
  BadQuoting | Indicates a parsing error, like an unterminated quoted string.
  FoundMeta | The AbortOnMeta flag was set and a shell meta character was encoutered.

Definition at line 62 of file kshell.h.

## Function Documentation

QStringList KShell::splitArgs | ( | const QString & | cmd,
|  | int | flags = `0`,
|  | int * | err = `0`
| ) |

Splits `cmd` according to POSIX shell word splitting and quoting rules.

Can optionally perform tilde expansion and/or abort if it finds shell meta characters it cannot process.

Parameters:

  | cmd | the command to split
  | flags | operation flags, see Options
  | err | if not NULL, a status code will be stored at the pointer target, see Errors

Returns:
  a list of unquoted words or an empty list if an error occurred

Definition at line 65 of file kshell.cpp.

References AbortOnMeta, BadQuoting, FoundMeta, homeDir(), QString::isEmpty(), QChar::isSpace(), NoError, TildeExpand, and QChar::unicode().

Referenced by KApplication::invokeMailer().

QString KShell::joinArgs | ( | const QStringList & | args | ) |

Quotes and joins `args` together according to POSIX shell rules.

Parameters:

  | args | a list of strings to quote and join

Returns:
  a command suitable for shell execution

Definition at line 257 of file kshell.cpp.

References QString::append(), QString::isEmpty(), and QString::replace().

QString KShell::joinArgsDQ | ( | const QStringList & | args | ) |

Same as above, but $'' is used instead of '' for the quoting.

The output is suitable for splitArgs(), bash, zsh and possibly other bourne-compatible shells, but not for plain sh. The advantage is, that control characters (ASCII less than 32) are escaped into human-readable strings.

Parameters:

  | args | a list of strings to quote and join

Returns:
  a command suitable for shell execution

Definition at line 311 of file kshell.cpp.

References QString::append(), QString::isEmpty(), and QString::unicode().

QString KShell::joinArgs | ( | const char *const * | argv,
|  | int | argc = `-1`
| ) |

Quotes and joins `argv` together according to POSIX shell rules.

Parameters:

  | argv | an array of c strings to quote and join. The strings are expected to be in local-8-bit encoding.
  | argc | maximal number of strings in `argv`. if not supplied, `argv` must be null-terminated.

Returns:
  a command suitable for shell execution

Definition at line 283 of file kshell.cpp.

References QString::append(), QString::isEmpty(), QString::length(), QString::replace(), and QString::unicode().

QString KShell::tildeExpand | ( | const QString & | path | ) |

Performs tilde expansion on `path`.

Interprets "~/path" and "~user/path".

Parameters:

  | path | the path to tilde-expand

Returns:
  the expanded path

Definition at line 355 of file kshell.cpp.

References QString::find(), homeDir(), and QString::isNull().

Referenced by KStandardDirs::addKDEDefaults().

QString KShell::homeDir | ( | const QString & | user | ) |

Obtain a `user's` home directory.

Parameters:

  | user | The name of the user whose home dir should be obtained. An empty string denotes the current user.

Returns:
  The user's home directory.

Definition at line 369 of file kshell.cpp.

References QFile::decodeName().

Referenced by splitArgs(), and tildeExpand().

This file is part of the documentation for kdecore Library Version 3.4.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat Jun 11 20:19:29 2005 by doxygen 1.4.1 written by Dimitri van Heesch, © 1997-2003