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, gp.terse(),
96                                 indent)
97
98        return buffer
99
100    def print_obj(self):
101        r"""
102        print the fields of this object to stdout.  This would normally be for
103        debug purposes.
104        """
105
106        sys.stdout.write(self.sprint_obj())
107
108    def push(self,
109             var_value,
110             var_name=""):
111        r"""
112        push the var_name/var_value pair onto the stack.
113
114        Description of argument(s):
115        var_value                   The value being pushed.
116        var_name                    The name of the variable containing the
117                                    value to be pushed.  This parameter is
118                                    normally unnecessary as this function can
119                                    figure out the var_name.  This is provided
120                                    for Robot callers.  In this scenario, we
121                                    are unable to get the variable name
122                                    ourselves.
123        """
124
125        if var_name == "":
126            # The caller has not passed a var_name so we will try to figure
127            # it out.
128            stack_frame_ix = 2
129            var_name = gp.get_arg_name(0, 1, stack_frame_ix)
130        if var_name in self.__stack_dict:
131            self.__stack_dict[var_name].append(var_value)
132        else:
133            self.__stack_dict[var_name] = copy.deepcopy([var_value])
134
135    def pop(self,
136            var_name=""):
137        r"""
138        Pop the value for the given var_name from the stack and return it.
139
140        Description of argument(s):
141        var_name                    The name of the variable whose value is to
142                                    be popped.
143        """
144
145        return self.__stack_dict[var_name].pop()
146