Managing a SUSE Linux™ system requires direct low-level access to the system which generally means reading and writing configuration data. Of course this could be done manually by a knowledgeable person using a conventional editor. A more comfortable and in most cases safer way is to use YaST. Consequently YaST must be able to handle this configuration data on the system level. By handling the original data YaST activities take into account manual editing that might also occur. Thus nobody is forced to use YaST exclusively for configuration tasks.

In YaST the access to system configuration data is realized by means of a special component (or layer if you prefer), the System Configuration Repository (SCR) (see below and Access to the System (SCR in General)). The SCR component basically consists of a number of so-called agents that have been created to accomplish a specific kind of access. For example there is an agent to run shell-commands and there is another one that reads and writes ASCII-files of a specific format. Additionally there are agents that provide access to the system hardware e.g. by taking hold on the proc-file-system.

All these agents are gathered together under a common hood, the SCR-API that can be used from within the YaST-modules in a consistent way. In summary the SCR provides kind of a view on all kinds of data, either YaST2 internal data, original system configuration files or hardware data.

YaST implies lots of artificial intelligence to provide reasonable suggestions for the various tasks. During installation the target system is thoroughly analyzed with respect to its hardware components and in most cases YaST succeeds in suggesting a proper configuration for them.

These suggestions are presented in an overview dialog that shows the main characteristics of the system to be installed and how YaST would handle them. If you are satisfied with these automatically generated settings you can simply accept them. If not, each of the system configuration categories can be “activated” to be changed manually. This is where the workflows come into their own.

If you decide to change a specific configuration category this is usually being done in a workflow. Workflows are used to lead you through the steps necessary to accomplish a specific task. The steps are generally small to avoid an information “overflow”. At the end of the sequence the task has been accomplished and the changes are made permanent in the system.

As was stated above, you are not forced to do it this way. You could as well edit configuration files by hand but YaST can offer as much help as possible for this. Sometimes a workflow has multiple branches for “novice” and “expert” modes. The novice mode fills in the default values and tries to determine as much as possible automatically. The expert mode offers full control and allows to enter even unreasonable values.

By providing pre-configured workflows and configuration data, it is possible to automate almost arbitrary configuration tasks with YaST. From adding a user, to installing a completely configured SUSE Linux™ on specific hardware, nearly everything is possible.

Every workflow is assembled from rather small steps, implemented by means of YaST modules written in a YaST-specific scripting language, the YaST Control Language (YCP). These YaST-modules are then called in a predefined sequence to complete a specific task.

In fact it is possible to even write modules in bash and Perl as long as the module need not have a user interface, i.e. it is not interactive. Such non-interactive modules typically handle specific problems like controlling a particular piece of hardware and can be called from within YCP-modules. This building block approach makes constructing complex workflows easy and maintainable.

The YCP language is also used to control the user interface (UI) presented on screen. The UI displays the information already known by the system and retrieves the information entered by the user.

There are two modes of operation:

It is important to notice here that both methods principally use the same YaST-specific YCP-API to build the dialogs. While there are some (rare) cases where the YCP-code has to distinguish these modes, the dialogs are usually programed for both worlds in in one single source with the same code.

In summary YaST provides the following features, some of them having already been mentioned above:

Even though in most scenarios there is only one single machine, it is important to distinguish between the installation source machine and the installation target machine:

All communication with the installation target is handled via the System Configuration Repository (SCR) to guarantee the network abstraction design goal. This is much easier said than done, however: YaST2 module developers always have to keep in mind that it is strictly forbidden to access system files (or any other system resources, for that matter) directly, even if there may be very convenient CPAN Perl modules to do that. Rather, SCR is to be used instead - always. Otherwise everything might run fine if installation source and target are the same machine, but break horribly if they are not.

SCR in itself is also modularized: All calls are handled by "agents" that each know how to handle a particular configuration "path" like "/etc/fstab" or "/etc/passwd". That may be a simple file, but it may also be a directory hierarchy like "probe" - this particular agent handles all kinds of hardware probing, from mouse and display adapters to storage device controllers (like SCSI or IDE controllers), disks attached to each individual controller or partitions on those disks. Paths are denoted like ".etc.fstab" for SCR. YCP even has a special data type "path" for just this case (a special kind of string with some special operations).

SCR agents handle no more than three calls:

The first argument is always the path to handle, but there may be any number of additional parameters, depending on the agent.

While Read() and Write() are obvious, Execute() may not be: This is intended for some kinds of agents that actually run a program on the installation target. In particular, the ".target.bash" agent does that - it runs a "bash" shell on the target machine and accepts a shell command as an argument. This is the tool of choice for tasks such as creating backup copies of configuration files or running any special command on the target machine - and again, the distinction between installation source and installation target machine becomes very important: You want run these commands on the (possibly remote) target machine, not on the machine that happens to hold the installation media.

SCR agents can easily added when needed. There are frameworks available to write SCR agents in C++, in Perl, or as Bash shell scripts as well as several ready-made parsers for different file formats like the ".ini" file parser that can handle files with "key = value" pairs or the "anyagent" that generalizes that concept even more using regular expressions. Those parsers return YCP lists and maps ready for further processing.

Typically, a YaST2 module for a specific installation or administration task includes a set of YCP or Perl scripts as well as some SCR agents to handle its particular configuration files.

Given the wide variety of machines that can possibly be handled with YaST2, it is important to keep the user interface (UI) abstraction in mind - very much like the SCR, the UI does not necessarily run on the installation target machine. It doesn't even need to run on the same machine as the WFM.

The UI provides dialogs with "widgets" - user interface elements such as input fields, selection lists or buttons. It is transparent to the calling application if those widgets are part of a graphical toolkit such as Qt, or text based (using the NCurses library) or something completely else. An input field for example only guarantees that the user can enter and edit some value with it. A button only provides means to notify the application when the user activated it - by mouse click (if the UI supports using pointing devices such as a mouse), by key press or however else.

The UI has a small number of built-in functions - for example:

There is virtually no low-level control for the widgets - nor is it necessary or even desired to have that. You don't specify a button's width or height - you specify its label to be "Continue", for example, and it will adapt its dimensions accordingly. If desired, more specific layout constraints can be specified: For example, buttons can be arranged in a row with equal width each. The UI will resize them as needed, giving them additional margins if necessary.

The existing UIs provide another layer of network abstraction: The graphical UI uses the Qt toolkit which is based on the X Window System's Xlib which in turn uses the X protocol (usually) running on top of TCP/IP. X Terminals can be used as well as a Linux console (that may be the installation source machine or the installation target machine or another machine connected via the network) running the X Window System or even X servers running on top of other operating systems.

The NCurses (text based) UI requires no more than a shell session - on a text terminal (serial console or other), on a Linux console, in an XTerm session, via ssh or whatever.

Currently, there is no web UI, but YaST2's concepts would easily allow for that if it proves useful or necessary.

The component broker is the central piece of YaST. It acts as a dispatcher for all other components: When a (YCP, Perl or whatever) script calls a function, the broker determines what component handles that function call based on the respective namespace identifier. It is transparent to the caller what programming language a function is written in; the component broker handles that kind of dispatching. The caller only needs to know the function name, its namespace and (or course) the required parameters.

For example, calls like UI::OpenDialog() go to the UI (the user interface), SCR::Read() to the SCR (the system configuration repository). Even scripts can provide namespaces via modules in YCP or Perl.

All communication between the different parts of YaST core is done via a predefined set of YCP data types - simple data types like string, integer, boolean etc., but also compound data types like maps (key / value pairs, also known as "hashes" in other programming languages) or lists (like arrays or vectors in other programming languages). For complex data structures, maps, lists and simple data types can be nested to any degree.

The core-engine of YaST consists of some binary components (modules) that are interconnected via YaST-specific protocols. There are clients as well as servers that are responsible for specific tasks that may have to be accomplished during a YaST-session. According to the well-known client-server-paradigm often used in software technology, YaST-servers are program modules that passively await connections from certain clients to process their requests. Clients on the other hand are active components that send requests to the servers thereby initiating certain actions.

For example the SCR and the UI act as server components that process client-requests on demand. An example for a client module is the stdio-component that can be used to connect the YaST-internal communication with a terminal.

Because this architectural specialty is meant to be used only by the YaST core developers to establish and maintain the low-level machinery we will not go into more detail here. Instead we will focus on the advocated method of extending YaST at the “open end” by creating YCP-modules.

The following little program opens a window that displays the string “Hello, World!” and provides a push button for termination.

{
    string message = "Hello, World!";
    
    UI::OpenDialog(
               `VBox( 
                     `Label( message ),
                     `PushButton("&OK")
                    )
              );

    UI::UserInput();

    UI::CloseDialog();
}
          

In the following this code will be explained shortly in a line-by-line manner thereby touching some topics we will examine in detail later on.

Section not written yet...

Now we can start the program using YaST. For this, we will use a script /sbin/yast2. It is an envelope for easier setup of a running YaST environment.

So if you are reading this document with a browser, you could copy-and-paste the program listed above into a file hello.ycp, and then run /sbin/yast2 hello.ycp which should render the following “spectacular” result.

Figure 1.1. Output of the “Hello, World!”-program

Starting off with this simple example we will now explore the more subtle details of YCP. Since all programming is about handling of data there must be a way to hold it in variables of different types. In the next section you will get to know the various data types that YCP knows about.

This is the most simple data type. It has only one possible value: nil. Declaring variables of this type doesn't make much sense but it is very useful to declare functions that need not return any useful value. nil is often also returned as an error flag if functions fail in doing their job somehow.

A symbol is a literal constant. It is denoted by a single backquote and a letter or underscore optionally followed by further letters, underscores or digits.

`literal
`next

In contrast to C/C++, a YCP boolean is a real data type with the dedicated values true and false. Comparison operations like < or == evaluate to a boolean value. The if (...) statement expects a boolean value as the result of the decision clause.

This is a machine independent signed integer value that is represented internally by a 64 bit value. The valid range is from -2^63 through 2^63-1. Integer constants are written just as you would expect. You can write them either decimal or hexadecimal by prefixing them with 0x, or octal by prefixing them with 0 (just like in C/C++).

1
-17049349
0x9fa0
0xDEADBEEF
0233

Floating point numbers. Because they are represented via the C datatype double the valid range is machine dependent. Constants are written just as you would expect. The decimal point is mandatory only if no exponent follows. Then there must be at least one digit leading the decimal point. The exponent symbol may be e or E.

1.0
-0.0035
1e30
-0.128e-17

Represents a character string of almost arbitrary length (limited only by memory restrictions). String constants consist of UNICODE characters encoded in UTF8. They are enclosed in double quotes.

The backslash in string can be used to mark special characters:

A backslash followed by a newline makes both the backslash and the newline being ignored. Thus you can split a string constant over multiple lines in the YCP code.

“This string ends with a newline character.\n”
“This is also a newline: \012”

A byteblock simply is a sequence of zero or more bytes. The ASCII syntax for a byteblock is #[hexstring]. The hexstring is a sequence of hexadecimal values, lower and upper case letters are both allowed. A byte block consisting of the three bytes 1, 17 and 254 can thus be written as #[0111fE].

In most cases, however, you will not write a byteblock constant directly into the YCP code. You can use the SCR to read and write byteblocks.

#[ ]
#[42]
#[0111fE]
#[03A6f298B5]

A list is a finite sequence of values. These values need not necessarily have the same data type. List constants are denoted by square brackets. In contrast to C it is possible to use complex expressions as list members when defining a list constant. The empty list is denoted by [].

[ ]
[ 1, 2, true ]
[ variable, 17 + 38, some_function(x, y) ]
[ "list", "of", "strings" ]

Accessing the list elements is done by means of the index operator as in my_list[1]:"error". The list elements are numbered starting with 0, so index 1 returns the second element. After the index operator there must be a colon denoting a following default value that is returned if the list access fails somehow. The default value should have the type that is expected for the current list access, in this case the string “error”.

Note 1: A list preserves order of its elements when iterating over them.

Note 2: There is also another method for accessing lists, originating from the early days of YaST. The command select(my_list, 1, "error") also returns the second element of my_list. While this still works, it is deprecated by now and may be dropped in the future.

A YCP-map is an associative array. It is a list of key-value-pairs with the keys being non-ambiguous, i.e. there are no two keys being exactly equal. While you can use values of any type for keys and values, you should restrict the keys to be of type string because from experience other types tend to complicate the code. Values of arbitrary type on the other hand make the map a very flexible data container. Maps are denoted with $[ key_0:value_0, key_1:value_1, ...]. The empty map is denoted by $[].

Note: A map does not reserve order of its elements when iterating over them.

$[ ]
$[ "/usr": 560, "/home" : 3200 ]
$[ "first": true, "2": [ true, false ], "number" : 8+9 ]

Accessing the map elements is done by means of the index operator as in my_map["os_type"]:"linux". This returns the value associated with the key "os_type". As with lists, a default value must be appended (after a colon) that is returned if the given key does not exist. Again it should have the type that is expected for the current access, in this case the string “linux”.

You may have noticed that the syntax for accessing maps kind of resembles that of accessing lists. This is due to the fact that lists are realized as maps internally with constant keys 0, 1, 2, and so on.

Note: There is also another method for accessing maps, originating from the early days of YaST. The command lookup(my_map, "os_type", "linux") also returns the value associated with the given key. While this still works, it is deprecated by now and may be dropped in the future.

A path is something special to YCP and similar to paths in TCL. It is a sequence of path elements separated by dots. A path element can contain any characters except \x00. If it contains something else than a-zA-Z0-9_- it must be enclosed in double quotes. The root path, i.e. the root of the tree is denoted by a single dot. Paths can be used for multiple purposes. One of their main tasks is the selection of data from complex data structures like the SCR-tree (see Chapter 2, SCR Tree).

The backslash in paths can be used to mark a special characters:

.
.17
.etc.fstab
."\nHello !\n".World

."\xff" == ."\xFF"
."\x41" == ."A"
."" != .

A term is something you won't find in C, Perl, Pascal or Lisp but you will find it in functional programming languages like Prolog for example. It is a list plus a symbol, with the list written between normal brackets. The term `alpha(17, true) denotes a symbol `alpha and the list [ 17, true ] as parameters for that symbol. This looks pretty much like a function call.

You can also use the term as a parameter in another function call, for example to specify a user dialog.

`like_function_call(17, true)
`HBox(`Pushbutton(`Id(`ok), "OK"), `TextEntry(`Id(`name), "Name"))

In the previous sections you have seen the data types YCP knows about. In most cases you will (and should) assign a certain data type to every variable you declare. However, there might be cases when the type of a variable is not really clear at coding time, e.g. (in some rare cases) if you access the SCR to get some hardware data. While you should try very hard to avoid this situation, there might be cases where you can't.

To solve this problem, you may assign the type any to your variable which makes it accept assignments of any other valid type. However, because variables of type any are highly deprecated in YaST by now, this “feature” will eventually be dropped in the near future.

Basically a block is a sequence of YCP statements enclosed in curly brackets. It can be a whole YCP program as was the case with the outermost block in hello.ycp from Section 1.1, “YCP Source”. What is special about blocks in YCP is that they represent a value and therefore can be assigned to a variable. It is sometimes really useful to have those blocks as YCP values because this makes it possible to use them as parameters to function calls. Of course the syntactical structure of blocks can become rather complex which leads to a description of the whole language itself. Therefore we put this into a section of its own: Chapter 8, YCP Program Structure.

For now the following examples should suffice.

{ return 17; }
{ integer a = 5; return a + 8; }

In Data type any you have seen the data type any. Because the value of type any can not be assigned to a variable of any other type. FIXME. So it is important to check its type with is(...) and then re-assigning it to a variable of the correct type. The following example shows how this should be done.

//
// Hypothetical example:
// ---------------------
// We don't know whether the SCR will return integers or floats...
//
any     any_var   = 0;
integer int_var   = 0;
float   float_var = 0.0;
boolean int_case  = false;

any_var = SCR::Read(...);

if ( is( any_var, integer ) )
{
   int_var  = any_var;
   int_case = true;
}
else if ( is( any_var, float ) )
{
   float_var = any_var;
   int_case  = false;
}
else
{
   // Error...
}

if ( int_case )
{
   // Use int_var...
}
else
{
   // Use float_var...
}
          

As this is very cumbersome, you should try to avoid this oddity in any case. If it is ineluctable, do it as shown above to stay compatible with future YaST behavior.

A YCP block is a sequence of statements enclosed in curly brackets. Upon evaluation (execution), all the statements in the block are evaluated one by one. Because blocks are also a valid data type in YCP, they can have a value (see Data type block). If a block contains the special statement return(...), then the returned value replaces the block upon evaluation.

The following code sample shows a block with some statements.

{
   integer n = 1;

   while (n <= 10)
   {
      y2milestone("Number: %1", n);
      n = n + 1;
   }

   y2milestone("Returned number: %1", n);

   return n;
}
        

It calculates the numbers 1 through 10 and prints these numbers into the log file. The statement y2milestone(...) used for this is explained in YaST2 Logging along with YCP-logging as such. For now we are interested in the output that is written to the log file. As can be seen below the loop is executed 10 times and the counter has the value 11 after the loop. Finally the last statement return(...) determines the value of the whole block, in this case 11.

...ycp/block_01.ycp:6 Number: 1
...ycp/block_01.ycp:6 Number: 2
...ycp/block_01.ycp:6 Number: 3
...ycp/block_01.ycp:6 Number: 4
...ycp/block_01.ycp:6 Number: 5
...ycp/block_01.ycp:6 Number: 6
...ycp/block_01.ycp:6 Number: 7
...ycp/block_01.ycp:6 Number: 8
...ycp/block_01.ycp:6 Number: 9
...ycp/block_01.ycp:6 Number: 10
...ycp/block_01.ycp:10 Returned number : 11
        

The basic YCP data types we got to know in Chapter 2, YCP Data Types are evaluated in a rather straight forward way as will be shown in the following list.

All the evaluations we have seen above are closely related to operators that may be used within an expression to act on the variables. The next section will give an overview of the operators that can be used in YCP.

These are binary operators for comparison of two values. The result is always boolean.

These are logical operators, that works with boolean datatype, two are binary one is unary. The result is always boolean.

These are bit operators that works with integer, two are binary one is unary. The result is always integer.

There math operators works with numeric data types (integer and float) and also with string. All are binary (except unary minus).

This is the operator known from C language ( condition ? expression : expression). The first operand is expression that can evaluate to boolean, types of second and third operands are code dependent. The result of the triple operator expression is the second operand in the case the first operand (condition) evaluates to true, the third one otherwise.

	Note
	Using brackets makes code cleaner, but is not necessary (according to operators precedence).

	Note
	With the introduction of the index operator ( a = mapvar["key"]:default ), the sequence "]:" became a lexical token usable only for indexing, so watch out when using the triple operator with lists and maps. Use parentheses or white space.

The table of operators precedence (from lowest to highest).

Despite not being “really” statements, comments do (and should) belong to the overall structure of a YCP program. There are two kinds of comments:

{
    // A single-line comment ends at the end of the line.

    /*
      Multi-line comments
      may span several lines.
    */

    y2milestone("This program runs without error");
}

Synopsis: data_type variable_name = initial_value;

Variable declarations in YCP are similar to C. Before you can use a variable, you must declare it. With the declaration you appoint the new variable to be of a certain data_type which means you can assign only values of that specific type. To avoid any errors caused by uninitialized variables, a declaration must imply a suitable value assignment.

Note: A variable declaration may occur at several points in the code which determines its validity (accessibility) in certain program regions (see Section 8.15, “Variable Scopes and blocks”).

{
    integer int_num     = 42;
    float   float_num   = 42.0;
    string  TipOfTheDay = "Linux is the best!";
    integer sum         = 4 * (int_num + 8);
}

Synopsis: variable_name = value;

An assignment statement is almost the same as a declaration statement. Just leave out the declaration. It is an error to assign a value to a variable that has not already been declared or to a variable of different data type.

{
    integer number = 0;

    number = number + 1;
    number = 2 * number;
    number = "Don't assign me to integers!";     // This will cause an error!!!
}

Synopsis: if (condition) then_part [ else else_part ]

Depending on condition only one of the code branches then_part and else_part is executed. The else_part is optional and may be omitted. Both then_part and else_part may either be single statements or a sequence of statements enclosed in curly brackets, i.e. a block. The then_part is executed if and only if condition evaluates to true, the else_part otherwise. It is an error if condition evaluates to something other than true or false.

{
    integer a = 10;

    if ( a > 10 )
	y2milestone("a is greater than 10");
    else
    {
	// Multiple statements require a block...
	
	y2milestone("a is less than or equal to 10");
	a = a * 10;
    }
}

{
    list &string& new_list = ["a", "new", "string"];

    if (contains(new_list, "test"))
	y2milestone("this is a test");

    else if (size(new_list) > 100)
	y2error("Too big list!");

    else if (contains(new_list, "string"))
	y2milestone("this is a new list");

    else
	y2error("Undefined behavior for list %1", new_list);
}

Synopsis: while (condition) loop_body

The while() loop executes the attached loop_body again and again as long as condition evaluates to true. The loop_body may be either a single statement or a block of statements.

Because condition is checked at the top of loop_body, it may not be executed at all if condition is false right from start.

{
    integer a = 0;

    while (a < 10) a = a + 1;
 
    while (a >= 0)
    {
	y2milestone("Current a: %1", a);
	a = a - 1;
    }
}

Synopsis: do loop_body while (condition);

The do...while() loop executes the attached loop_body again and again as long as condition evaluates to true. The loop_body may be either a single statement or a block of statements.

Because condition is checked at the bottom of loop_body, it is executed at least once, even if condition is false right from start.

{
    integer a = 0;

    do
    {
	y2milestone("Current a: %1", a);
	a = a + 1;
    } while (a <= 10);
}

Synopsis: repeat loop_body until (condition);

The repeat...until() loop executes the attached loop_body again and again as long as condition evaluates to false. The loop_body may be either a single statement or a block of statements.

Because condition is checked at the bottom of loop_body, it is executed at least once, even if condition is true right from start.

repeat...until() is similar to do...while() except that condition is logically inverted. The example below has been converted from the do...while() example.

{
    integer a = 0;

    repeat 
    {
	y2milestone("Current a: %1", a);
	a = a + 1;
    } until (a > 10);
}
	  

Synopsis: break;

The break statement is used within loops to exit immediately. The execution is continued at the first statement after the loop.

{
    integer a = 0;

    repeat 
    {
	y2milestone("Current a: %1", a);
	a = a + 1;
	if (a == 7) break;		// Exit the loop here, if a equals 7.
    } until (a > 10);		// Value 10 will never be reached.

    y2milestone("Final a: %1", a);	// This prints 7.
}

{
    foreach (string text, ["a", "new", "string", "break"], {
	// finishes the foreach loop
	if (text == "string") break;
	
	// "string" and "break" will never get here
	y2milestone("Current text is '%1'", text);
    });
}

{
    // list of found prime-number
    list <integer> found = [];
    // start with number
    integer number = 2;
    // finish with number
    integer max_number = 20000;
    
    while (number < max_number) {
	boolean not_found = true;
	
	// try all already found numbers
	foreach (integer try, found, {
	    if (number % try == 0) {
		not_found = false;
		break;
	    }
	});
	
	if (not_found)
	    found = add (found, number);

	number = number + 1;
    }
    
    y2milestone("Sum:   %1", size(found));
    y2milestone("Found: %1", found);
}

{
    integer counter = 0;

    // goes through the list and returns a map
    // made of this list
    map new_map = listmap (string text,
        ["a", "new", "string", "break"], 
    {
        // finishes the listmap loop
        if (text == "string") break;

        counter = counter + 1;
	// returns one "key : value" pair of the new map
        return $[text : counter];
    });
    
    y2milestone("Returned map: %1", new_map);
}

	Note
	The break statement can be used for all loop statments and also statments: listmap, mapmap, list-based maplist, map-based maplist, list-based foreach, map-based foreach, list-based filter, map-based filter.

Synopsis: continue;

The continue statement is used within loops to abandon the current loop cycle immediately. In contrast to break it doesnt exit the loop but jumps to the conditional clause that controls the loop. So for a while() loop, it jumps to the beginning of the loop and checks the condition. For a do...while() loop or repeat...until() loop, it jumps to the end of the loop end checks the condition.

{
    integer a = 0;

    while (a < 10)
    {
	a = a + 1;
	if (a % 2 == 1) continue;     // % is the modulo operator.
	y2milestone("This is an even number: %1", a);
    }
}

{
    // lists all files in /tmp directory
    map cmd = (map) SCR::Execute(.target.bash_output, "ls -1a /tmp");
    
    list <string> files = splitstring (
	(string) cmd["stdout"]:"", "\n"
    );
    
    // clearing memory
    cmd = nil;
    
    foreach (string filename, files, {
	if (regexpmatch(filename, "x")) {
	    y2warning("Filename '%1' contains 'x'", filename);
	}
	
	if (size(filename) > 20) {
	    y2error("Filename '%1' is longer than 20 chars", filename);
	    // we don't work with files with longer names
	    continue;
	}
	
	if (regexpmatch(filename, "^\.")) {
	    y2milestone("Filename '%1' starts with a dot", filename);
	} else {
	    y2milestone("Filename '%1' is what we are looking for", filename);
	}
    });
}

{
    list <integer> random_integers = [];
    
    // filling up with random numbers
    while (size(random_integers) < 10) {
	random_integers = add (random_integers, random(32768));
    }
    random_integers = toset(random_integers);
    
    map <integer, integer> new_map = listmap (integer number, random_integers, {
	// do not proccess huge numbers
	// actually, this finished the listmap and returns nil
	if (number > 32000) {
	    y2error("A huge number has been found");
	    continue;
	}
	
	if (number % 3 == 0) {
	    return $[number : number / 3];
	} else {
	    return $[number : number * 3];
	}
    });
    
    y2milestone("New map: %1", new_map);
}

	Note
	The usage is similar to the break's one.

Synopsis: return [ return_value ];

The return statement immediately leaves the current function or a current top level block (that contains it) and optionally assigns a return_value to this block. If blocks are nested, i.e. if the current block is contained in another block, the return statement leaves all nested blocks and defines the value of the outermost block.

However, if a block is used in an expression other than a block, and that expression is contained in an outer block, the return statement of the inner block won't leave the outer block but define the value of the inner block. This behavior is a as one would expect. For example in the iteration builtins in Section 8.16, “Applying Expressions To Lists And Maps”,

{
    // This block evaluates to 42.
    return 42;

    y2milestone("This command will never be executed");
}

{
    // This block evaluates to 18
    while (true)
    {
	return 18;
    }
}

{
    // This program evaluates to 3:
    integer a = 1 + { return 2; };

    return a;
}

Synopsis: data_type function_name ( [ typed_parameters ] ) function_body

A function definition creates a new function in the current namespace named function_name with a parameter list typed_parameters that has function_body attached for evaluation. The function_body must return a value of type data_type and the arguments passed upon function call must match the type definitions in typed_parameters.

{
    void nothing()
    {
	y2milestone("doing nothing, returning nothing");
    }

    integer half( integer value )
    {
	return value / 2;
    }

    map <string, integer> get_some_map () {
	return listmap (string key, ["a", "b", "c"], {
	    return $[key : random(999)];
	});
    }

    // This renders: ...nothing: nil  -  half: 21...
    y2milestone("nothing: %1  -  half: %2", nothing(), half(42) );
    
    // This renders something like: new half-random map: $["a":839, "b":393, "c":782]
    y2milestone("new half-random map: %1", get_some_map());
}

Synopsis: data_type function_name ( [ typed_parameters ] );

A function declaration allows you to declare only a header of a function without its body. It's main purpose is for indirect recursion etc. You have to provide a function definition with exactly the same arguments later in the same file. A new function will be declared in the current namespace named function_name with a parameter list typed_parameters.

{
    // declares the function - it is defined later
    void nothing();

    integer half( integer value )
    {
	return value / 2;
    }

    // This renders: ...nothing: nil  -  half: 21...
    // uses the function nothing
    y2milestone("nothing: %1  -  half: %2", nothing(), half(42) );

    // defines the function
    void nothing()
    {
	y2milestone("doing nothing, returning nothing");
    }
}

Synopsis: include " included file";

The include statement allows you to insert contents of a file at the given place in the current file. If the current file is a module, the contents of the included file will become a part of the module.

This is useful for dividing a large file into number of pieces. However, if a file is included more than once in a single block, the 2nd, 3rd etc. include statements are ignored.

The included file can be a relative or an absolute file name. Relative names are looked up with /usr/share/YaST2/include as a base.

// this will include /usr/share/YaST2/include/program/definitions.ycp

include "program/definitions.ycp";

Synopsis: import "name_space";

The import statement allows you to import another namespace (module) into the one you are just running in. Then you can access the global functions and variables of that namespace using the double-colon.

Namespaces, to be imported, are looked up in the /usr/share/YaST2/modules/ directory.

{
    import "Hostname";
    import "IP";
    
    // writes: Check FQDN: true
    y2milestone("Check FQDN: %1", Hostname::Check("www.example.com"));

    // writes: Check IP4: false
    y2milestone("Check IP: %1", IP::Check4("192.168.0.356"));
    
}

This is often used for clients using some global API of modules but also for modules using global API of another ones. Please, be careful on creating cross-dependencies when creating an RPM package from sources.

In contrast to many other programming languages, YCP variables can be defined at (almost) any point in the code, namely between other statements. Given that, there must be some rules regarding the creation, destruction and validity of variables. Generally variables are valid (accessible) within the block they are declared in. This also covers nested blocks that may exist in this current block. The valid program region for a variable is called a scope.

{
    // Declared in the outer block
    integer outer = 42;

    {
	// Declared in the inner block
	integer inner = 84;

	// This is OK.
	// Log: ...IN: inner: 84 - outer: 42
	y2milestone("IN: inner: %1 - outer: %2", inner, outer);
    }

    // This yields an error because "inner" is not defined any more.
    y2milestone("OUT: inner: %1 - outer: %2", inner, outer);
}

Additionally to the structural language elements described so far, there are special commands that apply to lists and maps. What is special about these commands is that they apply an expression to the single elements of a list or map. This is done in a functional manner, i.e. the expression to be applied is passed as a parameter. Generally this executes faster than a procedural loop because the internal functionality is realized in a very effective way.

Furthermore some of these commands create lists from maps, maps from maps, maps from lists etc., so that they can be used to avoid the cumbersome assembling of these compound data types in a procedural loop.

8.16.1. foreach() Statement

Synopsis (list): any foreach ( type variable, list<type>, { expression } );

Synopsis (map): any foreach( type_key variable_key, type_value variable_value, map<type_key, type_value>, { expression } );

This statement is a means to process the content of list or map in a sequential manner. It establishes an implicit loop over all entries of the list or map thereby executing the given expression with the respective entries. With lists the variable is a placeholder for the current entry. With maps, variable_key and variable_value are substituted for the respective key-value-pair.

	Note
	The return value of the last execution of expression determines the value of the whole foreach() statement.

Example 8.23. foreach() Loop

{
    // Exemplary foreach for list
    // This yields 3
    foreach(integer value, [1, 2, 3], { return value; });

    // Exemplary foreach for map
    // This yields 9
    foreach(integer key, integer value, $[1:1, 2:4, 3:9], {
	    y2milestone("value: %1", value);
	    return value;
    });
}

Example 8.24. Sophisticated foreach() Loop

{
    list <string> codes = ["X1", "D", "vT", "o", "T5h8"];
    
    list <string> one_letter_codes = [];
    list <string> other_codes = [];
    
    foreach (string code, codes, {
	// all one-letter codes
	if (size(code) == 1) {
	    one_letter_codes = add (one_letter_codes, code);
	// other ones
	} else {
	    other_codes = add (other_codes, code);
	}
    });
    
    // Results in: ["D", "o"]
    y2milestone("One-letter codes: %1", one_letter_codes);
    
    // Results in: ["X1", "vT", "T5h8"]
    y2milestone("Other codes: %1", other_codes);
}

{
    // This results in $[1:"xy", 2:"xy", 3:"xy"]
    map <integer, string> m1 = listmap (integer s, [1, 2, 3], {
	return $[s: "xy"]
    });

    // This results in $[11:2, 12:4, 13:6]
    map <integer, integer> m2 = listmap (integer s, [1, 2, 3], {
	integer a = s+10;
        integer b = s*2;
	list ret = [a, b];
        return ret;
    });

    y2milestone("map 1: %1  - map 2: %2", m1, m2);
}

8.16.3. maplist() Statement

Synopsis (map): list<type1> maplist( type2 key, type3 value, map<type2, type3>, { block returning type1 } );

Synopsis (list): list<type1> maplist( type2 variable, list<type2>, { block returning type1 } );

This statement is a means to process the content of map or list in a sequential manner. It establishes an implicit loop over all entries in map or list thereby executing the given expression with the respective entries. With lists the variable is a placeholder for the current entry. With maps, key and value are substituted for the respective key-value-pair. For each element the expression is evaluated in a new context. All return values are assembled to form the new list that is returned.

	Note
	To exit the loop before it ends, use the break. See the usage in the break statement description. To skip to the next loop step, use the continue. See the usage in the continue statement description.

Example 8.26. maplist() statement

{
    // This results in [2, 4, 6]
    list<integer> l1 = maplist (integer s, [1, 2, 3], {
	reuturn s*2;
    });

    // This results in [2, 6, 12]
    list<integer> l2 = maplist (integer k, integer v, $[1:2, 2:3, 3:4], {
	return k*v;
    });

    y2milestone("list 1: %1  - list 2: %2", l1, l2);
}

{
    // This results in $[11:"ax", 12:"bx"]
    map<integer,string> m = mapmap (integer k, string v, $[1:"a", 2:"b"], {
	return [k+10, v+"x"];
    });

    y2milestone("map: %1", m);
}
            

YCP, originally planned as a functional language, always did dynamic (i.e. runtime) binding of variables. Although useful in many cases, it's quite puzzling for someone used to “imperative” languages. So you could well program the following block and get an unexpected result.

{
   integer x = 42;

   define f() ``{ return x; }

   ... // lots of lines

   x = 55;

   return f();  // will return 55 because of runtime binding of x!
}
	

Another widely misused feature is to include global definitions. While there was no alternative as long as include was the only referencing instrument, this is certainly not a good programming practice in view of speed and memory considerations.

In contrast to included modules, true modules have some distinct properties that are shown in the list below.

The following listing is a brief sample of a true module.

{
   // This is a module called "Sample".
   // Therefore the file name MUST be Sample.ycp
   // The "module" statement makes the module accessible for 'import'.
   //
   module "Sample";

   // This is a local declaration.
   // It can only be 'seen' inside the module.
   //
   integer local_var = 42;

   // This is a global declaration.
   // It can be accessed from outside with the name space identifier 'Sample::'.
   //
   global integer global_var = 27;

   // This is a global function.
   // It has access to global_var *and* local_var.
   //
   global define sample_f () ``{ return local_var + global_var; }
}
	

The module above can be used with the import statement. The syntax for file inclusion with import is similar to include. The interpreter automatically appends “.ycp” to the filename and searches below /usr/lib/YaST2/modules. If the filename starts with “./”, the file is loaded from the local directory. The global declarations of the module can then be accessed with the name space identifier Sample::.

	Note
	The file name must match the module declaration! Inside modules, only variable or function declarations are allowed. Stand-alone blocks or any kind of evaluation statements are forbidden.

{
    // This imports the 'Sample'-module.
    //
    import "Sample";

    // The global function is called with the respective name space identifier.
    //
    integer i = Sample::sample_f();     // == 69

    // No access to local module variables.
    //
    i = Sample::local_var;              // ERROR, no access possible !

    // No problem with global variables.
    //
    i = Sample::global_var;             // == 27

    Sample::global_var = 0;             // This variable is writable !!

    return Sample::sample_f();          // == 42, since global_var is 0
}
	

	Note
	The first encounter of the statement import "Sample"; triggers the loading of “Sample.ycp”. Subsequent import statements are ignored, because “Sample” is already defined. Consequently you can't replace a module during runtime !

If a global function with the same name as the module is defined, it is treated as a constructor. The constructor is called after the module has been loaded and evaluated for the first time. Because of this the constructor could (and should) be defined at the beginning of the module. Despite being located “on top” it can make use of the functions declared later in the file.

Module constructors are used mostly for initialization purposes, e.g. for setting local variables to proper values. However, the actions within a constructor can be arbitrarily complex.

	Note
	Constructors can't have any arguments. The result of calling a constructor from the outside is ignored.

{
   // This is a module called "Class" with a constructor function.
   //
   module "Class";

   // A globally accessible variable.
   //
   global integer class_var = 42;

   // This is the constructor (same name as the module).
   //
   global define Class() ``{ class_var = 12345; }
}


{
    // The usage of the "Class"-module.
    //
    import "Class";

    return Class::class_var;            // will be 12345 !
}
	

When it comes to user-interaction one concept that is stressed very often is usability or - more speaking - user-friendliness. If you have ever heard s.th. about ergonomics you may also know the term Human Computer Interaction (HCI). For us regular folks usability is probably the best notation because it best summarizes what's it all about. It means that the program in question is good “usable” by the user. In general that means that operating a screen dialog should enjoin as low a burden as possible on the user.

In order to have a good usability a system should satisfy the following criteria:

	Important
	If you want to create an interactive YaST module you should try to heed those rules to ease the users life and to assure your module fits smoothly into the surrounding YaST environment which (hopefully) follows them too.

All that said above in essence is an outline from a very good article by Todd Burgess. If you are interested in a more elaborate discussion of usability you may have a look at http://www.osOpinion.com/Opinions/ToddBurgess/ToddBurgess1.html

FIXME: To be done...

FIXME: To be done...

Every YaST package, you have installed on your system, has its auto-generated HTML-based documentation in the /usr/share/doc/packages/_package_name_/.../autodocs/ directory. This documentation is generated by the ycpdoc script — part of the yast2-devtools package.

	Important
	To recognize the comment that should be processed for the autodocs, ycpdoc needs this syntax: /** * * slash and two asterisks identify the comment * for file headers, functions and variables * */ /*** * * slash and three asterisks identify the initial comment * of file (intro) * */ If you don't use two (or three) asterisks, the comment doesn't get processed at all.

Here you can see all available options and arguments of the ycpdoc script. This is the /usr/lib/YaST2/bin/ycpdoc --help command output:

Usage:
      ycpdoc -h|--help|--man
      ycpdoc [-d <dir>] [-s <dir>] [-f html|xml] [-i] [-] [-o] [-wr] files.ycp...

Options and Arguments:
    -h  Show this help screen

    -d dir, --outputdir=dir
        Output files are placed to directory dir

    -s dir, --strip=dir
        Strip only dir when generating output files (default all). Remaining
        slashes are converted to double underscores.

    -f format, --format=format
        Produce output in given format, html or xml. The option may be
        repeated. HTML is the default. XML produces ycpdoc.xml, the DTD is
        not stable yet.

    -O file, --xml-output=file
        For xml output, write to file. The default is "ycpdoc.xml", not
        respecting outputdir.

    -i, --noindex
        Do not generate index.html (intro.html, files.html)

    -   Write output to stdout. Do not generate indexes. If there are more
        input files, generate only one output html file

    -o, --oldindex
        Old style of index: creates only index.html

    -wr Do not warn about undeclared return types

    --state
        For debugging, prints the parsing state for each line.

1.1.2. XML Output

This example of generated XML-based documentation. Run the command /usr/lib/YaST2/bin/ycpdoc --format=xml /usr/share/YaST2/modules/FileUtils.ycp and see the just generated ycpdoc.xml XML file.

	Note
	XML is not for humans, it's optimized for computers. That's also why the XML output of ycpdoc doesn't so look nice but it's very valuable for text-processing tools.

Example 1.1. Examplary XML output reformated and shortened by hand

<?xml version="1.0" encoding="UTF-8"?>
<ycpdoc>
  <files>
    <file_item key="usr/share/YaST2/modules/FileUtils.ycp">
      <header>
        <authors>
          <ITEM>author</ITEM>
        </authors>
        <file>modules/FileUtils.ycp</file>
        <module>YaST2</module>
        <summary>summary</summary>
      </header>

      <provides>
        <provides_item>
	  <descr></descr>
	  <example_file></example_file>
	  <file>usr/share/YaST2/modules/FileUtils.ycp</file>
	  <global>1</global>
	  <kind>function</kind>
	  <name>Exists</name>
	  <parameters>
	    <parameters_item>
	      <name>target</name>
	      <type>string</type>
	    </parameters_item>
	  </parameters>
	  <return>true if exists</return>
	  <scruple></scruple>
	  <see></see>
	  <short>short description</short>
	  <type>boolean</type>
	</provides_item>
	...	
      </provides>

      <requires>
        <requires_item>
          <kind>import</kind>
	  <name>SCR</name>
        </requires_item>
        ...
      </requires>
    </file_item>
  </files>
</ycpdoc>

The file header should show general information about the file name and location, author, and a general purpose.

{
/**
 * File:	modules/CRONConfig.ycp
 * Package:	General YaST Modules
 * Authors:	John The Fish <john@thesmallfish.net>
 * Flags:	Stable
 *
 * $Id: $
 *
 * This module offers to read, change and write the current
 * CRON setup for all system users.
 */
 
    module "CRONConfig";
    ...
}

File header format:

Attribute: value

Possible Attributes are:

Authors: Wendy Graceful <grace@example.com>

Authors: Wendy Graceful <grace@example.com>
         Lars Kralewski <lars@example.com>

Depends: Language

File: modules/HTTP.ycp

Flags: Stable

 *
 * Author: Joe Example <joe@example.com>
 * Internal
 *

Package: SSHD Configuration Module

Summary: This is a multiline summary for the exemplary YaST module
         that does nothing and has no valuable content at all.

/**
 * File: modules/DoNothingAtAll.ycp
 *
 * ...
 *
 * $Id: $
 *
 * This is a multiline summary for the exemplary YaST module
 * that does nothing and has no valuable content at all.
 */

The function header should describe all needed pieces of information about the function. Such as parameters, return value, function's textual description, examples, etc.

/**
 * Returns number of just connected users to the server.
 * You can filter these users by defining the filtering parameter.
 *
 * @param part_of_ip ("192.168.") that users are connected from
 * @return integer number of connected users
 *
 * @see AnotherFunction()
 */
global integer GetCountOfConnectedUsers (string part_of_ip) {
    ...
}

Function description tags:

@deprecated AnotherFunction()

@descr This is a standard multi-line description
       of a function.

/**
* This first line is identified as @short
*
* This multi-line @descr (after a newline) is automatically
* taken as the function description.
*
* Additionally, this multi-line text is automatically taken as another paragraph
* of the function @descr (the number of paragraphs is unlimited).
*/

@example
list <string> servers = GetListOfNSServers("example.com.");
boolean success = AddNewNSServer("ns4.example.com.", "example.com.");

/**
 * Adds a new NS Server into list of domain NS servers.
 *
 * @param new_ns_server FQDN
 * @param domain
 * @return boolean successfull
 */
global boolean AddNewNSServer (string new_ns_server, string domain) {
   ...
   return success;
}

@ref AddNewNSServer()

/**
 * Removes the NS Server from list of domain NS servers.
 *
 * @param ns_server FQDN
 * @param domain
 * @return boolean successfull
 */
global boolean RemoveNSServer (string ns_server, string domain) {
   ...
   boolean success = true;

   return success;
}

@short This function does nothing valuable

/**
* This first line is identified as @short
*
* This multi-line @descr (after a newline) is automatically
* taken as the function description.
*/

@since: 2.12.65

@stable

@struct returns $[
    // example.com.
    "domain"     : "domain name",

    // list of NS servers assigned to the domain
    "ns_servers" : [ "ns1", "ns2", ... ],

    // map of MX servers $[ "server_name" : priority ]
    "mx_servers" : $[ "mx1" : 10, "mx2" : 5 ],
]

@unstable

The YCP variable description can contain almost all pieces of information as the YCP function description except @param and @return tags that don't make sense here. You can, for instance, describe the variable's textual description, examples, structures, etc. However, it's usual that only the description is given.

/**
 * Defines the number of connected users for each IP.
 * There might be more connected users from one IP.
 *
 * @struct $[
 *	"192.168.0.1"  : 5,
 *	"192.168.0.12" : 1,
 *	"192.168.0.35" : 3,
 * ]
 *
 * @see GetNumberOfConnectedUsers()
 */
global map <string, integer>  number_of_connected_users = nil;

/**
 * Stores the currently selected domain
 */
global string current_domain = "";

Function description tags:

See the YCP function description for usage and parameters of tags mentioned above.

This is a set of basic routines for manipulating packages.

1.1.2. Functions

The function names should be self-descriptive, so there are no comments here. Feel free to ask if you are in doubts. (FIXME)

1.1.2.1. Package Installation (GUI)

• boolean Package::Install(<string> package);

• boolean Package::InstallAll(list<string> packages);

• boolean Package::InstallAny(list<string> packages);

• boolean Package::Remove(<string> package);

• boolean Package::RemoveAll(list<string> packages);

1.1.2.2. Package Installation (GUI, custom message)

• boolean Package::InstallMsg(<string> package, <string> message);

• boolean Package::InstallAllMsg(list<string> packages, <string> message);

• boolean Package::InstallAnyMsg(list<string> packages, <string> message);

• boolean Package::RemoveMsg(<string> package, <string> message);

• boolean Package::RemoveAllMsg(list<string> packages, <string> message);

1.1.2.3. Conditional Package Installation

	Note
	GUI based, do not install if Mode::config is defined, only in PackageSystem)

• boolean Package::CheckAndInstallPackages (list<string> packages);

• boolean Package::CheckAndInstallPackagesInteractive (list<string> packages); // with error handling

1.1.2.4. Packages Installation (No GUI)

• boolean Package::DoInstall(list<string> packages);

• boolean Package::DoRemove(list<string> packages);

• boolean Package::DoInstallAndRemove(list<string> toinstall, list<string> toremove);

1.1.2.5. Testing

• boolean Package::Available(<string> package);

• boolean Package::AvailableAll(list<string> packages);

• boolean Package::AvailableAny(list<string> packages);

• boolean Package::Installed(<string> package);

• boolean Package::InstalledAll(list<string> packages);

• boolean Package::InstalledAny(list<string> packages);

1.1.2.6. Other

• void RunSUSEconfig();

• boolean Package::LastOperationCanceled();

• boolean Package::InstallKernel(list<lt;string> kernel_modules);

The module Popup.ycp contains commonly used popup dialogs for general usage. Use those dialogs rather than creating your own custom dialogs whenever possible.

If you have your own definitions of equivalent popups (which is very likely), please remove them as soon as possible and use the popups from Popup.ycp. The new popups usually require fewer parameters, e.g., you no longer need to explicitly pass standard button labels like Yes or No etc. as parameters (we had to do that because of technical limitations with the translator module, but we found a workaround for that).

1.2.2. Headlines, Yes or No?

Sense or nonsense of providing headlines for each popup is a cause for endless discussion - we've been through that. Sometimes headlines make sense, sometimes they don't.

As a general rule of thumb, don't provide a headline that is more or less the same as the message itself, i.e. don't

// Example how NOT to use popups:
//
// - The headline is redundant
//
// - The text is too verbose
//
// - The text contains a reference to "YaST2"
//   (the user shouldn't need to know what that is)
{
    import "Popup";

    boolean answer = Popup::YesNoHeadline( "Create Backup?", // superfluous headline
					   "Should YaST2 create a backup of the configuration files?" );
}

this is plainly redundant. This could be done much better like this:

// Improved version of ask_create_backup_bad.ycp:
//
// Note there is no superfluous headline any more,
// the text is concise, and there is no more reference
// to "YaST2" (a user shouldn't need to know what that is)
{
    import "Popup";

    boolean answer = Popup::YesNo( "Create a backup of the configuration files?" );
}

i.e. concise question, no lyrics around it, clear, plain and simple.

If you need to provide more background information to the users so they can understand what tragedy could befall their machine should they chose either alternative, a headline makes perfect sense for the more experienced user who gets to this kind of question quite frequently:

// Example when to use a headline:
//
// There is lengthy text that advanced users might have read several times
// before, so we give him a concise headline that identifies that dialog so he
// can keep on working without having to read everything again.
{
    import "Popup";

    string long_text =
	"Resizing the windows partition works well in most cases,\n"
	+ "but there are pathological cases where this might fail.\n"
	+ "\n"
	+ "You might lose all data on that disk. So please make sure\n"
	+ "you have an up-to-date backup of all relevant data\n"
	+ "for disaster recovery.\n"
	+ "\n"
	+ "If you are unsure, it might be a good idea to abort the installation\n"
	+ "right now and make a backup."
	;

    boolean answer = Popup::YesNoHeadline( "Resize Windows Partition?", long_text );
}

	Note
	This example might be a good candidate for ContinueCancel() - see below

If you use headlines, please use them to either

• classify the type of popup (Error, Warning, ...)

• summarize the question.

Please DON'T use headlines like Question etc. - that doesn't have any informative value, yet it forces the user to read this useless headline.

For all those reasons, most popups come in a generic version where you can pass a headline ("Headline" is included in the names of those) and a simple version for general usage.

`OpenDialog(
            ...
            `HBox(
:-)               `PushButton( `id(`ok ), `opt(`default), Label::OKButton() ),
                  `PushButton( `id(`retry ), Label::RetryButton() ),
                  `PushButton( `id(`cancel), Label::CancelButton() )
                  )
           )

`OpenDialog(
            ...
            `HBox(
:-(               `PushButton( `id(`ok ), `opt(`default), _("&OK") ),
                  `PushButton( `id(`retry ), "&Retry"  ),
                  `PushButton( `id(`cancel), "&Cancel" )
                  )
           )

1.2.4. When to use which Popup

1.2.4.1. Decision Popups - two buttons, return true or false

For confirmation of possibly dangerous things, use Popup::ContinueCancel.

Only when there are two really distinct paths of decision use Popup::YesNo. And no, cancelling the entire process doesn't count here - this is no equivalent decision.

The positive case (Yes or Continue) is the default. If you don't like that, use the generic Popup::AnyQuestion directly and pass `focus_no for the focus parameter.

	Important
	Remember: Only do that for very good reasons - i.e. when it's a really dangerous decision that typically results in loss of data that can't easily be restored.

• If you need to pass other button labels, think twice.

• If you really need this, use Popup::AnyQuestion.

But NEVER use it so simply change the order of default buttons - i.e. NEVER create dialogs like this one:

// Bad Popup design: Default button order exchanged
//
// DON'T DO THIS!
{
    import "Popup";
    import "Label";

    boolean dont_do_it =
	Popup::AnyQuestion( Popup::NoHeadline(),
			    "Format hard disk?",
			    Label::CancelButton(),
			    Label::ContinueButton(),
			    `yes ); // initial focus - "Cancel" in this case
}

// Bad Popup design: Default button order exchanged
//
// DON'T DO THIS!
{
    import "Popup";
    import "Label";

    boolean dont_do_it =
	Popup::AnyQuestion( Popup::NoHeadline(),
			    "Show installation log?",
			    Label::NoButton(),
			    Label::YesButton(),
			    `no ); // button role reversed - "Yes" 
}

1.2.4.2. Info Popups - just an "OK" button

If you can classify a simple message accordingly, use one of

• Popup::Error

• Popup::Warning

• Popup::Notify

they all have a headline that indicates the type (Error, Warning or Notification).

If you can't classify your message, use the Popup::Message.

Use Popup::LongText to display large amounts of text that might need scrolling.