1#!/usr/bin/env python3
2
3r"""
4This file contains functions useful for printing to stdout from robot programs.
5"""
6
7import os
8import re
9
10import func_args as fa
11import gen_print as gp
12from robot.libraries.BuiltIn import BuiltIn
13
14gen_robot_print_debug = int(os.environ.get("GEN_ROBOT_PRINT_DEBUG", "0"))
15
16
17def sprint_vars(*args, **kwargs):
18    r"""
19    Sprint the values of one or more variables to the console.
20
21    This is a robot re-definition of the sprint_vars function in gen_print.py.  Given a list of variable
22    names, this keyword will string print each variable name and value such that each value lines up in the
23    same column as messages printed with sprint_time().
24
25    Description of argument(s):
26    args                            The names of the variables to be printed (e.g. var1 rather than ${var1}).
27    kwargs                          See sprint_varx in gen_print.py for descriptions of all other arguments.
28    """
29
30    if "fmt" in kwargs:
31        # Find format option names in kwargs['fmt'] and wrap them with "gp." and "()" to make them into
32        # function calls.  For example, verbose would be converted to "gp.verbose()".  This allows the user
33        # to simply specify "fmt=verbose" (vs. fmt=gp.verbose()).
34        # Note "terse" has been explicitly added for backward compatibility.  Once the repo has been purged
35        # of its use, this code can return to its original form.
36        regex = "(" + "|".join(gp.valid_fmts()) + "|terse)"
37        kwargs["fmt"] = re.sub(regex, "gp.\\1()", kwargs["fmt"])
38    kwargs = fa.args_to_objects(kwargs)
39    buffer = ""
40    for var_name in args:
41        var_value = BuiltIn().get_variable_value("${" + str(var_name) + "}")
42        buffer += gp.sprint_varx(var_name, var_value, **kwargs)
43
44    return buffer
45
46
47def sprint_auto_vars(headers=0):
48    r"""
49    String print all of the Automatic Variables described in the Robot User's Guide using sprint_vars.
50
51    NOTE: Not all automatic variables are guaranteed to exist.
52
53    Description of argument(s):
54    headers                         This indicates that a header and footer should be printed.
55    """
56
57    buffer = ""
58    if int(headers) == 1:
59        buffer += gp.sprint_dashes()
60        buffer += "Automatic Variables:"
61
62    buffer += sprint_vars(
63        "TEST_NAME",
64        "TEST_TAGS",
65        "TEST_DOCUMENTATION",
66        "TEST_STATUS",
67        "TEST_DOCUMENTATION",
68        "TEST_STATUS",
69        "TEST_MESSAGE",
70        "PREV_TEST_NAME",
71        "PREV_TEST_STATUS",
72        "PREV_TEST_MESSAGE",
73        "SUITE_NAME",
74        "SUITE_SOURCE",
75        "SUITE_DOCUMENTATION",
76        "SUITE_METADATA",
77        "SUITE_STATUS",
78        "SUITE_MESSAGE",
79        "KEYWORD_STATUS",
80        "KEYWORD_MESSAGE",
81        "LOG_LEVEL",
82        "OUTPUT_FILE",
83        "LOG_FILE",
84        "REPORT_FILE",
85        "DEBUG_FILE",
86        "OUTPUT_DIR",
87    )
88
89    if int(headers) == 1:
90        buffer += gp.sprint_dashes()
91
92    return buffer
93
94
95def gp_debug_print(buffer):
96    r"""
97    Print the buffer value only if gen_robot_print_debug is set.
98
99    This function is intended for use only by other functions in this module.
100
101    Description of argument(s):
102    buffer                          The string to be printed.
103    """
104
105    if not gen_robot_print_debug:
106        return
107    gp.gp_print(buffer)
108
109
110# In the following section of code, we will dynamically create print versions for several of the sprint
111# functions defined above.  For example, where we have an sprint_vars() function defined above that returns
112# formatted variable print outs in a string, we will create a corresponding rprint_vars() function that will
113# print that string directly to stdout.
114
115# It can be complicated to follow what's being created below.  Here is an example of the rprint_vars()
116# function that will be created:
117
118# def rprint_vars(*args, **kwargs):
119#     gp.gp_print(gp.replace_passwords(sprint_vars(*args, **kwargs)), stream='stdout')
120
121# For sprint_vars (defined above), the following functions will be created:
122
123# rprint_vars                       Robot Print Vars
124# rqprint_vars                      Robot Print Vars if ${quiet} is set to ${0}.
125# rdprint_vars                      Robot Print Vars if ${debug} is set to ${1}.
126# rlprint_vars                      Robot Print Vars to the log instead of to the console.
127
128# Abbreviated names are created for all of the preceding function names:
129# rpvars
130# rqpvars
131# rdpvars
132# rlpvars
133
134# Users are encouraged to only use the abbreviated forms for development but to then ultimately switch to
135# full names.
136# Rprint Vars (instead of Rpvars)
137
138replace_dict = {"output_stream": "stdout", "mod_qualifier": "gp."}
139
140gp_debug_print("gp.robot_env: " + str(gp.robot_env) + "\n")
141
142# func_names contains a list of all rprint functions which should be created from their sprint counterparts.
143func_names = ["print_vars", "print_auto_vars"]
144
145# stderr_func_names is a list of functions whose output should go to stderr rather than stdout.
146stderr_func_names = []
147
148func_defs = gp.create_print_wrapper_funcs(
149    func_names, stderr_func_names, replace_dict, "r"
150)
151gp_debug_print(func_defs)
152exec(func_defs)
153
154# Define an alias.  rpvar is just a special case of rpvars where the args list contains only one element.
155cmd_buf = "rpvar = rpvars"
156gp_debug_print("\n" + cmd_buf + "\n")
157exec(cmd_buf)
158