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