blob: d1e8d234f3c5dfc9bda3248e88a1f5464c7a7d50 [file] [log] [blame]
George Keishinge7e91712021-09-03 11:28:44 -05001#!/usr/bin/env python3
Michael Walsh18176322016-11-15 15:11:21 -06002
3r"""
Michael Walsh410b1782019-10-22 15:56:18 -05004This module provides validation functions like valid_value(), valid_integer(), etc. for robot programs.
Michael Walsh18176322016-11-15 15:11:21 -06005"""
6
Michael Walsh84230c22019-08-01 12:23:07 -05007import re
Patrick Williams20f38712022-12-08 06:18:26 -06008
9import func_args as fa
Michael Walshc108e422019-03-28 12:27:18 -050010import gen_print as gp
Michael Walsh18176322016-11-15 15:11:21 -060011import gen_valid as gv
Michael Walsh18176322016-11-15 15:11:21 -060012from robot.libraries.BuiltIn import BuiltIn
Michael Walsh18176322016-11-15 15:11:21 -060013
14
Michael Walsh84230c22019-08-01 12:23:07 -050015def valid_var_name(var_name):
Michael Walsh18176322016-11-15 15:11:21 -060016 r"""
Michael Walsh84230c22019-08-01 12:23:07 -050017 Validate the robot variable name and return its value.
Michael Walsh3e26e102017-01-10 11:29:28 -060018
Michael Walsh410b1782019-10-22 15:56:18 -050019 If the variable is undefined, this function will print an error message and call BuiltIn().fail().
Michael Walsh18176322016-11-15 15:11:21 -060020
Michael Walsh84230c22019-08-01 12:23:07 -050021 Description of arguments():
Michael Walsh410b1782019-10-22 15:56:18 -050022 var_name The name of the robot variable (e.g. "var1"). Do not include "${}" (e.g.
23 "${var1}". Just provide the simple name of the variable.
Michael Walsh18176322016-11-15 15:11:21 -060024 """
25
26 # Note: get_variable_value() seems to have no trouble with local variables.
27 var_value = BuiltIn().get_variable_value("${" + var_name + "}")
Michael Walsh18176322016-11-15 15:11:21 -060028 if var_value is None:
Michael Walsh84230c22019-08-01 12:23:07 -050029 var_value = "<undefined>"
Patrick Williams20f38712022-12-08 06:18:26 -060030 error_message = gv.valid_value(
31 var_value, invalid_values=[var_value], var_name=var_name
32 )
Michael Walsh18176322016-11-15 15:11:21 -060033 BuiltIn().fail(error_message)
34
Michael Walsh84230c22019-08-01 12:23:07 -050035 return var_value
Michael Walsh18176322016-11-15 15:11:21 -060036
Michael Walsh84230c22019-08-01 12:23:07 -050037
38def valid_init(var_name, *args, **kwargs):
Michael Walsh18176322016-11-15 15:11:21 -060039 r"""
Michael Walsh410b1782019-10-22 15:56:18 -050040 Do initialization for variable validation and return var_name, args and kwargs.
Michael Walsh3e26e102017-01-10 11:29:28 -060041
Michael Walsh410b1782019-10-22 15:56:18 -050042 This function is to be called by all of the various validation functions in this module.
Michael Walsh18176322016-11-15 15:11:21 -060043
Michael Walsh84230c22019-08-01 12:23:07 -050044 This function is designed solely for use by other functions in this file.
Michael Walsh18176322016-11-15 15:11:21 -060045
Michael Walsh84230c22019-08-01 12:23:07 -050046 Description of argument(s):
47 var_name The name of the variable to be validated.
Michael Walsh410b1782019-10-22 15:56:18 -050048 args The positional arguments to be passed to a validation function.
49 kwargs The keyword arguments to be passed to a validation function.
Michael Walsh18176322016-11-15 15:11:21 -060050 """
51
Michael Walsh84230c22019-08-01 12:23:07 -050052 var_value = valid_var_name(var_name)
Michael Walsh410b1782019-10-22 15:56:18 -050053 # Convert python string object definitions to objects (useful for robot callers).
Michael Walsh84230c22019-08-01 12:23:07 -050054 args = fa.args_to_objects(args)
55 kwargs = fa.args_to_objects(kwargs)
56 return var_value, args, kwargs
Michael Walsh2c687e92018-05-09 11:47:56 -050057
58
Michael Walsh84230c22019-08-01 12:23:07 -050059def process_error_message(error_message):
Michael Walsh2c687e92018-05-09 11:47:56 -050060 r"""
Michael Walsh84230c22019-08-01 12:23:07 -050061 Process an error message.
Michael Walsh2c687e92018-05-09 11:47:56 -050062
Michael Walsh84230c22019-08-01 12:23:07 -050063 If error_message is non-blank, fail. Otherwise, do nothing.
Michael Walsh2c687e92018-05-09 11:47:56 -050064
Michael Walsh84230c22019-08-01 12:23:07 -050065 This function is designed solely for use by other functions in this file.
Michael Walsh2c687e92018-05-09 11:47:56 -050066
Michael Walsh84230c22019-08-01 12:23:07 -050067 Description of argument(s):
68 error_message The error message to be processed.
Michael Walsh2c687e92018-05-09 11:47:56 -050069 """
70
Michael Walsh84230c22019-08-01 12:23:07 -050071 if error_message:
Michael Walshc108e422019-03-28 12:27:18 -050072 error_message = gp.sprint_error_report(error_message)
Michael Walsh2c687e92018-05-09 11:47:56 -050073 BuiltIn().fail(error_message)
Michael Walsh84230c22019-08-01 12:23:07 -050074
75
Michael Walsh410b1782019-10-22 15:56:18 -050076# The docstring header will be pre-pended to each validation function's existing docstring.
Patrick Williams20f38712022-12-08 06:18:26 -060077docstring_header = r"""
Michael Walsh84230c22019-08-01 12:23:07 -050078 Fail if the variable named by var_name is invalid.
79 """
80
81
82def customize_doc_string(doc_string):
83 r"""
84 Customize a gen_valid function docstring and return the result.
85
86 This function is designed solely for use by other functions in this file.
87
Michael Walsh410b1782019-10-22 15:56:18 -050088 The caller should pass a docstring from a gen_valid.py validation function. This docstring will be
89 changed to make a suitable docstring for this module's corresponding validation function.
Michael Walsh84230c22019-08-01 12:23:07 -050090
91 For example:
92
Michael Walsh410b1782019-10-22 15:56:18 -050093 Let's suppose that gen_valid.py has a function called "valid_value()". This module could make the
94 following call to essentially copy gen_valid's "valid_value()" function, modify it and then assign it to
95 the local version of the valid_value() function.
Michael Walsh84230c22019-08-01 12:23:07 -050096
97 valid.__doc__ = customize_doc_string(gv.valid.__doc__)
98
99 Description of argument(s):
100 doc_string The docstring to be customized.
101 """
102
103 doc_string = docstring_header + doc_string
104 doc_string = doc_string.split("\n")
105
106 start_ix = 0
107 # Find the "var_value" line.
Patrick Williams20f38712022-12-08 06:18:26 -0600108 start_ix = next(
109 (
110 index
111 for index, value in enumerate(doc_string[start_ix:], start_ix)
112 if re.match("[ ]+var_value ", value)
113 ),
114 None,
115 )
Michael Walsh84230c22019-08-01 12:23:07 -0500116 # Replace the "var_value" line with our "var_name" line.
Patrick Williams20f38712022-12-08 06:18:26 -0600117 doc_string[start_ix] = (
118 " var_name "
Michael Walsh84230c22019-08-01 12:23:07 -0500119 + "The name of the variable to be validated."
Patrick Williams20f38712022-12-08 06:18:26 -0600120 )
Michael Walsh84230c22019-08-01 12:23:07 -0500121
122 return "\n".join(doc_string)
123
124
Michael Walsh410b1782019-10-22 15:56:18 -0500125# All of the following functions are robot wrappers for the equivalent functions defined in gen_valid.py.
126# Note that the only difference between any two of these locally defined functions is the function name and
127# the gv.<function name> which they call. Also, note that the docstring for each is created by modifying the
128# docstring from the supporting gen_valid.py function.
Michael Walsh84230c22019-08-01 12:23:07 -0500129
George Keishinge635ddc2022-12-08 07:38:02 -0600130
Patrick Williams20f38712022-12-08 06:18:26 -0600131def valid_type(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500132 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600133 error_message = gv.valid_type(
134 var_value, *args, var_name=var_name, **kwargs
135 )
Michael Walsh84230c22019-08-01 12:23:07 -0500136 process_error_message(error_message)
137
138
139def valid_value(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500140 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600141 error_message = gv.valid_value(
142 var_value, *args, var_name=var_name, **kwargs
143 )
Michael Walsh84230c22019-08-01 12:23:07 -0500144 process_error_message(error_message)
145
146
147def valid_range(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500148 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600149 error_message = gv.valid_range(
150 var_value, *args, var_name=var_name, **kwargs
151 )
Michael Walsh84230c22019-08-01 12:23:07 -0500152 process_error_message(error_message)
153
154
155def valid_integer(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500156 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600157 error_message = gv.valid_integer(
158 var_value, *args, var_name=var_name, **kwargs
159 )
Michael Walsh84230c22019-08-01 12:23:07 -0500160 process_error_message(error_message)
161
162
Michael Walsh8333a182019-10-22 16:19:00 -0500163def valid_float(var_name, *args, **kwargs):
Michael Walsh8333a182019-10-22 16:19:00 -0500164 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600165 error_message = gv.valid_float(
166 var_value, *args, var_name=var_name, **kwargs
167 )
Michael Walsh8333a182019-10-22 16:19:00 -0500168 process_error_message(error_message)
169
170
171def valid_date_time(var_name, *args, **kwargs):
Michael Walsh8333a182019-10-22 16:19:00 -0500172 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600173 error_message = gv.valid_date_time(
174 var_value, *args, var_name=var_name, **kwargs
175 )
Michael Walsh8333a182019-10-22 16:19:00 -0500176 process_error_message(error_message)
177
178
Michael Walsh84230c22019-08-01 12:23:07 -0500179def valid_dir_path(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500180 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600181 error_message = gv.valid_dir_path(
182 var_value, *args, var_name=var_name, **kwargs
183 )
Michael Walsh84230c22019-08-01 12:23:07 -0500184 process_error_message(error_message)
185
186
187def valid_file_path(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500188 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600189 error_message = gv.valid_file_path(
190 var_value, *args, var_name=var_name, **kwargs
191 )
Michael Walsh84230c22019-08-01 12:23:07 -0500192 process_error_message(error_message)
193
194
195def valid_path(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500196 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600197 error_message = gv.valid_path(
198 var_value, *args, var_name=var_name, **kwargs
199 )
Michael Walsh84230c22019-08-01 12:23:07 -0500200 process_error_message(error_message)
201
202
203def valid_list(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500204 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600205 error_message = gv.valid_list(
206 var_value, *args, var_name=var_name, **kwargs
207 )
Michael Walsh84230c22019-08-01 12:23:07 -0500208 process_error_message(error_message)
209
210
211def valid_dict(var_name, *args, **kwargs):
Michael Walsh84230c22019-08-01 12:23:07 -0500212 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600213 error_message = gv.valid_dict(
214 var_value, *args, var_name=var_name, **kwargs
215 )
Michael Walsh84230c22019-08-01 12:23:07 -0500216 process_error_message(error_message)
217
218
Michael Walshbe3a8152019-08-20 16:38:19 -0500219def valid_program(var_name, *args, **kwargs):
Michael Walshbe3a8152019-08-20 16:38:19 -0500220 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600221 error_message = gv.valid_program(
222 var_value, *args, var_name=var_name, **kwargs
223 )
Michael Walshbe3a8152019-08-20 16:38:19 -0500224 process_error_message(error_message)
225
226
Michael Walshb9d8dfd2019-09-11 11:11:12 -0500227def valid_length(var_name, *args, **kwargs):
Michael Walshb9d8dfd2019-09-11 11:11:12 -0500228 var_value, args, kwargs = valid_init(var_name, *args, **kwargs)
Patrick Williams20f38712022-12-08 06:18:26 -0600229 error_message = gv.valid_length(
230 var_value, *args, var_name=var_name, **kwargs
231 )
Michael Walshb9d8dfd2019-09-11 11:11:12 -0500232 process_error_message(error_message)
233
234
Michael Walsh410b1782019-10-22 15:56:18 -0500235# Modify the validation function docstrings by calling customize_doc_string for each function in the
236# func_names list.
Michael Walsh84230c22019-08-01 12:23:07 -0500237func_names = [
Patrick Williams20f38712022-12-08 06:18:26 -0600238 "valid_type",
239 "valid_value",
240 "valid_range",
241 "valid_integer",
242 "valid_dir_path",
243 "valid_file_path",
244 "valid_path",
245 "valid_list",
246 "valid_dict",
247 "valid_program",
248 "valid_length",
249 "valid_float",
250 "valid_date_time",
Michael Walsh84230c22019-08-01 12:23:07 -0500251]
252
253for func_name in func_names:
Patrick Williams20f38712022-12-08 06:18:26 -0600254 cmd_buf = (
255 func_name
256 + ".__doc__ = customize_doc_string(gv.raw_doc_strings['"
257 + func_name
258 + "'])"
259 )
Michael Walsh84230c22019-08-01 12:23:07 -0500260 exec(cmd_buf)