1#!/usr/bin/env python
2
3r"""
4Define the var_stack class.
5"""
6
7import sys
8import collections
9import copy
10
11try:
12    from robot.utils import DotDict
13except ImportError:
14    pass
15
16import gen_print as gp
17
18
19class var_stack:
20
21    r"""
22    Define the variable stack class.
23
24    An object of this class can be used to push variable name/variable value pairs which may be popped off
25    the stack at a later time.  The most obvious use for this is for saving variables that are to be restored
26    later.
27
28    Example code:
29
30    save_stack = var_stack('save_stack')
31    var1 = "johnson"
32    save_stack.push(var1)
33    var1 = "smith"
34    ...
35    var1 = save_stack.pop('var1')
36    # var1 has now been restored to the value "johnson".
37
38
39    Example use:
40
41    var1 = "mike"
42    save_stack.push(var1)
43    var1 = "james"
44    save_stack.push(var1)
45    save_stack.print_obj()
46
47    # The print-out of the object would then look like this:
48
49    save_stack:
50      stack_dict:
51        [var1]:
52          [var1][0]:  mike
53          [var1][1]:  james
54
55    # Continuing with this code...
56
57    var1 = save_stack.pop('var1')
58    save_stack.print_obj()
59
60    # The print-out of the object would then look like this:
61
62    save_stack:
63      stack_dict:
64        [var1]:
65          [var1][0]:  mike
66    """
67
68    def __init__(self,
69                 obj_name='var_stack'):
70        r"""
71        Initialize a new object of this class type.
72
73        Description of argument(s):
74        obj_name                    The name of the object.  This is useful for printing out the object.
75        """
76
77        self.__obj_name = obj_name
78        # Create a stack dictionary.
79        try:
80            self.__stack_dict = collections.OrderedDict()
81        except AttributeError:
82            self.__stack_dict = DotDict()
83
84    def sprint_obj(self):
85        r"""
86        sprint the fields of this object.  This would normally be for debug purposes.
87        """
88
89        buffer = ""
90
91        buffer += self.__obj_name + ":\n"
92        indent = 2
93        buffer += gp.sprint_varx('stack_dict', self.__stack_dict, indent)
94
95        return buffer
96
97    def print_obj(self):
98        r"""
99        print the fields of this object to stdout.  This would normally be for debug purposes.
100        """
101
102        sys.stdout.write(self.sprint_obj())
103
104    def push(self,
105             var_value,
106             var_name=""):
107        r"""
108        push the var_name/var_value pair onto the stack.
109
110        Description of argument(s):
111        var_value                   The value being pushed.
112        var_name                    The name of the variable containing the value to be pushed.  This
113                                    parameter is normally unnecessary as this function can figure out the
114                                    var_name.  This is provided for Robot callers.  In this scenario, we are
115                                    unable to get the variable name ourselves.
116        """
117
118        if var_name == "":
119            # The caller has not passed a var_name so we will try to figure it out.
120            stack_frame_ix = 2
121            var_name = gp.get_arg_name(0, 1, stack_frame_ix)
122        if var_name in self.__stack_dict:
123            self.__stack_dict[var_name].append(var_value)
124        else:
125            self.__stack_dict[var_name] = copy.deepcopy([var_value])
126
127    def pop(self,
128            var_name=""):
129        r"""
130        Pop the value for the given var_name from the stack and return it.
131
132        Description of argument(s):
133        var_name                    The name of the variable whose value is to be popped.
134        """
135
136        return self.__stack_dict[var_name].pop()
137