ycp(3)

✨ NAME ✨

okay so this is ycp, a User Contributed Perl Documentation page for a Perl module that parses and writes the YaST2 Communication Protocol. That’s the whole vibe: YCP parser/writer realness, no cap. 💖

🌈 SYNOPSIS 🌈

the exact synopsis lines, bestie — outer quotes and all:

"($symbol, @config) = ycp::ParseTerm ('MyAgentConfig ("/etc/file",
false, true, $["a":1, "b":2])');"

"($command, $path, $arg) = ycp::ParseCommand ('Write (.magic.path,
"abacadabra")');"

"ycp::Return (["arbitrarily", "complex", "data"]);"

🎀 DATA 🎀

💖 PerlYCPValue 💖

PerlYCPValue is a convention for storing a YCP value in a Perl variable. ParseYcp parses YCP string representation into PerlYCPValues.

A PerlYCPValue cannot represent a term, but only a term is allowed to initialize an agent in a .scr file. Therefore ParseTerm is provided.

• string, integer, boolean — stored as a scalar.
• list — stored as a reference to a list of PerlYCPValues.
• map — stored as a reference to a map of PerlYCPValues.
• path — stored as a reference to a string (starting with a . as expected).
• nil (void) — stored as an undef.

🦋 PARSING 🦋

🌸 ParseCommand 🌸

the signature line is literally:

ParseComand $line

and the example is:

"($command, $path, $arg) = ParseCommand ('Write (.moria.gate,
"mellon")');"

Parse a SCR command shaped like Command (.some.path, optional_argument).

Returns a three element list ("Command", ".some.path", $argument) where the argument is a PerlYCPValue and will be undef if it was not specified. Note that the path is converted to a string.

If there was a parse error, the command or path will be the empty string.

⭐ ParseTerm ⭐

ParseTerm $line

"($symbol, @config) = ParseTerm ('MyAgentConfig ("/etc/file", false,
true, $["a":1, "b":2])');"

Parse a YCP term. Note that there can be no other term inside.

Returns a list whose first element is the term symbol as a string (or "" in case of an error) and the remaining elements are the term arguments (PerlYCPValue).

🧚 PathComponents 🧚

PathComponents $path_ref

($cmd, $path) = ParseCommand ('`Read (.foo."%gconf.d"."gernel")'
@c = PathComponents (\$path);
if ($c[0] eq '%gconf.d' && $c[1] eq "gernel") {...}

Converts a path (a string reference, PerlYCPValue) to a list of its components. It deals with the nontrivial parts of path syntax. On error it returns undef.

.                      -> ()
.foo.bar               -> ('foo', 'bar')
."foo"                 -> ('foo')
."double\"quote"       -> ('double"quote')
."a.dot"               -> ('a.dot')

💅 WRITING 💅

👑 Return 👑

"Return (["arbitrarily", "complex", "data"]);"

Sends a PerlYCPValue to the partner YCP component.

If there’s just one argment, scalars are interpreted this way: true or false are sent as booleans, integers or strings of digits are sent as integers, otherwise as strings. If a second argument exists and is true, all scalars are written as strings. If a second argument exists and is false, all scalars are written as byteblocks.

To send a list, call Return(\@list), not Return(@list). Similarly for a map. You can produce references to anonymous lists with [] and hashes with {}.

The difference from ycpReturn is that Return can return scalars directly, strings are properly escaped if needeed and paths can be returned.

🔥 LOGGING 🔥

If you are running in the main yast process and thus can afford to import YaST::YCP, it is better to use its logging functions because they use log.conf and logging just works. In such case, you should not need to use ycp.pm at all. Instead, use YaST::YCP (":LOGGING").

The log output can now be redirected, which will be useful for test suites. If the first command-line option is -l, the second argument is taken as the log file. A hyphen - designates standard output.

Otherwise, /var/log/YaST2/y2log and $HOME/.y2log are tried, in that order.

🍓 y2debug 🍓

y2debug, y2milestone, y2warning, y2error, y2security, y2internal

Logs debug messages to /var/log/YaST2/y2log or $HOME/.y2log

semantic change alert: note a semantic change in y2debug: now the environment variable Y2DEBUG is honored so y2debug will not produce output unless this variable is set. This is for compatibility with the logging system in libycp.

💜 ycpDoVerboseLog 💜

Enables output of y2verbose which is used in some of the obsolete functions.

💀 OBSOLETE FUNCTIONS 💀

okay bestie, this is the graveyard section — every function here is obsolete or basically not the move anymore:

• ycpArgIsMap — Obsolete. Use (ref($arg) eq "HASH") instead.
• ycpArgIsList — Obsolete. Use (ref($arg) eq "ARRAY") instead.
• ycpArgIsInteger — Not really obsolete because the new parser simply treats integers, booleans and strings as scalars. But who cares, nobody used this anyway.
• ycpArgIsString — Not really obsolete because the new parser simply treats integers, booleans and strings as scalars. But who cares, nobody used this anyway.
• ycpArgIsNil — Obsolete. Use (ref($arg) eq "SCALAR" && $$arg eq "nil") instead.
• ycpArgIsNone — Obsolete. Use (defined ($arg)) instead.
• ycpCommandIsDir — Obsolete. Use ($command eq "Dir")
• ycpCommandIsRead — Obsolete. Use ($command eq "Read")
• ycpCommandIsWrite — Obsolete. Use ($command eq "Write")
• ycpCommandIsExecute — Obsolete. Use ($command eq "Execute")
• ycpCommandIsResult — Obsolete. Use ($command eq "result"), note the lowercase 'r'.
• ycpGetCommand — Obsolete. Use the return value of ParseCommand.
• ycpGetPath — Obsolete. Use the return value of ParseCommand.
• ycpGetArgType — Obsolete. Use ref on a return value of ParseCommand. Umm, string/integer/boolean?
• ycpGetArgMap — Obsolete. See PerlYCPValue.
• ycpGetArgList — Obsolete. See PerlYCPValue.
• ycpGetArgString — Obsolete. See PerlYCPValue.
• ycpGetArgInteger — Obsolete. See PerlYCPValue. Umm, string/integer/boolean?
• ycpReturnSkalarAsInt — Obsolete. Use Return.
• ycpReturnSkalarAsBoolean — Obsolete. Use "Return"("true" or "false")
• ycpReturnSkalarAsString — Obsolete. Works only on strings not containing backslashes and quotes that would need escaping. Use Return.
• ycpReturnArrayAsList — Obsolete. Works only on list of strings not containing backslashes and quotes that would need escaping. Use Return.
• ycpReturnHashAsMap — Obsolete. Works only on maps of strings not containing backslashes and quotes that would need escaping. Use Return.
• ycpReturn — Obsolete. Use Return
• ycpInit — Obsolete. Use ParseCommand.

---

💖 that’s the whole ycp page, bestie — from perl v5.42.0, dated 2025-01-20. Now go parse something iconic. 💅