YaST2 Developers Documentation: The YCP standard built-in functions



The YCP standard built-in functions

! boolean b -> boolean

Logical not for booleans.

Example:

!false -> true

- float i -> float

Negative of float.

- integer i -> integer

Negative of integer.

_ (string singular, string plural, integer value) -> string

Translates the text using a locale-aware plural form handling and the current textdomain. The chosen form of the translation depends on the value.

Example

_("%1 File", "%1 Files", 2) -> "%1 soubory"

_ (string text) -> string

Translates the text using the current textdomain.

Example

_("File") -> "Soubor"

add (list l, value v) -> list

Creates a new list that is identical to the list l but has the value v appended as additional element.

Example:

add ([1, 4], 8) -> [1, 4, 8]

add (map m, any k, any v) -> map

Adds the key/value pair k : v to the map m and returns the newly Created map. If the key k exists in k, the old key/value pair is replaced with the new one.

Example:

add ($[a: 17, b: 11], `b, nil) -> $[a:17, b:nil].

add (path p, string s) -> path

Returns p with added path element created from string s.

Example:

add (.aaa, "anypath...\n\"") -> .aaa."anypath...\n\""

add (term t, any v) -> term

Adds the value v to the term t and returns the newly created term. As always in YCP, t is not modified.

Example:

add (sym (a), b) -> sym (a, b)

argsof (term t) -> list

Returns the arguments of a term.

Example:

argsof (`fun(1, 2)) -> [1, 2]

boolean b1 && boolean b2 -> boolean

Logical and for booleans.

Example:

false && true -> false

boolean b1 || boolean b2 -> boolean

Logical or for booleans.

Example:

false || true -> true

change (list l, value v) -> list

DO NOT use this yet. Its for a special requst, not for common use!!!

changes the list l adds a new element

Example:

change ([1, 4], 8) -> [1, 4, 8]

change (map m, any k, any v) -> map

DO NOT use this yet. It's for a special requst, not for common use!!!

Adds the key/value pair k : v to the map m and returns the map. m is modified. If the key k exists in k, the old key/value pair is replaced with the new one.

Example:

change ($[.a: 17, .b: 11], .b, nil) -> $[.a:17, .b:nil].

contains (list l, any v) -> boolean

Determines, if a certain value v is contained in a list l. Returns true, if this is so.

Example:

contains ([1, 2, 5], 2) -> true

crypt (string unencrypted) -> string

Encrypt the string unencrypted using the standard password encryption provided by the system.

Example:

crypt ("readable") -> "Y2PEyAiaeaFy6"

cryptbigcrypt (string unencrypted) -> string

Encrypt the string unencrypted using bigcrypt password encryption. The password is not truncated.

Example

cryptbigcrypt ("readable") -> "d4brTQmcVbtNg"

cryptblowfish (string unencrypted) -> string

Encrypt the string unencrypted using blowfish password encryption. The password is not truncated.

Example

cryptblowfish ("readable") -> "$2a$05$B3lAUExB.Bqpy8Pq0TpZt.s7EydrmxJRuhOZR04YG01ptwOUR147C"

cryptmd5 (string unencrypted) -> string

Encrypt the string unencrypted using md5 password encryption.

Example:

crypt ("readable") -> "WEgvferaeaFy6"

deletechars (string s, string remove) -> string

Returns a string that results from string s by removing all characters that occur in remove.

Example:

deletechars ("aÖBÄc", "abcdefghijklmnopqrstuvwxyz") -> "ÖBÄ"

dgettext (string textdomain, string text) -> string

Translates the text using the given text domain into the current language.

This is a special case builtin not intended for general use. See _() instead.

Example

dgettext ("base", "No") -> "Nie"

dngettext (string textdomain, string singular, string plural, integer value) -> string

Translates the text using a locale-aware plural form handling using the given textdomain. The chosen form of the translation depend on the value.

This is a special case builtin not intended for general use. See _() instead.

Example

dngettext ("base", "%1 File", "%1 Files", 2) -> "%1 soubory"

eval (any v) -> any

Evaluate a YCP value. See also the builtin ``, which is kind of the counterpart to eval.

Examples:

eval (``(1+2)) -> 3
{ term a = ``add(); a = add(a, [1]); a = add(a, 4); return eval(a); } -> [1,4]

filter (key k, value v, map m, block (boolean) c) -> map

For each key/value pair of the map m the expression exp is evaluated in a new context, where the variable k is assigned to the key and v to the value of the pair. If the expression evaluates to true, the key/value pair is appended to the returned map.

Example:

filter (`k, `v, $[1:"a", 2:"b", 3:3, 5:5], { return (k == v); }) -> $[3:3, 5:5]

filter (symbol s, list l, block (boolean) c) -> list

For each element of the list l the expression v is executed in a new context, where the variable s is assigned to that value. If the expression evaluates to true under this circumstances, the value is appended to the result list.

Example:

filter (`v, [1, 2, 3, 5], { return (v > 2); }) -> [3, 5]

filterchars (string s, string include) -> string

Returns a string that results from string s by removing all characters that do not occur in include.

Example:

filterchars ("aÖBÄc", "abcdefghijklmnopqrstuvwxyz") -> "ac"

find (string s1, string s2) -> integer

Returns the first position in s1 where the string s2 is contained in s1.

Examples:

find ("abcdefghi", "efg") -> 4
find ("aaaaa", "z") -> -1

find (symbol s, list l, expression e) -> any

Searches for a certain item in the list. It applies the expression e to each element in the list and returns the first element the makes the expression evaluate to true, if s is bound to that element. Returns nil, if none is found.

Example:

find (`n, [3,5,6,4], ``(n >= 5)) -> 5

findfirstnotof (string s1, string s2) -> integer

Returns the position of the first character in s1 that is not contained in s2.

Examples:

findfirstnotof ("abcdefghi", "abcefghi") -> 3
findfirstnotof ("aaaaa", "a") -> nil

findfirstof (string s1, string s2) -> integer

Returns the position of the first character in s1 that is contained in s2.

Examples:

findfirstof ("abcdefghi", "cxdv") -> 2
findfirstof ("aaaaa", "z") -> nil

findlastnotof ( string s_1, string s_2 ) -> integer

Returns the position of the last character in s_1 that is NOT contained in s_2.

Example

findlastnotof( "abcdefghi", "abcefghi" ) -> 3 ('d')
findlastnotof("aaaaa", "a") -> nil

findlastof (string s1, string s2) -> integer

Returns the position of the last character in s1 that is contained in s2.

Examples:

findlastof ("abcdecfghi", "cxdv") -> 5
findlastof ("aaaaa", "z") -> nil

flatten (list (list, list) l) -> list

Gets a list l of lists and creates a single list that is the concatenation of those lists in l.

Example:

flatten ([ [1, 2], [3, 4] ]) -> [1, 2, 3, 4]

float f1 * float f2 -> float

Multiplication of floats.

Example:

1.5 * 2.5 -> 3.75

float f1 * float f2 -> float

Division of floats.

Example:

1.5 / 2.5 -> 0.6

float f1 + float f2 -> float

Addition of floats.

Example:

1.5 + 2.5 -> 4.0

float f1 - float f2 -> float

Subtraction of floats.

Example:

1.5 - 2.5 -> -1.0

foreach (symbol key, symbol value, map m, any exp) -> any

For each key:value pair of the map m the expression exp is executed in a new context, where the variables key is bound to the key and value is bound to the value. The return value of the last execution of exp is the value of the foreach construct.

Example

foreach (integer k, integer v, $[1:1,2:4,3:9], { y2debug("v = %1", v); return v; }) -> 9 

foreach (symbol s, list l, any exp) -> any

For each element of the list l the expression exp is executed in a new context, where the variable s is assigned to that value. The return value of the last execution of exp is the value of the foreach construct.

Example

foreach (integer v, [1,2,3], { return v; }) -> 3

haskey (map m, any k) -> boolean

Determines whether the map m contains a pair with the key k. Returns true if this is so.

integer i1 % integer i2 -> integer

Modulus of integers.

Examples:

7 % 4 -> 3

integer i1 & integer i2 -> integer

Bitwise and of integers.

Examples:

13 & 8 -> 8
13 & 7 -> 5

integer i1 * integer i2 -> integer

Multiplication of integers.

Example:

2 * 3 -> 6

integer i1 + integer i2 -> integer

Addition of integers.

Example:

1 + 2 -> 3

integer i1 - integer i2 -> integer

Subtraction of integers.

Example:

1 - 2 -> -1

integer i1 / integer i2 -> integer

Division of integers.

Examples:

6 / 2 -> 3
42 / 0 -> nil

integer i1 << integer i2 -> integer

Bitwise shift left for integers.

Example:

8 << 2 -> 32

integer i1 >> integer i2 -> integer

Bitwise shift right for integers.

Example:

8 >> 2 -> 2

integer i1 ^ integer i2 -> integer

Bitwise exclusive or of integers.

Examples:

2 ^ 7 -> 5
5 ^ 4 -> 1

integer i1 | integer i2 -> integer

Bitwise or of integers.

Examples:

2 | 2 -> 2
1 | 4 -> 5

issubstring (string s, string substring) -> bool

Return true, if substring is a substring of s.

Example:

issubstring ("some text", "tex") -> true

listmap (symbol k, list l, block c) -> map

Maps an operation onto all elements of a list and thus creates a map. For each element k of the list l in the expression exp is evaluated in a new context. The result is the map of those evaluations.

The result of each evaluation must be a list with two items. The first item is the key of the new mapentry, the second is the value of the new entry.

Examples:

listmap (`k, [1,2,3], { return [k, "xy"]; }) -> $[ 1:"xy", 2:"xy" ]
listmap (`k, [1,2,3], { any a = k+10; any b = sformat("x%1",k); list ret = [a,b]; return (ret); }) -> $[ 11:"x1", 12:"x2", 13:"x3" ]

maplist (symbol k, symbol v, map m, block c) -> list

Maps an operation onto all elements key/value pairs of a map and thus creates a list. For each key/value pair of the map m the expression e is evaluated in a new context, where the variable k is assigned to the key and v to the value of the pair. The result is the list of those evaluations.

Example:

maplist (`k, `v, $[1:"a", 2:"b"], { return [k+10, v+"x"]; }) -> [ [11, "ax"], [ 12, "bx" ] ]

maplist (symbol s, list l, block c) -> list

Maps an operation onto all elements of a list and thus creates a new list. For each element of the list l the expression v is evaluated in a new context, where the variable s is assigned to that value. The result is the list of those evaluations.

Example:

maplist (`v, [1, 2, 3, 5], { return (v + 1); }) -> [2, 3, 4, 6]

mapmap (symbol k, symbol v, map m, expression exp) -> map

Maps an operation onto all key/value pairs of the map m and thus creates a new map. For each key/value pair of the map m the expression exp is evaluated in a new context, where the variable k is assigned to the key and v to the value of the pair. The result is the map of those evaluations.

The result of each evaluation must be a map with a single entry which will be added to the result map.

Examples:

mapmap (`k, `v, $[1:"a", 2:"b"], { return ($[k+10 : v+"x"]); }) -> $[ 11:"ax", 12:"bx" ]
mapmap (`k, `v, $[1:"a", 2:"b"], { any a = k+10; any b = v+"x"; map ret = $[a:b]; return (ret); }) -> $[ 11:"ax", 12:"bx" ]

mergelist (list l1, list l2) -> list

Interprets two lists as sets and returns a new list that has all elements of the first list and all of the second list. Identical elements are preserved. The order of the elements in the new list is preserved. Elements of l1 are prior to elements from l2. See also "union".

Examples:

merge ([1, 2], [3, 4]) -> [1, 2, 3, 4]
merge ([1, 2, 3], [2, 3, 4]) -> [1, 2, 3, 2, 3, 4]

mergestring (list (string) l, string c) -> string

Merges a list of strings to a single list. Inserts c between list elements (c may be empty). List elements which are not of type strings are ignored.

See also: splitstring

Examples:

mergestring (["", "abc", "dev", "ghi"], "/") -> "/abc/dev/ghi"
mergestring (["abc", "dev", "ghi", ""], "/") -> "abc/dev/ghi/"
mergestring ([1, "a", 3], ".") -> "a"
mergestring ([], ".") -> ""
mergestring (["abc", "dev", "ghi"], "") -> "abcdevghi"
mergestring (["abc", "dev", "ghi"], "123") -> "abc123dev123ghi"

path p1 + path p2 -> path

Returns p1 with added p2 element created from string s.

Example:

.aaa + "anypath...\n\"" -> .aaa."anypath...\n\""

prepend (list l, value v) -> list

Creates a new list that is identical to the list l but has the value v prepended as additional element.

Example:

prepend ([1, 4], 8) -> [8, 1, 4]

random (integer max) -> integer

Random number generator. Returns integer in the interval <0,max).

regexpmatch (string input, string pattern) -> boolean

Examples:

regexpmatch ("aaabbb", ".*ab.*") -> true
regexpmatch ("aaabbb", ".*ba.*") -> false

regexppos ( string input, string pattern ) -> [ pos, len ]

Returns a list with position and length of the first match, if no match is found it returns an empty list.

Example

regexppos( "abcd012efgh345", "[0-9]+" ) -> [4, 3]
regexppos( "aaabbb", "[0-9]+" ) -> []

regexpsub (string input, string pattern, string match) -> string

Examples:

regexpsub ("aaabbb", "(.*ab).*", "s_\\1_e") -> "s_aaab_e"
regexpsub ("aaabbb", "(.*ba).*", "s_\\1_e") -> nil

regexptokenize (string input, string pattern) -> list handle

!Attention pattern have to include parenthesize "(" ")" If you need no parenthesize, use regexp_match

If the pattern does not not match, the list ist empty. Otherwise the list contains then matchted subexpressions for each pair of parenthesize in pattern.

If pattern does not contain a valid pattern, nil is returned. In the include "common_functions, there are some convinience function, like tokenX or regexp_error

Examples:

list e = regexptokenize ("aaabbBb", "(.*[A-Z]).*")

// e == [ "aaabbB" ]

list h = regexptokenize ("aaabbb", "(.*ab)(.*)");

// h == [ "aaab", "bb" ]

include "wizard/common_functions.ycp" token1 (h) -> "aaab" token2 (h) -> "bb" ... token9 (h) -> "" regexp_matched (h) -> true regexp_error (h) -> false

list h = regexptokenize ("aaabbb", "(.*ba).*");

// h == []

token1 (h) -> "" token2 (h) -> "" ... token9 (h) -> "" regexp_matched (h) -> false regexp_error (h) -> false

list h = regexptokenize ("aaabbb", "(.*ba).*(");

// h == nil

token1 (h) -> "" token2 (h) -> "" ... token9 (h) -> "" regexp_matched (h) -> nil regexp_error (h) -> true

remove (list l, integer i) -> list

Remove the i'th value from a list. The first value has the index 0. The call remove ([1,2,3], 1) thus returns [1,3]. Returns nil if the index is invalid.

Example:

remove ([1, 2], 0) -> [2]

remove (map l, any key) -> map

Remove the value with the key key from a map. Returns nil if the key is invalid.

Example:

remove($[1:2], 0) -> nil
remove ($[1:2, 3:4], 1) -> $[3:4]

remove (term t, integer i) -> term

Remove the i'th value from a term. The first value has the index 1 (!). (The index counting is for compatibility reasons with the 'old' remove which allowed 'remove(`term(1,2,3), 0) = [1,2,3]' Use 'argsof (term) -> list' for this kind of transformation.)

Example:

remove (`fun(1, 2), 1) -> `fun(2)

select (list l, integer i, any default) -> any

Gets the i'th value of a list. The first value has the index 0. The call select([1,2,3], 1) thus returns 2. Returns default if the index is invalid or if the found entry has a different type than the default value.

Examples:

select ([1, 2], 22, 0) -> 0
select ([1, "two"], 0, "no") -> "no"

select (term t, integer i, any default) -> any

Gets the i'th value of the term t. The first value has the index 0. The call select ([1, 2, 3], 1) thus returns 2. Returns the default if the index is invalid or the found value has a diffetent type that default.

Example:

select (`hirn (true, false), 33, true) -> true

setcontains (list l, any v) -> boolean

Determines, if a certain value v is contained in a list l, but assumes that l is sorted. If l is not sorted, the result is undefined.

Example:

setcontains ([1, 2, 5], 2) -> true

sformat (string form, any par1, any par2, ...) -> string

form is a string that may contains placeholders %1, %2, ... Each placeholder is substituted with the argument converted to string whose number is after the %. Only 1-9 are allowed by now. The percentage sign is donated with %%.

Example:

sformat ("%2 is greater %% than %1", 3, "five") -> "five is greater % than 3"

size (byteblock value) -> integer

Returns a size of a byteblock in bytes.

size (list l) -> integer

Returns the number of elements of the list l

size (map m) -> integer

Returns the number of key/value pairs in the map m

size (path p) -> integer

Returns the number of path elements of the path p, i.e. the length of p.

Examples:

size (.hello.world) -> 2
size (.) -> 0

size (string s) -> integer

Returns the number of characters of the string s Notice, that size(nil) -> nil

size (term t) -> integer

Returns the number of arguments of the term t.

sleep (integer ms) -> void

Sleeps a number of milliseconds.

sort (list l) -> list

Sort the list l according to the YCP builtin predicate <. Duplicates are not removed.

Example:

sort ([2, 1, true, 1]) -> [true, 1, 1, 2]

sort (symbol x, symbol y, list l, block< boolean > order) -> list

Sorts the list l. You have to specify an order on the list elements by naming to formal variables x und y and specify an expression order, that evaluates to a boolean value depending on x and y. Return true, if x < y to sort the list ascending.

The comparison must be an irreflexive one, that is "<" instead of "<=".

It is because we no longer use bubblesort (yuck) but std::sort which requires a strict weak ordering.

Examples:

sort (integer x, integer y, [ 3,6,2,8 ], ``(x < y)) -> [ 2, 3, 6, 8 ]

splitstring (string s, string c) -> list (string)

Splits s into sub-strings at delimter chars c. the resulting pieces do not contain c

see also: mergestring

If s starts with c, the first string in the result list is empty If s ends with c, the last string in the result list is empty. If s does not contain c, the result is a list with s.

Examples:

splitstring ("/abc/dev/ghi", "/") -> ["", "abc", "dev", "ghi" ]
splitstring ("abc/dev/ghi/", "/") -> ["abc", "dev", "ghi", "" ]
splitstring ("abc/dev/ghi/", ".") -> ["abc/dev/ghi/" ]
splitstring ("text/with:different/separators", "/:") -> ["text", "with", "different", "separators"]

srandom () -> integer

Initialize random number generator with current date and time and returns the seed.

srandom (integer seed) -> void

Initialize random number generator.

string s1 + integer i2 -> string

Returns concatenation of s1 and i2 after transforming i2 to a string.

Example:

"YaST" + 2 -> "YaST2"

string s1 + path p2 -> string

Returns concatenation of s1 and p2 after transforming p2 to a string.

Example:

"YaST" + .two -> "YaST.two"

string s1 + string s2 -> string

Returns concatenation of s1 and s2.

Example:

"YaST" + "2" -> "YaST2"

string s1 + symbol s2 -> string

Returns concatenation of s1 and s2 after transforming s2 to a string AND stripping the leading backquote.

Example:

"YaST" + `two -> "YaSTtwo"

substring (string s, integer start) -> string

Extract a substring of the string s, starting at start after the first one.

Examples:

substring ("some text", 5) -> "text"
substring ("some text", 42) -> ""

substring (string s, integer start, integer length) -> string

Extract a substring of the string s, starting at start after the first one with length of at most length.

Example:

substring ("some text", 5, 2) -> "te"
substring ("some text", 42, 2) -> ""

symbolof (term t) -> symbol

Returns the symbol of the term t.

Example:

symbolof (`hrombuch (18, false)) -> `hrombuch

time () -> integer

Return the number of seconds since 1.1.1970.

timestring (string format, integer time, boolean utc) -> string

Combination of standard libc functions gmtime or localtime and strftime.

Example

timestring ("", 100, false) -> ""

toascii (string s) -> string

Returns a string that results from string s by copying each character that is below 0x7F (127).

Example:

toascii ("aÖBÄc") -> "aBc"

tobyteblock (any value) -> byteblock

Converts a value to a byteblock. If the value can't be converted to a byteblock, nilbyteblock is returned.

tofloat (any value) -> float

Converts a value to a floating point number. If the value can't be converted to a float, nilfloat is returned.

Example:

tofloat (4) -> 4.0
tofloat ("42") -> 42.0
tofloat ("3.14") -> 3.14

tohexstring (integer number) -> string

Converts a integer to a hexadecimal string.

Example:

tohexstring (31) -> "0x1f"

tointeger (any value) -> integer

Converts a value to an integer. If the value can't be converted to an integer, nilinteger is returned.

Example:

tointeger (4.03) -> 4
tointeger ("42") -> 42
tointeger ("0x42") -> 66
tointeger ("042") -> 34

tolist (any value) -> list

Converts a value to a list. If the value can't be converted to a list, nillist is returned.

tolower (string s) -> string

Returns a string that results from string s by converting each character tolower.

Example:

tolower ("aBcDeF") -> "abcdef"

tomap (any value) -> map

Converts a value to a map. If the value can't be converted to a map, nilmap is returned.

topath (string s) -> path

Converts a value to a path. If the value can't be converted to a path, nilpath is returned.

Example:

topath ("path") -> .path
topath (".some.path") -> .some.path

toset (list l) -> list

Scans a list for duplicates, removes them and sorts the list.

Example:

toset ([1, 5, 3, 2, 3, true, false, true]) -> [false, true, 1, 2, 3, 5]

tostring (any value) -> string

Converts a value to a string.

tostring (float f, integer precision) -> string

Converts a floating point number to a string, using the specified precision.

Example:

tostring (0.12345, 4) -> 0.1235

toterm (any value) -> term

Converts a value to a term. If the value can't be converted to a term, nilterm is returned.

toupper (string s) -> string

Returns a string that results from string s by converting each character toupper.

Example:

tolower ("aBcDeF") -> "ABCDEF"

union (list l1, list l2) -> list

Interprets two lists as sets and returns a new list that has all elements of the first list and all of the second list. Identical elements are dropped. The order of the elements in the new list is preserved. Elements of l1 are prior to elements from l2. See also "mergelist".

Examples:

union ([1, 2], [3, 4]) -> [1, 2, 3, 4]
union ([1, 2, 3], [2, 3, 4]) -> [1, 2, 3, 4]

union (map m1, map m2) -> map

Interprets two maps as sets and returns a new map that has all elements of the first map m1>/tt>and all of the second map m2. If elements have identical keys, values from m2 overwrite elements from m1.

y2debug (string format, ...) -> void

Log a message to the y2log. Arguments are same as for sformat() builtin. The y2log component is "YCP", so you can control these messages the same way as other y2log messages.

Example:

y2debug ("%1 is smaller than %2", 7, "13");

y2error (string format, ...) -> void

y2internal (string format, ...) -> void

y2milestone (string format, ...) -> void

y2security (string format, ...) -> void

y2warning (string format, ...) -> void

~ integer i -> integer

Bitwise not of integer.

Example:

~42 = -43

YaST2 Developers Documentation: The YCP standard built-in functions