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