diff --git a/README.md b/README.md index 0d77c7e..0cefc56 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ - [`2.5.1 Documented Keyword Information`](website/docs/chapter-02/05_keyword_interface.md#251-documented-keyword-information) - LO-2.5.1 (K1) Recall the information that can be found in a keyword documentation. - [`2.5.1.1 Example Keyword `Should Be Equal``](website/docs/chapter-02/05_keyword_interface.md#2511-example-keyword-should-be-equal) - - [`2.5.1.2 Example Keyword `Run Process``](website/docs/chapter-02/05_keyword_interface.md#2512-example-keyword-run-process) + - [`2.5.1.2 Example Keyword `Set To Dictionary``](website/docs/chapter-02/05_keyword_interface.md#2512-example-keyword-set-to-dictionary) - [`2.5.1.3 Example Keyword `Get Regexp Matches``](website/docs/chapter-02/05_keyword_interface.md#2513-example-keyword-get-regexp-matches) - [`2.5.2 Keyword Arguments`](website/docs/chapter-02/05_keyword_interface.md#252-keyword-arguments) - LO-2.5.2 (K2) Understand the difference between argument kinds. diff --git a/website/docs/chapter-02/05_keyword_interface.md b/website/docs/chapter-02/05_keyword_interface.md index ac13d0a..8b214ad 100644 --- a/website/docs/chapter-02/05_keyword_interface.md +++ b/website/docs/chapter-02/05_keyword_interface.md @@ -62,22 +62,23 @@ This keyword has 2 "Mandatory Arguments" and 6 "Optional Arguments". All of them can be called positionally or by name. -### 2.5.1.2 Example Keyword `Run Process` +### 2.5.1.2 Example Keyword `Set To Dictionary` -[Documentation of `Run Process` from `Process` library](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) +[Documentation of `Set To Dictionary` from `Collections` library](https://robotframework.org/robotframework/latest/libraries/Collections.html#Set%20To%20Dictionary) -`Run Process` is part of the Process library and is documented as follows: +`Set To Dictionary` is part of the Collections library and is documented as follows: -![Run Process Keyword Documentation](/img/Run_Process_Docs.png) +![Set To Dictionary Keyword Documentation](/img/Set_To_Dictionary_part_1.png) -This keyword has one Mandatory Argument `command` which can be called positionally or by name. -The latter two arguments are optional. +This keyword has one :term[Mandatory Argument] `dictionary` which can be called positionally or by name. See [Mandatory Args](../chapter-03/user_keyword). +The latter two arguments are optional and can be used depending on the style of defining keys and values the user likes most. -The argument `arguments` is a :term[Variable Number of Positional Arguments] and can only be set by position. +The argument `key_value_pairs` is a :term[Variable Number of Positional Arguments] and can only be set by position. Therefore, if it shall be set, all preceding arguments must be set by position as well. See [2.5.2.5 Variable Number of Positional Arguments](chapter-02/05_keyword_interface.md#2525-variable-number-of-positional-arguments) for more information about this kind of argument. -The argument `configuration` is a :term[Free Named Argument] and can only be set by names. +The argument `items` is a :term[Free Named Argument] and can only be set by names. + See [2.5.2.7 Free Named Arguments](chapter-02/05_keyword_interface.md#2527-free-named-arguments) for more information about this kind of argument. @@ -279,17 +280,26 @@ A special case of optional arguments that can only be set by their position are These are also referred to as `*args` or `*varargs` in Python. Some keywords need to collect a variable amount of values into one argument, because it is not possible to define the amount of values in advance. -One example for this kind of keyword is [2.5.1.2 Example Keyword `Run Process`](chapter-02/05_keyword_interface.md#2512-example-keyword-run-process) from the Process library. -This keyword executes a `command` with variable amount of `arguments` and waits for the process to finish. -Depending on the command to be executed different amount of arguments are needed for that command. +One example for this kind of keyword is [2.5.1.2 Example Keyword `Set To Dictionary`](chapter-02/05_keyword_interface.md#2512-example-keyword-set-to-dictionary) from the Collections library. +This keyword adds key and values to a `dictionary` with variable amount of `key_value_pairs`. +Depending on the number of keys and values, different amount of arguments are needed. -This variable argument is marked with a single asterisk `*` before the argument name in the keyword documentation. +This key_value_pairs argument is marked with a single asterisk `*` before the argument name in the keyword documentation. -When calling this keyword, the first positional argument is assigned to `command`, while all subsequent positional arguments are collected into `arguments`. +When calling this keyword, the first positional argument is assigned to `dictionary`, while all subsequent positional arguments are collected into `key_value_pairs`. Because of this behavior, no additional positional arguments can be used after these :term[Variable Number of Positional Arguments]. As a result, any arguments following these :term[Variable Number of Positional Arguments] must be named arguments, + regardless of whether they are mandatory or optional arguments with a default value. +Example adding items to a dictionary using the `key_value_pairs` argument: +```robotframework +*** Test Cases *** +Dictionary Handling + VAR &{mydict} + Set To Dictionary ${mydict} key1 value1 key2 value2 +``` + Also see [2.5.1.3 Example Keyword `Get Regexp Matches`](chapter-02/05_keyword_interface.md#2513-example-keyword-get-regexp-matches). @@ -334,19 +344,20 @@ In this case all values given to the keyword as arguments, that do contain an un Free named arguments are marked with two asterisks `**` before the argument name in the keyword documentation. -The example of the `Run Process` keyword also has a free named argument `** configuration`. +The example of the `Set To Dictionary` keyword also has a free named argument `** items`. -When calling this keyword all named arguments that are not explicitly defined as argument names are collected into the `configuration` argument and will be available as a dictionary in the keyword implementation. +When calling this keyword all named arguments that are not explicitly defined as argument names are collected into the `items` argument and will be available as a dictionary in the keyword implementation. They are optional and can be omitted. -With this configuration it is possible to e.g. redirect the output of the process to a file or to set the working directory of the process. +Using this `items` argument the key/value pairs can be given with an equal sign, like key=value. -Example redirecting stdout and stderr to a file: +Example adding items to a dictionary using the `items` argument: ```robotframework *** Test Cases *** -Send 5 IPv4 Pings On Windows - Run Process ping -n 5 -4 localhost stdout=ping_output.txt stderr=ping_error.txt +Dictionary Handling + VAR &{mydict} + Set To Dictionary ${mydict} key1=value1 key2=value2 ``` diff --git a/website/docs/chapter-03/03_user_keyword.md b/website/docs/chapter-03/03_user_keyword.md index 6ccc8cd..7141bf7 100644 --- a/website/docs/chapter-03/03_user_keyword.md +++ b/website/docs/chapter-03/03_user_keyword.md @@ -61,9 +61,9 @@ Also spaces and underscores will be ignored when matching keyword names. So the keywords `Login To System`, and `log_into_system` are considered identical. To identify keywords that shall be executed, Robot Framework uses a matching algorithm that is case-insensitive and ignores spaces and underscores. -- If then a full match is found, that keyword is used. -- If no full match is found, the prefixes `Given`, `When`, `Then`, `And`, and `But` (case-insensitive), which are used in Behavior-Driven Specification style, are removed from the called keyword name to find a match. -- If still no match is found, Robot Framework tries to match the name with keywords that have embedded arguments. +- The prefixes Given, When, Then, And, and But (case-insensitive), which are used in Behavior-Driven Specification style, are removed from the called keyword name to find a match. +- If no match is found, Robot Framework tries to match the name with keywords that have embedded arguments. +- If still no match is found, a full match (including possible Given, When, Then, And and But) is tried. By default, if not explicitly defined by the library developers, all Library Keywords are named in **Title Case** with capital letters at the beginning of each word, and spaces between words. diff --git a/website/static/img/Run_Process_Docs.png b/website/static/img/Run_Process_Docs.png deleted file mode 100644 index 50a6836..0000000 Binary files a/website/static/img/Run_Process_Docs.png and /dev/null differ diff --git a/website/static/img/Set_To_Dictionary_part_1.png b/website/static/img/Set_To_Dictionary_part_1.png new file mode 100644 index 0000000..4872435 Binary files /dev/null and b/website/static/img/Set_To_Dictionary_part_1.png differ