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
25    pairs which may be popped off the stack at a later time.  The most obvious
26    use for this is for saving variables that are to be restored 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
75                                    for printing out the object.
76        """
77
78        self.__obj_name = obj_name
79        # Create a stack dictionary.
80        try:
81            self.__stack_dict = collections.OrderedDict()
82        except AttributeError:
83            self.__stack_dict = DotDict()
84
85    def sprint_obj(self):
86        r"""
87        sprint the fields of this object.  This would normally be for debug
88        purposes.
89        """
90
91        buffer = ""
92
93        buffer += self.__obj_name + ":\n"
94        indent = 2
95        buffer += gp.sprint_varx('stack_dict', self.__stack_dict, indent)
96
97        return buffer
98
99    def print_obj(self):
100        r"""
101        print the fields of this object to stdout.  This would normally be for
102        debug purposes.
103        """
104
105        sys.stdout.write(self.sprint_obj())
106
107    def push(self,
108             var_value,
109             var_name=""):
110        r"""
111        push the var_name/var_value pair onto the stack.
112
113        Description of argument(s):
114        var_value                   The value being pushed.
115        var_name                    The name of the variable containing the
116                                    value to be pushed.  This parameter is
117                                    normally unnecessary as this function can
118                                    figure out the var_name.  This is provided
119                                    for Robot callers.  In this scenario, we
120                                    are unable to get the variable name
121                                    ourselves.
122        """
123
124        if var_name == "":
125            # The caller has not passed a var_name so we will try to figure
126            # it out.
127            stack_frame_ix = 2
128            var_name = gp.get_arg_name(0, 1, stack_frame_ix)
129        if var_name in self.__stack_dict:
130            self.__stack_dict[var_name].append(var_value)
131        else:
132            self.__stack_dict[var_name] = copy.deepcopy([var_value])
133
134    def pop(self,
135            var_name=""):
136        r"""
137        Pop the value for the given var_name from the stack and return it.
138
139        Description of argument(s):
140        var_name                    The name of the variable whose value is to
141                                    be popped.
142        """
143
144        return self.__stack_dict[var_name].pop()
145