# Namespace KShell

Module | kdecore
Namespace | KShell

\namespace KShell Emulates some basic system shell functionality.

See also KStringHandler

### enums

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

enum details

### methods

- joinArgs (args)

  returns QString

  Argument | Type | Default
  --- | --- | ---
  args | QStringList |

  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.

  args - a list of strings to quote and join Returns a command suitable for shell execution

- quoteArg (arg)

  returns QString

  Argument | Type | Default
  --- | --- | ---
  arg | QString |

  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.

  arg - the argument to quote Returns the quoted argument

- splitArgs (cmd, flags, err)

  returns QStringList

  Argument | Type | Default
  --- | --- | ---
  cmd | QString |
  flags | KShell.Options | KShell.NoOptions
  err | KShell.Errors | 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.

  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

- tildeExpand (path)

  returns QString

  Argument | Type | Default
  --- | --- | ---
  path | QString |

  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.

  path - the path to tilde-expand Returns the expanded path

### enums - detail

- Errors { NoError, BadQuoting, FoundMeta }

  Success.

  | NoError | - 0 | - |
  | BadQuoting | - | - |
  | FoundMeta | - | - |

- Option { NoOptions, TildeExpand, AbortOnMeta }

  Flags for splitArgs().

  | NoOptions | - 0 | - |
  | TildeExpand | - 1 | - |
  | AbortOnMeta | - 2 | - |