|
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-functions-library-strings"> |
|
<title>lib.strings: string manipulation functions</title> |
|
<section xml:id="function-library-lib.strings.concatStrings"> |
|
<title><literal>lib.strings.concatStrings</literal></title> |
|
<para> |
|
<literal>concatStrings :: [string] -> string</literal> |
|
</para> |
|
<para> |
|
Concatenate a list of strings. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.concatStrings"> |
|
<title>lib.strings.concatStrings usage example</title> |
|
<programlisting language="nix"> |
|
concatStrings ["foo" "bar"] |
|
=> "foobar" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.concatMapStrings"> |
|
<title><literal>lib.strings.concatMapStrings</literal></title> |
|
<para> |
|
<literal>concatMapStrings :: (a -> string) -> [a] -> string</literal> |
|
</para> |
|
<para> |
|
Map a function over a list and concatenate the resulting strings. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>f</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.concatMapStrings"> |
|
<title>lib.strings.concatMapStrings usage example</title> |
|
<programlisting language="nix"> |
|
concatMapStrings (x: "a" + x) ["foo" "bar"] |
|
=> "afooabar" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.concatImapStrings"> |
|
<title><literal>lib.strings.concatImapStrings</literal></title> |
|
<para> |
|
<literal>concatImapStrings :: (int -> a -> string) -> [a] -> string</literal> |
|
</para> |
|
<para> |
|
Like <literal>concatMapStrings</literal> except that the f |
|
functions also gets the position as a parameter. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>f</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.concatImapStrings"> |
|
<title>lib.strings.concatImapStrings usage example</title> |
|
<programlisting language="nix"> |
|
concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"] |
|
=> "1-foo2-bar" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.intersperse"> |
|
<title><literal>lib.strings.intersperse</literal></title> |
|
<para> |
|
<literal>intersperse :: a -> [a] -> [a]</literal> |
|
</para> |
|
<para> |
|
Place an element between each element of a list |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>separator</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Separator to add between elements |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Input list |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.intersperse"> |
|
<title>lib.strings.intersperse usage example</title> |
|
<programlisting language="nix"> |
|
intersperse "/" ["usr" "local" "bin"] |
|
=> ["usr" "/" "local" "/" "bin"]. |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.concatStringsSep"> |
|
<title><literal>lib.strings.concatStringsSep</literal></title> |
|
<para> |
|
<literal>concatStringsSep :: string -> [string] -> string</literal> |
|
</para> |
|
<para> |
|
Concatenate a list of strings with a separator between each |
|
element |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.concatStringsSep"> |
|
<title>lib.strings.concatStringsSep usage example</title> |
|
<programlisting language="nix"> |
|
concatStringsSep "/" ["usr" "local" "bin"] |
|
=> "usr/local/bin" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.concatMapStringsSep"> |
|
<title><literal>lib.strings.concatMapStringsSep</literal></title> |
|
<para> |
|
<literal>concatMapStringsSep :: string -> (a -> string) -> [a] -> string</literal> |
|
</para> |
|
<para> |
|
Maps a function over a list of strings and then concatenates the |
|
result with the specified separator interspersed between elements. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>sep</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Separator to add between elements |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>f</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function to map over the list |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
List of input strings |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.concatMapStringsSep"> |
|
<title>lib.strings.concatMapStringsSep usage example</title> |
|
<programlisting language="nix"> |
|
concatMapStringsSep "-" (x: toUpper x) ["foo" "bar" "baz"] |
|
=> "FOO-BAR-BAZ" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.concatImapStringsSep"> |
|
<title><literal>lib.strings.concatImapStringsSep</literal></title> |
|
<para> |
|
<literal>concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string</literal> |
|
</para> |
|
<para> |
|
Same as <literal>concatMapStringsSep</literal>, but the mapping |
|
function additionally receives the position of its argument. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>sep</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Separator to add between elements |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>f</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function that receives elements and their positions |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
List of input strings |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.concatImapStringsSep"> |
|
<title>lib.strings.concatImapStringsSep usage example</title> |
|
<programlisting language="nix"> |
|
concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ] |
|
=> "6-3-2" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.concatLines"> |
|
<title><literal>lib.strings.concatLines</literal></title> |
|
<para> |
|
<literal>concatLines :: [string] -> string</literal> |
|
</para> |
|
<para> |
|
Concatenate a list of strings, adding a newline at the end of each |
|
one. Defined as |
|
<literal>concatMapStrings (s: s + "\n")</literal>. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.concatLines"> |
|
<title>lib.strings.concatLines usage example</title> |
|
<programlisting language="nix"> |
|
concatLines [ "foo" "bar" ] |
|
=> "foo\nbar\n" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.makeSearchPath"> |
|
<title><literal>lib.strings.makeSearchPath</literal></title> |
|
<para> |
|
<literal>makeSearchPath :: string -> [string] -> string</literal> |
|
</para> |
|
<para> |
|
Construct a Unix-style, colon-separated search path consisting of |
|
the given <literal>subDir</literal> appended to each of the given |
|
paths. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>subDir</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Directory name to append |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>paths</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
List of base paths |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.makeSearchPath"> |
|
<title>lib.strings.makeSearchPath usage example</title> |
|
<programlisting language="nix"> |
|
makeSearchPath "bin" ["/root" "/usr" "/usr/local"] |
|
=> "/root/bin:/usr/bin:/usr/local/bin" |
|
makeSearchPath "bin" [""] |
|
=> "/bin" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.makeSearchPathOutput"> |
|
<title><literal>lib.strings.makeSearchPathOutput</literal></title> |
|
<para> |
|
<literal>string -> string -> [package] -> string</literal> |
|
</para> |
|
<para> |
|
Construct a Unix-style search path by appending the given |
|
<literal>subDir</literal> to the specified |
|
<literal>output</literal> of each of the packages. If no output by |
|
the given name is found, fallback to <literal>.out</literal> and |
|
then to the default. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>output</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Package output to use |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>subDir</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Directory name to append |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>pkgs</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
List of packages |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.makeSearchPathOutput"> |
|
<title>lib.strings.makeSearchPathOutput usage example</title> |
|
<programlisting language="nix"> |
|
makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ] |
|
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.makeLibraryPath"> |
|
<title><literal>lib.strings.makeLibraryPath</literal></title> |
|
<para> |
|
Construct a library search path (such as RPATH) containing the |
|
libraries for a set of packages |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.makeLibraryPath"> |
|
<title>lib.strings.makeLibraryPath usage example</title> |
|
<programlisting language="nix"> |
|
makeLibraryPath [ "/usr" "/usr/local" ] |
|
=> "/usr/lib:/usr/local/lib" |
|
pkgs = import <nixpkgs> { } |
|
makeLibraryPath [ pkgs.openssl pkgs.zlib ] |
|
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.makeBinPath"> |
|
<title><literal>lib.strings.makeBinPath</literal></title> |
|
<para> |
|
Construct a binary search path (such as $PATH) containing the |
|
binaries for a set of packages. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.makeBinPath"> |
|
<title>lib.strings.makeBinPath usage example</title> |
|
<programlisting language="nix"> |
|
makeBinPath ["/root" "/usr" "/usr/local"] |
|
=> "/root/bin:/usr/bin:/usr/local/bin" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.normalizePath"> |
|
<title><literal>lib.strings.normalizePath</literal></title> |
|
<para> |
|
<literal>normalizePath :: string -> string</literal> |
|
</para> |
|
<para> |
|
Normalize path, removing extraneous /s |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>s</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.normalizePath"> |
|
<title>lib.strings.normalizePath usage example</title> |
|
<programlisting language="nix"> |
|
normalizePath "/a//b///c/" |
|
=> "/a/b/c/" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.optionalString"> |
|
<title><literal>lib.strings.optionalString</literal></title> |
|
<para> |
|
<literal>optionalString :: bool -> string -> string</literal> |
|
</para> |
|
<para> |
|
Depending on the boolean `cond’, return either the given string or |
|
the empty string. Useful to concatenate against a bigger string. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>cond</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Condition |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>string</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
String to return if condition is true |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.optionalString"> |
|
<title>lib.strings.optionalString usage example</title> |
|
<programlisting language="nix"> |
|
optionalString true "some-string" |
|
=> "some-string" |
|
optionalString false "some-string" |
|
=> "" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.hasPrefix"> |
|
<title><literal>lib.strings.hasPrefix</literal></title> |
|
<para> |
|
<literal>hasPrefix :: string -> string -> bool</literal> |
|
</para> |
|
<para> |
|
Determine whether a string has given prefix. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>pref</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Prefix to check for |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>str</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Input string |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.hasPrefix"> |
|
<title>lib.strings.hasPrefix usage example</title> |
|
<programlisting language="nix"> |
|
hasPrefix "foo" "foobar" |
|
=> true |
|
hasPrefix "foo" "barfoo" |
|
=> false |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.hasSuffix"> |
|
<title><literal>lib.strings.hasSuffix</literal></title> |
|
<para> |
|
<literal>hasSuffix :: string -> string -> bool</literal> |
|
</para> |
|
<para> |
|
Determine whether a string has given suffix. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>suffix</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Suffix to check for |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>content</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Input string |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.hasSuffix"> |
|
<title>lib.strings.hasSuffix usage example</title> |
|
<programlisting language="nix"> |
|
hasSuffix "foo" "foobar" |
|
=> false |
|
hasSuffix "foo" "barfoo" |
|
=> true |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.hasInfix"> |
|
<title><literal>lib.strings.hasInfix</literal></title> |
|
<para> |
|
<literal>hasInfix :: string -> string -> bool</literal> |
|
</para> |
|
<para> |
|
Determine whether a string contains the given infix |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>infix</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>content</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.hasInfix"> |
|
<title>lib.strings.hasInfix usage example</title> |
|
<programlisting language="nix"> |
|
hasInfix "bc" "abcd" |
|
=> true |
|
hasInfix "ab" "abcd" |
|
=> true |
|
hasInfix "cd" "abcd" |
|
=> true |
|
hasInfix "foo" "abcd" |
|
=> false |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.stringToCharacters"> |
|
<title><literal>lib.strings.stringToCharacters</literal></title> |
|
<para> |
|
<literal>stringToCharacters :: string -> [string]</literal> |
|
</para> |
|
<para> |
|
Convert a string to a list of characters (i.e. singleton strings). |
|
This allows you to, e.g., map a function over each character. |
|
However, note that this will likely be horribly inefficient; Nix |
|
is not a general purpose programming language. Complex string |
|
manipulations should, if appropriate, be done in a derivation. |
|
Also note that Nix treats strings as a list of bytes and thus |
|
doesn’t handle unicode. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>s</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.stringToCharacters"> |
|
<title>lib.strings.stringToCharacters usage example</title> |
|
<programlisting language="nix"> |
|
stringToCharacters "" |
|
=> [ ] |
|
stringToCharacters "abc" |
|
=> [ "a" "b" "c" ] |
|
stringToCharacters "🦄" |
|
=> [ "�" "�" "�" "�" ] |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.stringAsChars"> |
|
<title><literal>lib.strings.stringAsChars</literal></title> |
|
<para> |
|
<literal>stringAsChars :: (string -> string) -> string -> string</literal> |
|
</para> |
|
<para> |
|
Manipulate a string character by character and replace them by |
|
strings before concatenating the results. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>f</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function to map over each individual character |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>s</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Input string |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.stringAsChars"> |
|
<title>lib.strings.stringAsChars usage example</title> |
|
<programlisting language="nix"> |
|
stringAsChars (x: if x == "a" then "i" else x) "nax" |
|
=> "nix" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.charToInt"> |
|
<title><literal>lib.strings.charToInt</literal></title> |
|
<para> |
|
<literal>charToInt :: string -> int</literal> |
|
</para> |
|
<para> |
|
Convert char to ascii value, must be in printable range |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>c</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.charToInt"> |
|
<title>lib.strings.charToInt usage example</title> |
|
<programlisting language="nix"> |
|
charToInt "A" |
|
=> 65 |
|
charToInt "(" |
|
=> 40 |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escape"> |
|
<title><literal>lib.strings.escape</literal></title> |
|
<para> |
|
<literal>escape :: [string] -> string -> string</literal> |
|
</para> |
|
<para> |
|
Escape occurrence of the elements of <literal>list</literal> in |
|
<literal>string</literal> by prefixing it with a backslash. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.escape"> |
|
<title>lib.strings.escape usage example</title> |
|
<programlisting language="nix"> |
|
escape ["(" ")"] "(foo)" |
|
=> "\\(foo\\)" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeC"> |
|
<title><literal>lib.strings.escapeC</literal></title> |
|
<para> |
|
<literal>escapeC = [string] -> string -> string</literal> |
|
</para> |
|
<para> |
|
Escape occurrence of the element of <literal>list</literal> in |
|
<literal>string</literal> by converting to its ASCII value and |
|
prefixing it with \x. Only works for printable ascii characters. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>list</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.escapeC"> |
|
<title>lib.strings.escapeC usage example</title> |
|
<programlisting language="nix"> |
|
escapeC [" "] "foo bar" |
|
=> "foo\\x20bar" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeURL"> |
|
<title><literal>lib.strings.escapeURL</literal></title> |
|
<para> |
|
<literal>escapeURL :: string -> string</literal> |
|
</para> |
|
<para> |
|
Escape the string so it can be safely placed inside a URL query. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.escapeURL"> |
|
<title>lib.strings.escapeURL usage example</title> |
|
<programlisting language="nix"> |
|
escapeURL "foo/bar baz" |
|
=> "foo%2Fbar%20baz" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeShellArg"> |
|
<title><literal>lib.strings.escapeShellArg</literal></title> |
|
<para> |
|
<literal>escapeShellArg :: string -> string</literal> |
|
</para> |
|
<para> |
|
Quote string to be used safely within the Bourne shell. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>arg</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.escapeShellArg"> |
|
<title>lib.strings.escapeShellArg usage example</title> |
|
<programlisting language="nix"> |
|
escapeShellArg "esc'ape\nme" |
|
=> "'esc'\\''ape\nme'" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeShellArgs"> |
|
<title><literal>lib.strings.escapeShellArgs</literal></title> |
|
<para> |
|
<literal>escapeShellArgs :: [string] -> string</literal> |
|
</para> |
|
<para> |
|
Quote all arguments to be safely passed to the Bourne shell. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.escapeShellArgs"> |
|
<title>lib.strings.escapeShellArgs usage example</title> |
|
<programlisting language="nix"> |
|
escapeShellArgs ["one" "two three" "four'five"] |
|
=> "'one' 'two three' 'four'\\''five'" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.isValidPosixName"> |
|
<title><literal>lib.strings.isValidPosixName</literal></title> |
|
<para> |
|
<literal>string -> bool</literal> |
|
</para> |
|
<para> |
|
Test whether the given name is a valid POSIX shell variable name. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>name</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.isValidPosixName"> |
|
<title>lib.strings.isValidPosixName usage example</title> |
|
<programlisting language="nix"> |
|
isValidPosixName "foo_bar000" |
|
=> true |
|
isValidPosixName "0-bad.jpg" |
|
=> false |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.toShellVar"> |
|
<title><literal>lib.strings.toShellVar</literal></title> |
|
<para> |
|
<literal>string -> (string | listOf string | attrsOf string) -> string</literal> |
|
</para> |
|
<para> |
|
Translate a Nix value into a shell variable declaration, with |
|
proper escaping. |
|
</para> |
|
<para> |
|
The value can be a string (mapped to a regular variable), a list |
|
of strings (mapped to a Bash-style array) or an attribute set of |
|
strings (mapped to a Bash-style associative array). Note that |
|
<quote>string</quote> includes string-coercible values like paths |
|
or derivations. |
|
</para> |
|
<para> |
|
Strings are translated into POSIX sh-compatible code; lists and |
|
attribute sets assume a shell that understands Bash syntax (e.g. |
|
Bash or ZSH). |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>name</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>value</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.toShellVar"> |
|
<title>lib.strings.toShellVar usage example</title> |
|
<programlisting language="nix"> |
|
'' |
|
${toShellVar "foo" "some string"} |
|
[[ "$foo" == "some string" ]] |
|
'' |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.toShellVars"> |
|
<title><literal>lib.strings.toShellVars</literal></title> |
|
<para> |
|
<literal>attrsOf (string | listOf string | attrsOf string) -> string</literal> |
|
</para> |
|
<para> |
|
Translate an attribute set into corresponding shell variable |
|
declarations using <literal>toShellVar</literal>. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>vars</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.toShellVars"> |
|
<title>lib.strings.toShellVars usage example</title> |
|
<programlisting language="nix"> |
|
let |
|
foo = "value"; |
|
bar = foo; |
|
in '' |
|
${toShellVars { inherit foo bar; }} |
|
[[ "$foo" == "$bar" ]] |
|
'' |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeNixString"> |
|
<title><literal>lib.strings.escapeNixString</literal></title> |
|
<para> |
|
<literal>string -> string</literal> |
|
</para> |
|
<para> |
|
Turn a string into a Nix expression representing that string |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>s</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.escapeNixString"> |
|
<title>lib.strings.escapeNixString usage example</title> |
|
<programlisting language="nix"> |
|
escapeNixString "hello\${}\n" |
|
=> "\"hello\\\${}\\n\"" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeRegex"> |
|
<title><literal>lib.strings.escapeRegex</literal></title> |
|
<para> |
|
<literal>string -> string</literal> |
|
</para> |
|
<para> |
|
Turn a string into an exact regular expression |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.escapeRegex"> |
|
<title>lib.strings.escapeRegex usage example</title> |
|
<programlisting language="nix"> |
|
escapeRegex "[^a-z]*" |
|
=> "\\[\\^a-z]\\*" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeNixIdentifier"> |
|
<title><literal>lib.strings.escapeNixIdentifier</literal></title> |
|
<para> |
|
<literal>string -> string</literal> |
|
</para> |
|
<para> |
|
Quotes a string if it can’t be used as an identifier directly. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>s</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.escapeNixIdentifier"> |
|
<title>lib.strings.escapeNixIdentifier usage example</title> |
|
<programlisting language="nix"> |
|
escapeNixIdentifier "hello" |
|
=> "hello" |
|
escapeNixIdentifier "0abc" |
|
=> "\"0abc\"" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.escapeXML"> |
|
<title><literal>lib.strings.escapeXML</literal></title> |
|
<para> |
|
<literal>string -> string</literal> |
|
</para> |
|
<para> |
|
Escapes a string such that it is safe to include verbatim in an |
|
XML document. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.escapeXML"> |
|
<title>lib.strings.escapeXML usage example</title> |
|
<programlisting language="nix"> |
|
escapeXML ''"test" 'test' < & >'' |
|
=> "&quot;test&quot; &apos;test&apos; &lt; &amp; &gt;" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.toLower"> |
|
<title><literal>lib.strings.toLower</literal></title> |
|
<para> |
|
<literal>toLower :: string -> string</literal> |
|
</para> |
|
<para> |
|
Converts an ASCII string to lower-case. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.toLower"> |
|
<title>lib.strings.toLower usage example</title> |
|
<programlisting language="nix"> |
|
toLower "HOME" |
|
=> "home" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.toUpper"> |
|
<title><literal>lib.strings.toUpper</literal></title> |
|
<para> |
|
<literal>toUpper :: string -> string</literal> |
|
</para> |
|
<para> |
|
Converts an ASCII string to upper-case. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.toUpper"> |
|
<title>lib.strings.toUpper usage example</title> |
|
<programlisting language="nix"> |
|
toUpper "home" |
|
=> "HOME" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.addContextFrom"> |
|
<title><literal>lib.strings.addContextFrom</literal></title> |
|
<para> |
|
Appends string context from another string. This is an |
|
implementation detail of Nix and should be used carefully. |
|
</para> |
|
<para> |
|
Strings in Nix carry an invisible <literal>context</literal> which |
|
is a list of strings representing store paths. If the string is |
|
later used in a derivation attribute, the derivation will properly |
|
populate the inputDrvs and inputSrcs. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>a</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>b</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.addContextFrom"> |
|
<title>lib.strings.addContextFrom usage example</title> |
|
<programlisting language="nix"> |
|
pkgs = import <nixpkgs> { }; |
|
addContextFrom pkgs.coreutils "bar" |
|
=> "bar" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.splitString"> |
|
<title><literal>lib.strings.splitString</literal></title> |
|
<para> |
|
Cut a string with a separator and produces a list of strings which |
|
were separated by this separator. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>sep</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>s</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.splitString"> |
|
<title>lib.strings.splitString usage example</title> |
|
<programlisting language="nix"> |
|
splitString "." "foo.bar.baz" |
|
=> [ "foo" "bar" "baz" ] |
|
splitString "/" "/usr/local/bin" |
|
=> [ "" "usr" "local" "bin" ] |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.removePrefix"> |
|
<title><literal>lib.strings.removePrefix</literal></title> |
|
<para> |
|
<literal>string -> string -> string</literal> |
|
</para> |
|
<para> |
|
Return a string without the specified prefix, if the prefix |
|
matches. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>prefix</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Prefix to remove if it matches |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>str</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Input string |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.removePrefix"> |
|
<title>lib.strings.removePrefix usage example</title> |
|
<programlisting language="nix"> |
|
removePrefix "foo." "foo.bar.baz" |
|
=> "bar.baz" |
|
removePrefix "xxx" "foo.bar.baz" |
|
=> "foo.bar.baz" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.removeSuffix"> |
|
<title><literal>lib.strings.removeSuffix</literal></title> |
|
<para> |
|
<literal>string -> string -> string</literal> |
|
</para> |
|
<para> |
|
Return a string without the specified suffix, if the suffix |
|
matches. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>suffix</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Suffix to remove if it matches |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>str</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Input string |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.removeSuffix"> |
|
<title>lib.strings.removeSuffix usage example</title> |
|
<programlisting language="nix"> |
|
removeSuffix "front" "homefront" |
|
=> "home" |
|
removeSuffix "xxx" "homefront" |
|
=> "homefront" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.versionOlder"> |
|
<title><literal>lib.strings.versionOlder</literal></title> |
|
<para> |
|
Return true if string v1 denotes a version older than v2. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>v1</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>v2</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.versionOlder"> |
|
<title>lib.strings.versionOlder usage example</title> |
|
<programlisting language="nix"> |
|
versionOlder "1.1" "1.2" |
|
=> true |
|
versionOlder "1.1" "1.1" |
|
=> false |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.versionAtLeast"> |
|
<title><literal>lib.strings.versionAtLeast</literal></title> |
|
<para> |
|
Return true if string v1 denotes a version equal to or newer than |
|
v2. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>v1</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>v2</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.versionAtLeast"> |
|
<title>lib.strings.versionAtLeast usage example</title> |
|
<programlisting language="nix"> |
|
versionAtLeast "1.1" "1.0" |
|
=> true |
|
versionAtLeast "1.1" "1.1" |
|
=> true |
|
versionAtLeast "1.1" "1.2" |
|
=> false |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.getName"> |
|
<title><literal>lib.strings.getName</literal></title> |
|
<para> |
|
This function takes an argument that’s either a derivation or a |
|
derivation’s <quote>name</quote> attribute and extracts the name |
|
part from that argument. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>x</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.getName"> |
|
<title>lib.strings.getName usage example</title> |
|
<programlisting language="nix"> |
|
getName "youtube-dl-2016.01.01" |
|
=> "youtube-dl" |
|
getName pkgs.youtube-dl |
|
=> "youtube-dl" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.getVersion"> |
|
<title><literal>lib.strings.getVersion</literal></title> |
|
<para> |
|
This function takes an argument that’s either a derivation or a |
|
derivation’s <quote>name</quote> attribute and extracts the |
|
version part from that argument. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>x</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.getVersion"> |
|
<title>lib.strings.getVersion usage example</title> |
|
<programlisting language="nix"> |
|
getVersion "youtube-dl-2016.01.01" |
|
=> "2016.01.01" |
|
getVersion pkgs.youtube-dl |
|
=> "2016.01.01" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.nameFromURL"> |
|
<title><literal>lib.strings.nameFromURL</literal></title> |
|
<para> |
|
Extract name with version from URL. Ask for separator which is |
|
supposed to start extension. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>url</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>sep</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.nameFromURL"> |
|
<title>lib.strings.nameFromURL usage example</title> |
|
<programlisting language="nix"> |
|
nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "-" |
|
=> "nix" |
|
nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "_" |
|
=> "nix-1.7-x86" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.mesonOption"> |
|
<title><literal>lib.strings.mesonOption</literal></title> |
|
<para> |
|
<literal>mesonOption :: string -> string -> string@param feature The feature to be set@param value The desired value</literal> |
|
</para> |
|
<para> |
|
Create a -D<feature>=<value> string that can be passed to typical |
|
Meson invocations. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>feature</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>value</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.mesonOption"> |
|
<title>lib.strings.mesonOption usage example</title> |
|
<programlisting language="nix"> |
|
mesonOption "engine" "opengl" |
|
=> "-Dengine=opengl" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.mesonBool"> |
|
<title><literal>lib.strings.mesonBool</literal></title> |
|
<para> |
|
<literal>mesonBool :: string -> bool -> string@param condition The condition to be made true or false@param flag The controlling flag of the condition</literal> |
|
</para> |
|
<para> |
|
Create a -D<condition>={true,false} string that can be passed to |
|
typical Meson invocations. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>condition</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>flag</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.mesonBool"> |
|
<title>lib.strings.mesonBool usage example</title> |
|
<programlisting language="nix"> |
|
mesonBool "hardened" true |
|
=> "-Dhardened=true" |
|
mesonBool "static" false |
|
=> "-Dstatic=false" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.mesonEnable"> |
|
<title><literal>lib.strings.mesonEnable</literal></title> |
|
<para> |
|
<literal>mesonEnable :: string -> bool -> string@param feature The feature to be enabled or disabled@param flag The controlling flag</literal> |
|
</para> |
|
<para> |
|
Create a -D<feature>={enabled,disabled} string that can be passed |
|
to typical Meson invocations. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>feature</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>flag</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.mesonEnable"> |
|
<title>lib.strings.mesonEnable usage example</title> |
|
<programlisting language="nix"> |
|
mesonEnable "docs" true |
|
=> "-Ddocs=enabled" |
|
mesonEnable "savage" false |
|
=> "-Dsavage=disabled" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.enableFeature"> |
|
<title><literal>lib.strings.enableFeature</literal></title> |
|
<para> |
|
Create an –{enable,disable}-<feat> string that can be passed to |
|
standard GNU Autoconf scripts. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>enable</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>feat</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.enableFeature"> |
|
<title>lib.strings.enableFeature usage example</title> |
|
<programlisting language="nix"> |
|
enableFeature true "shared" |
|
=> "--enable-shared" |
|
enableFeature false "shared" |
|
=> "--disable-shared" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.enableFeatureAs"> |
|
<title><literal>lib.strings.enableFeatureAs</literal></title> |
|
<para> |
|
Create an –{enable-<feat>=<value>,disable-<feat>} string that can |
|
be passed to standard GNU Autoconf scripts. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>enable</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>feat</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>value</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.enableFeatureAs"> |
|
<title>lib.strings.enableFeatureAs usage example</title> |
|
<programlisting language="nix"> |
|
enableFeatureAs true "shared" "foo" |
|
=> "--enable-shared=foo" |
|
enableFeatureAs false "shared" (throw "ignored") |
|
=> "--disable-shared" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.withFeature"> |
|
<title><literal>lib.strings.withFeature</literal></title> |
|
<para> |
|
Create an –{with,without}-<feat> string that can be passed to |
|
standard GNU Autoconf scripts. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>with_</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>feat</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.withFeature"> |
|
<title>lib.strings.withFeature usage example</title> |
|
<programlisting language="nix"> |
|
withFeature true "shared" |
|
=> "--with-shared" |
|
withFeature false "shared" |
|
=> "--without-shared" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.withFeatureAs"> |
|
<title><literal>lib.strings.withFeatureAs</literal></title> |
|
<para> |
|
Create an –{with-<feat>=<value>,without-<feat>} string that can be |
|
passed to standard GNU Autoconf scripts. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>with_</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>feat</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>value</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.withFeatureAs"> |
|
<title>lib.strings.withFeatureAs usage example</title> |
|
<programlisting language="nix"> |
|
withFeatureAs true "shared" "foo" |
|
=> "--with-shared=foo" |
|
withFeatureAs false "shared" (throw "ignored") |
|
=> "--without-shared" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.fixedWidthString"> |
|
<title><literal>lib.strings.fixedWidthString</literal></title> |
|
<para> |
|
<literal>fixedWidthString :: int -> string -> string -> string</literal> |
|
</para> |
|
<para> |
|
Create a fixed width string with additional prefix to match |
|
required width. |
|
</para> |
|
<para> |
|
This function will fail if the input string is longer than the |
|
requested length. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>width</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>filler</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>str</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.fixedWidthString"> |
|
<title>lib.strings.fixedWidthString usage example</title> |
|
<programlisting language="nix"> |
|
fixedWidthString 5 "0" (toString 15) |
|
=> "00015" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.fixedWidthNumber"> |
|
<title><literal>lib.strings.fixedWidthNumber</literal></title> |
|
<para> |
|
Format a number adding leading zeroes up to fixed width. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>width</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>n</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.fixedWidthNumber"> |
|
<title>lib.strings.fixedWidthNumber usage example</title> |
|
<programlisting language="nix"> |
|
fixedWidthNumber 5 15 |
|
=> "00015" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.floatToString"> |
|
<title><literal>lib.strings.floatToString</literal></title> |
|
<para> |
|
Convert a float to a string, but emit a warning when precision is |
|
lost during the conversion |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>float</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.floatToString"> |
|
<title>lib.strings.floatToString usage example</title> |
|
<programlisting language="nix"> |
|
floatToString 0.000001 |
|
=> "0.000001" |
|
floatToString 0.0000001 |
|
=> trace: warning: Imprecise conversion from float to string 0.000000 |
|
"0.000000" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.isCoercibleToString"> |
|
<title><literal>lib.strings.isCoercibleToString</literal></title> |
|
<para> |
|
Soft-deprecated function. While the original implementation is |
|
available as isConvertibleWithToString, consider using |
|
isStringLike instead, if suitable. |
|
</para> |
|
</section> |
|
<section xml:id="function-library-lib.strings.isConvertibleWithToString"> |
|
<title><literal>lib.strings.isConvertibleWithToString</literal></title> |
|
<para> |
|
Check whether a list or other value can be passed to toString. |
|
</para> |
|
<para> |
|
Many types of value are coercible to string this way, including |
|
int, float, null, bool, list of similarly coercible values. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>x</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
</section> |
|
<section xml:id="function-library-lib.strings.isStringLike"> |
|
<title><literal>lib.strings.isStringLike</literal></title> |
|
<para> |
|
Check whether a value can be coerced to a string. The value must |
|
be a string, path, or attribute set. |
|
</para> |
|
<para> |
|
String-like values can be used without explicit conversion in |
|
string interpolations and in most functions that expect a string. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>x</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
</section> |
|
<section xml:id="function-library-lib.strings.isStorePath"> |
|
<title><literal>lib.strings.isStorePath</literal></title> |
|
<para> |
|
Check whether a value is a store path. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>x</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.isStorePath"> |
|
<title>lib.strings.isStorePath usage example</title> |
|
<programlisting language="nix"> |
|
isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python" |
|
=> false |
|
isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11" |
|
=> true |
|
isStorePath pkgs.python |
|
=> true |
|
isStorePath [] || isStorePath 42 || isStorePath {} || … |
|
=> false |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.toInt"> |
|
<title><literal>lib.strings.toInt</literal></title> |
|
<para> |
|
<literal>string -> int</literal> |
|
</para> |
|
<para> |
|
Parse a string as an int. Does not support parsing of integers |
|
with preceding zero due to ambiguity between zero-padded and octal |
|
numbers. See toIntBase10. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>str</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.toInt"> |
|
<title>lib.strings.toInt usage example</title> |
|
<programlisting language="nix"> |
|
|
|
toInt "1337" |
|
=> 1337 |
|
|
|
toInt "-4" |
|
=> -4 |
|
|
|
toInt " 123 " |
|
=> 123 |
|
|
|
toInt "00024" |
|
=> error: Ambiguity in interpretation of 00024 between octal and zero padded integer. |
|
|
|
toInt "3.14" |
|
=> error: floating point JSON numbers are not supported |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.toIntBase10"> |
|
<title><literal>lib.strings.toIntBase10</literal></title> |
|
<para> |
|
<literal>string -> int</literal> |
|
</para> |
|
<para> |
|
Parse a string as a base 10 int. This supports parsing of |
|
zero-padded integers. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>str</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.toIntBase10"> |
|
<title>lib.strings.toIntBase10 usage example</title> |
|
<programlisting language="nix"> |
|
toIntBase10 "1337" |
|
=> 1337 |
|
|
|
toIntBase10 "-4" |
|
=> -4 |
|
|
|
toIntBase10 " 123 " |
|
=> 123 |
|
|
|
toIntBase10 "00024" |
|
=> 24 |
|
|
|
toIntBase10 "3.14" |
|
=> error: floating point JSON numbers are not supported |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.readPathsFromFile"> |
|
<title><literal>lib.strings.readPathsFromFile</literal></title> |
|
<para> |
|
Read a list of paths from <literal>file</literal>, relative to the |
|
<literal>rootPath</literal>. Lines beginning with |
|
<literal>#</literal> are treated as comments and ignored. |
|
Whitespace is significant. |
|
</para> |
|
<para> |
|
NOTE: This function is not performant and should be avoided. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.readPathsFromFile"> |
|
<title>lib.strings.readPathsFromFile usage example</title> |
|
<programlisting language="nix"> |
|
readPathsFromFile /prefix |
|
./pkgs/development/libraries/qt-5/5.4/qtbase/series |
|
=> [ "/prefix/dlopen-resolv.patch" "/prefix/tzdir.patch" |
|
"/prefix/dlopen-libXcursor.patch" "/prefix/dlopen-openssl.patch" |
|
"/prefix/dlopen-dbus.patch" "/prefix/xdg-config-dirs.patch" |
|
"/prefix/nix-profiles-library-paths.patch" |
|
"/prefix/compose-search-path.patch" ] |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.fileContents"> |
|
<title><literal>lib.strings.fileContents</literal></title> |
|
<para> |
|
<literal>fileContents :: path -> string</literal> |
|
</para> |
|
<para> |
|
Read the contents of a file removing the trailing \n |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>file</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.fileContents"> |
|
<title>lib.strings.fileContents usage example</title> |
|
<programlisting language="nix"> |
|
$ echo "1.0" > ./version |
|
|
|
fileContents ./version |
|
=> "1.0" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.sanitizeDerivationName"> |
|
<title><literal>lib.strings.sanitizeDerivationName</literal></title> |
|
<para> |
|
<literal>sanitizeDerivationName :: String -> String</literal> |
|
</para> |
|
<para> |
|
Creates a valid derivation name from a potentially invalid one. |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.sanitizeDerivationName"> |
|
<title>lib.strings.sanitizeDerivationName usage example</title> |
|
<programlisting language="nix"> |
|
sanitizeDerivationName "../hello.bar # foo" |
|
=> "-hello.bar-foo" |
|
sanitizeDerivationName "" |
|
=> "unknown" |
|
sanitizeDerivationName pkgs.hello |
|
=> "-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10" |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.levenshtein"> |
|
<title><literal>lib.strings.levenshtein</literal></title> |
|
<para> |
|
<literal>levenshtein :: string -> string -> int</literal> |
|
</para> |
|
<para> |
|
Computes the Levenshtein distance between two strings. Complexity |
|
O(n*m) where n and m are the lengths of the strings. Algorithm |
|
adjusted from https://stackoverflow.com/a/9750974/6605742 |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>a</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>b</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
<section xml:id="function-library-example-lib.strings.levenshtein"> |
|
<title>lib.strings.levenshtein usage example</title> |
|
<programlisting language="nix"> |
|
levenshtein "foo" "foo" |
|
=> 0 |
|
levenshtein "book" "hook" |
|
=> 1 |
|
levenshtein "hello" "Heyo" |
|
=> 3 |
|
</programlisting> |
|
</section> |
|
</section> |
|
<section xml:id="function-library-lib.strings.commonPrefixLength"> |
|
<title><literal>lib.strings.commonPrefixLength</literal></title> |
|
<para> |
|
Returns the length of the prefix common to both strings. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>a</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>b</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
</section> |
|
<section xml:id="function-library-lib.strings.commonSuffixLength"> |
|
<title><literal>lib.strings.commonSuffixLength</literal></title> |
|
<para> |
|
Returns the length of the suffix common to both strings. |
|
</para> |
|
<variablelist> |
|
<varlistentry> |
|
<term> |
|
<literal>a</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
<varlistentry> |
|
<term> |
|
<literal>b</literal> |
|
</term> |
|
<listitem> |
|
<para> |
|
Function argument |
|
</para> |
|
</listitem> |
|
</varlistentry> |
|
</variablelist> |
|
</section> |
|
<section xml:id="function-library-lib.strings.levenshteinAtMost"> |
|
<title><literal>lib.strings.levenshteinAtMost</literal></title> |
|
<para> |
|
<literal>levenshteinAtMost :: int -> string -> string -> bool</literal> |
|
</para> |
|
<para> |
|
Returns whether the levenshtein distance between two strings is at |
|
most some value Complexity is O(min(n,m)) for k <= 2 and O(n*m) |
|
otherwise |
|
</para> |
|
<section xml:id="function-library-example-lib.strings.levenshteinAtMost"> |
|
<title>lib.strings.levenshteinAtMost usage example</title> |
|
<programlisting language="nix"> |
|
levenshteinAtMost 0 "foo" "foo" |
|
=> true |
|
levenshteinAtMost 1 "foo" "boa" |
|
=> false |
|
levenshteinAtMost 2 "foo" "boa" |
|
=> true |
|
levenshteinAtMost 2 "This is a sentence" "this is a sentense." |
|
=> false |
|
levenshteinAtMost 3 "This is a sentence" "this is a sentense." |
|
=> true |
|
</programlisting> |
|
</section> |
|
</section> |
|
</section> |
