KDE 4.9 PyKDE API Reference

- KDE's Python API

# KShell Namespace Reference

`from PyKDE4.kdecore.KShell import *`

## Detailed Description

Emulates some basic system shell functionality.

See also:
  KStringHandler

## Enumerations

Errors | { NoError, BadQuoting, FoundMeta }
Option | { NoOptions, TildeExpand, AbortOnMeta }

## Functions

QString | joinArgs (QStringList args)
QString | quoteArg (QString arg)
QStringList | splitArgs (QString cmd, KShell.Options flags=KShell.NoOptions, KShell.Errors err=0)
QString | tildeExpand (QString path)

## Enumeration Documentation

Errors

Status codes from splitArgs()

Enumerator:

  NoError = 0 |
  BadQuoting |
  FoundMeta |

Option

Flags for splitArgs().

Enumerator:

  NoOptions = 0 |
  TildeExpand = 1 |
  AbortOnMeta = 2 |

## Function Documentation

QString joinArgs | ( | QStringList | args
| ) |  |  |

Quotes and joins args together according to system shell rules.

If the output is fed back into splitArgs(), the AbortOnMeta flag needs to be used on Windows. On *NIX, no such requirement exists.

See quoteArg() for more info.

Parameters:

  | args | a list of strings to quote and join

Returns:
  a command suitable for shell execution

QString quoteArg | ( | QString | arg
| ) |  |  |

Quotes arg according to system shell rules.

This function can be used to quote an argument string such that the shell processes it properly. This is e.g. necessary for user-provided file names which may contain spaces or quotes. It also prevents expansion of wild cards and environment variables.

On *NIX, the output is POSIX shell compliant. On Windows, it is compliant with the argument splitting code of the Microsoft C runtime and the cmd shell used together. Occurrences of the percent sign are replaced with \%PERCENT_SIGN% to prevent spurious variable expansion; related KDE functions are prepared for this.

Parameters:

  | arg | the argument to quote

Returns:
  the quoted argument

QStringList splitArgs | ( | QString | cmd,
|  | KShell.Options | flags=KShell.NoOptions,
|  | KShell.Errors | err=0
| ) |  |  |

Splits cmd according to system shell word splitting and quoting rules. Can optionally perform tilde expansion and/or abort if it finds shell meta characters it cannot process.

On *NIX the behavior is based on the POSIX shell and bash: - Whitespace splits tokens - The backslash quotes the following character - A string enclosed in single quotes is not split. No shell meta characters are interpreted. - A string enclosed in double quotes is not split. Within the string, the backslash quotes shell meta characters - if it is followed by a "meaningless" character, the backslash is output verbatim. - A string enclosed in $'' is not split. Within the string, the backslash has a similar meaning to the one in C strings. Consult the bash manual for more information.

On Windows, the behavior is defined by the Microsoft C runtime. Qt and many other implementations comply with this standard, but many do not. - Whitespace splits tokens - A string enclosed in double quotes is not split - 2N double quotes within a quoted string yield N literal quotes. This is not documented on MSDN. - Backslashes have special semantics iff they are followed by a double quote: - 2N backslashes + double quote => N backslashes and begin/end quoting - 2N+1 backslashes + double quote => N backslashes + literal quote

If AbortOnMeta is used on Windows, this function applies cmd shell semantics before proceeding with word splitting: - Cmd ignores all special chars between double quotes. Note that the quotes are not removed at this stage - the tokenization rules described above still apply. - The circumflex is the escape char for everything including itself.

Parameters:

  | cmd | the command to split
  | flags | operation flags, see Option
  | 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

QString tildeExpand | ( | QString | path
| ) |  |  |

Performs tilde expansion on path. Interprets "~/path" and "~user/path". If the path starts with an escaped tilde ("\~" on UNIX, "^~" on Windows), the escape char is removed and the path is returned as is.

Note that if path starts with a tilde but cannot be properly expanded, this function will return an empty string.

Parameters:

  | path | the path to tilde-expand

Returns:
  the expanded path