`pystring` (OpScript) ===================== .. lua:module:: pystring .. lua:function:: capitalize(string) Return a copy of the string with its first character capitalized and the rest lowercased. .. lua:function:: center(string str, int width) Return new string centered in a string of length *width*. Padding is done with spaces. .. lua:function:: count(string str, string substr, string substr, [int start, \ int end]) Return the number of non-overlapping occurrences of substring *sub* in the range [*start*, *end*]. Optional arguments start and end are interpreted as in slice notation. .. lua:function:: endswith(string str, string suffix, [int start, int end]) Return ``true`` if the string ends with the specified *suffix*, otherwise return ``false``. With optional *start*, test beginning at that position. With optional *end*, stop comparing at that position. .. lua:function:: expandtabs(string str, [int tabsize]) Return a copy of the string where all tab characters are replaced by one or more spaces, depending on the current column and the given tab size. Tab positions occur every *tabsize* characters (default is 8, giving tab positions at columns 0, 8, 16 and so on). .. lua:function:: find(string str, string sub, [int start, int end]) Return the lowest index in the string where substring *sub* is found, such that *sub* is contained in the slice ``s[start:end]``. Optional arguments *start* and *end* are interpreted as in slice notation. Return ``-1`` if *sub* is not found. .. lua:function:: index(string str, string sub, [int start, int end]) Same as find. Does not throw exception on failure (unlike Python). .. lua:function:: isalnum(string str) Return ``true`` if all characters in the string are alphanumeric and there is at least one character, ``false`` otherwise. .. lua:function:: isalpha(string str) Return ``true`` if all characters in the string are alphabetic and there is at least one character, ``false`` otherwise. .. lua:function:: isdigit(string str) Return ``true`` if all characters in the string are digits and there is at least one character, ``false`` otherwise. .. lua:function:: islower(string str) Return ``true`` if all cased characters in the string are lowercase and there is at least one cased character, ``false`` otherwise. .. lua:function:: isspace(string str) Return ``true`` if there are only whitespace characters in the string and there is at least one character, ``false`` otherwise .. lua:function:: istitle(string str) Return ``true`` if the string is a titlecased string and there is at least one character, for example uppercase characters may only follow uncased characters and lowercase characters only cased ones. Return ``false`` otherwise. .. lua:function:: isupper(string str) Return ``true`` if all cased characters [in the string are uppercase and there is at least one cased character, ``false`` otherwise. .. lua:function:: join(string separator, list seq) Return a string which is the concatenation of the strings in *seq*. The separator between elements is given by the *separator* argument. .. lua:function:: ljust(string str, int width) Return the string left justified in a string of length *width*. Padding is done with spaces. .. lua:function:: lower(string str) Return a copy of the string with all the cased characters converted to lowercase. .. lua:function:: lstrip(string str, string chars) Return a copy of the string with leading characters removed. The *chars* argument is a string specifying the set of characters to be removed. If omitted, the *chars* argument defaults to removing whitespace. The *chars* argument is not a prefix; rather, all combinations of its values are stripped. .. lua:function:: mul(string str, int n) Return a new string with the *str* argument concatenated *n* times. .. lua:function:: partition(string str, int sep) Split the string at the first occurrence of *sep*, and return a list table with three values containing the part before the separator, the separator itself, and the part after the separator. If the separator is not found, return a list table containing the string itself, followed by two empty strings. .. lua:function:: replace(string str, string oldstr, string newstr, \ [int count = -1]) Return a copy of the string with all occurrences of substring *old* replaced by *new*. If the optional argument *count* is given, only the first *count* occurrences are replaced. .. lua:function:: rfind(string str, string sub, [int start, int end]) Return the highest index in the string where substring *sub* is found, such that *sub* is contained within ``s[start:end]``. Optional arguments *start* and *end* are interpreted as in slice notation. Return ``-1`` on failure. .. lua:function:: rindex(string str, string sub, [int start, int end]) Like pystring.rfind(). .. lua:function:: rjust(string str, int width) Return the string right justified in a string of length *width*. Padding is done with spaces. The original string is returned if *width* is less than or equal to ``#s``. .. lua:function:: rpartition(string str, string sep) Split the string at the last occurrence of *sep*, and return a list table with three values containing the part before the separator, the separator itself, and the part after the separator. If the separator is not found, return a list table containing two empty strings, followed by the string itself. .. lua:function:: rsplit(string str, [string sep = "", int maxsplits = -1]) Return a list of the words in the string, using *sep* as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* ones. If *sep* is not specified, any whitespace string is a separator. Except for splitting from the right, :func:`rsplit` behaves like :func:`split` which is described in detail below. .. lua:function:: rstrip(string str, [string chars = ""]) Return a copy of the string with trailing characters removed. The *chars* argument is a string specifying the set of characters to be removed. If omitted, the *chars* argument defaults to removing whitespace. The *chars* argument is not a suffix; rather, all combinations of its values are stripped. .. lua:function:: slice(string str, [int start, int end]) Return substring of *str* using equivalent of python slice ``str[start:end]``. .. lua:function:: split(string str, [string sep = "", int maxsplits = -1]) Return a list of the words in the string, using *sep* as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not specified or ``-1``, then there is no limit on the number of splits (all possible splits are made). If *sep* is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, ``pystring.split('1,,2', ',')`` returns ``{'1', '', '2'}``). The *sep* argument may consist of multiple characters (for example, ``pystring.split('123', '')`` returns ``{'1', '2', '3'}``). Splitting an empty string with a specified separator returns ``{''}``. If *sep* is not specified, a different splitting algorithm is applied: runs of consecutive whitespace are regarded as a single separator, and the result will contain no empty strings at the start or end if the string has leading or trailing whitespace. Consequently, splitting an empty string or a string consisting of just whitespace with no separator returns ``{}``. .. lua:function:: splitlines(string str, [boolean keepends = false]) Return a list of the lines in *str*, breaking at line boundaries. This method uses the universal newlines approach to splitting lines. Line breaks are not included in the resulting list unless *keepends* is given and true. For example, ``pystring.splitlines('ab c\n\nde fg\rkl\r\n')`` returns ``{'ab c', '', 'de fg', 'kl'}``, while the same call with ``keepends=true`` returns ``{'ab c\n', '\n', 'de fg\r', 'kl\r\n'}``. Unlike :func:`split` when a delimiter string *sep* is given, this method returns an empty list for the empty string, and a terminal line break does not result in an extra line. .. lua:function:: startswith(string str, string prefix, [int start, int end]) Return ``true`` if *str* starts with the *prefix*, otherwise return ``false``. With optional *start*, test string beginning at that position. With optional *end*, stop comparing string at that position. .. lua:function:: strip(string str, [string chars]) Return a copy of *str* with the leading and trailing characters removed. The *chars* argument is a string specifying the set of characters to be removed. If omitted, the *chars* argument defaults to removing whitespace. The *chars* argument is not a prefix or suffix; rather, all combinations of its values are stripped: .. lua:function:: swapcase(string str) Return a copy of the string with uppercase characters converted to lowercase and vice versa. .. lua:function:: title(string str) Return a titlecased version of the string where words start with an uppercase character and the remaining characters are lowercase. The algorithm uses a simple language-independent definition of a word as groups of consecutive letters. The definition works in many contexts but it means that apostrophes in contractions and possessives form word boundaries, which may not be the desired result. .. lua:function:: translate(string str, string chartable, [string deletechars]) Return a copy of the string where all characters occurring in the optional argument *deletechars* are removed, and the remaining characters have been mapped through the given translation table, which must be a string of length 256. .. lua:function:: upper(string str) Return a copy of the string with all the cased characters converted to uppercase. Note that ``pystring.isupper(pystring.upper(str))`` might be ``false`` if ``s`` contains uncased characters .. lua:function:: zfill(string str, int width) Return a copy of the numeric *str* left filled with zeros in a string of length *width*. A sign prefix is handled correctly. A copy of the original string is returned if *width* is less than or equal to ``#str``. Path Manipulation ----------------- .. lua:currentmodule:: pystring.os .. lua:data:: sep The character used by the operating system to separate pathname components. This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this is not sufficient to be able to parse or concatenate pathnames — use :lua:func:`path.split()` and :lua:func:`path.join()` — but it is occasionally useful. Also available via :lua:mod:`os.path`. .. lua:data:: pathsep The character conventionally used by the operating system to separate search path components (as in ``PATH``), such as ``':'`` for POSIX or ``';'`` for Windows. Also available via :lua:mod:`os.path`. .. lua:currentmodule:: pystring.os.path .. lua:function:: basename(string path) Return the base name of pathname *path*. This is the second half of the pair returned by ``split(path)``. Note that the result of this function is different from the Unix :program:`basename` program; where basename for ``'/foo/bar/'`` returns ``'bar'``, the :lua:func:`basename` function returns an empty string (``''``). .. lua:function:: dirname(string path) Return the directory name of pathname *path*. This is the first half of the pair returned by :lua:func:`split`. .. lua:function:: isabs(string path) Return ``true`` if *path* is an absolute pathname. On Unix, that means it begins with a slash, on Windows that it begins with a (back)slash after chopping off a potential drive letter. .. lua:function:: abspath(string path, [string cwd]) Return a normalized absolutized version of the pathname *path*. The optional *cwd* argument specifies the directory *path* is relative to; it defaults to the current working directory. .. lua:function:: join(string path1, [string path2...]) Join one or more path components intelligently. If any component is an absolute path, all previous components (on Windows, including the previous drive letter, if there was one) are thrown away, and joining continues. The return value is the concatenation of *path1*, and optionally *path2*, etc., with exactly one directory separator (:lua:data:`os.sep`) inserted between components, unless *path2* is empty. Note that on Windows, since there is a current directory for each drive, ``os.path.join("c:", "foo")`` represents a path relative to the current directory on drive ``'c:'`` (``'c:foo'``), not ``'c:\foo'``. .. lua:function:: normpath(string path) Normalize a pathname. This collapses redundant separators and up-level references so that ``'A//B'``, ``'A/B/'``, ``'A/./B'`` and ``'A/foo/../B'`` all become ``'A/B'``. It does not normalize the case. On Windows, it converts forward slashes to backward slashes. It should be understood that this may change the meaning of the path if it contains symbolic links! .. lua:function:: split(string path) Split the pathname *path* into a pair, ``head, tail`` where *tail* is the last pathname component and *head* is everything leading up to that. The *tail* part will never contain a slash; if *path* ends in a slash, *tail* will be empty. If there is no slash in *path*, *head* will be empty. If *path* is empty, both *head* and *tail* are empty. Trailing slashes are stripped from *head* unless it is the root (one or more slashes only). In all cases, ``join(head, tail)`` returns a path to the same location as *path* (but the strings may differ). .. lua:function:: splitdrive(string path) Split the pathname *path* into a pair ``drive, tail`` where drive is either a drive specification or the empty string. On systems which do not use drive specifications, *drive* will always be the empty string. In all cases, ``drive .. tail`` will be the same as *path*. .. lua:function:: splitext(string path) Split the pathname *path* into a pair ``root, ext`` such that ``root .. ext == path``, and *ext* is empty or begins with a period and contains at most one period. Leading periods on the basename are ignored; ``splitext('.cshrc')`` returns ``'.cshrc', ''``. .. lua:function:: expanduser(string path) Expand paths beginning with ``'~'`` or ``'~user'``. ``'~'`` means the current user's home directory; ``'~user'`` means that user's home directory. If the path doesn't begin with ``'~'``, or if the user or their home directory is unknown, the path is returned unchanged (leaving error reporting to whatever function is called with the expanded path as argument). .. lua:function:: expandvars(string path) Return the argument with environment variables expanded. Substrings of the form ``$name`` or ``${name}`` are replaced by the value of environment variable name. Malformed variable names and references to non-existent variables are left unchanged.