1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
3 # This file is part of Hooke.
5 # Hooke is free software: you can redistribute it and/or modify it
6 # under the terms of the GNU Lesser General Public License as
7 # published by the Free Software Foundation, either version 3 of the
8 # License, or (at your option) any later version.
10 # Hooke is distributed in the hope that it will be useful, but WITHOUT
11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
13 # Public License for more details.
15 # You should have received a copy of the GNU Lesser General Public
16 # License along with Hooke. If not, see
17 # <http://www.gnu.org/licenses/>.
19 """The ``command_stack`` module provides tools for managing and
20 executing stacks of :class:`~hooke.engine.CommandMessage`\s.
28 from .engine import CommandMessage
31 class CommandStack (list):
32 """Store a stack of commands.
36 >>> c = CommandStack([CommandMessage('CommandA', {'param':'A'})])
37 >>> c.append(CommandMessage('CommandB', {'param':'B'}))
38 >>> c.append(CommandMessage('CommandA', {'param':'C'}))
39 >>> c.append(CommandMessage('CommandB', {'param':'D'}))
41 Implement a dummy :meth:`execute_command` for testing.
43 >>> def execute_cmd(hooke, command_message, stack=None):
44 ... cm = command_message
45 ... print 'EXECUTE', cm.command, cm.arguments
46 >>> c.execute_command = execute_cmd
48 >>> c.execute(hooke=None) # doctest: +ELLIPSIS
49 EXECUTE CommandA {'param': 'A'}
50 EXECUTE CommandB {'param': 'B'}
51 EXECUTE CommandA {'param': 'C'}
52 EXECUTE CommandB {'param': 'D'}
54 :meth:`filter` allows you to select which commands get executed.
55 If, for example, you are applying a set of commands to the current
56 :class:`~hooke.curve.Curve`, you may only want to execute
57 instances of :class:`~hooke.plugin.curve.CurveCommand`. Here we
58 only execute commands named `CommandB`.
60 >>> def filter(hooke, command_message):
61 ... return command_message.command == 'CommandB'
64 Apply the stack to the current curve.
66 >>> c.execute(hooke=None) # doctest: +ELLIPSIS
67 EXECUTE CommandB {'param': 'B'}
68 EXECUTE CommandB {'param': 'D'}
70 Execute a new command and add it to the stack.
72 >>> cm = CommandMessage('CommandC', {'param':'E'})
73 >>> c.execute_command(hooke=None, command_message=cm)
74 EXECUTE CommandC {'param': 'E'}
76 >>> print [repr(cm) for cm in c] # doctest: +NORMALIZE_WHITESPACE
77 ['<CommandMessage CommandA {param: A}>',
78 '<CommandMessage CommandB {param: B}>',
79 '<CommandMessage CommandA {param: C}>',
80 '<CommandMessage CommandB {param: D}>',
81 '<CommandMessage CommandC {param: E}>']
83 The data-type is also pickleable, to ensure we can move it between
84 processes with :class:`multiprocessing.Queue`\s and easily save it
88 >>> s = pickle.dumps(c)
89 >>> z = pickle.loads(s)
90 >>> print [repr(cm) for cm in c] # doctest: +NORMALIZE_WHITESPACE
91 ['<CommandMessage CommandA {param: A}>',
92 '<CommandMessage CommandB {param: B}>',
93 '<CommandMessage CommandA {param: C}>',
94 '<CommandMessage CommandB {param: D}>',
95 '<CommandMessage CommandC {param: E}>']
97 There is also a convenience function for clearing the stack.
100 >>> print [repr(cm) for cm in c]
103 def __getstate__(self):
104 state = [{'command':cm.command, 'arguments':cm.arguments}
108 def __setstate__(self, state):
110 for cm_state in state:
111 self.append(CommandMessage(
112 command=cm_state['command'],
113 arguments=cm_state['arguments']))
115 def execute(self, hooke, stack=False):
116 """Execute a stack of commands.
122 for command_message in self:
123 if self.filter(hooke, command_message) == True:
124 self.execute_command(
125 hooke=hooke, command_message=command_message, stack=stack)
127 def filter(self, hooke, command_message):
128 """Return `True` to execute `command_message`, `False` otherwise.
130 The default implementation always returns `True`.
134 def execute_command(self, hooke, command_message, stack=False):
135 arguments = dict(command_message.arguments)
136 arguments['stack'] = stack
137 hooke.run_command(command=command_message.command,
145 class FileCommandStack (CommandStack):
146 """A file-backed :class:`CommandStack`.
150 def __init__(self, *args, **kwargs):
151 super(FileCommandStack, self).__init__(*args, **kwargs)
152 self.name = self.path = None
154 def __getstate__(self):
155 command_stack = super(FileCommandStack, self).__getstate__()
157 'command stack': command_stack,
163 def __setstate__(self, state):
164 super(FileCommandStack, self).__setstate__(
165 state.get('command stack', []))
166 self.name = state.get('name', None)
168 self.set_path(state.get('path', None))
170 def set_path(self, path):
171 """Set the path (and possibly the name) of the command stack.
175 >>> c = FileCommandStack([CommandMessage('CommandA', {'param':'A'})])
177 :attr:`name` is set only if it starts out equal to `None`.
180 >>> c.set_path(os.path.join('path', 'to', 'my', 'command', 'stack'))
182 'path/to/my/command/stack'
185 >>> c.set_path(os.path.join('another', 'path'))
193 if self.name == None:
194 self.name = os.path.basename(path)
196 def save(self, path=None, makedirs=True):
197 """Saves the command stack to `path`.
200 dirname = os.path.dirname(self.path) or '.'
201 if makedirs == True and not os.path.isdir(dirname):
203 with open(self.path, 'w') as f:
204 f.write(self.flatten())
206 def load(self, path=None):
207 """Load a command stack from `path`.
210 with open(self.path, 'r') as f:
212 self.from_string(text)
215 """Create a string representation of the command stack.
217 A playlist is a YAML document with the following syntax::
219 - arguments: {param: A}
221 - arguments: {param: B, ...}
227 >>> c = FileCommandStack([CommandMessage('CommandA', {'param':'A'})])
228 >>> c.append(CommandMessage('CommandB', {'param':'B'}))
229 >>> c.append(CommandMessage('CommandA', {'param':'C'}))
230 >>> c.append(CommandMessage('CommandB', {'param':'D'}))
231 >>> print c.flatten()
232 - arguments: {param: A}
234 - arguments: {param: B}
236 - arguments: {param: C}
238 - arguments: {param: D}
242 return yaml.dump([{'command':cm.command,'arguments':cm.arguments}
245 def from_string(self, string):
246 """Load a playlist from a string.
248 .. warning:: This is *not safe* with untrusted input.
253 >>> string = '''- arguments: {param: A}
254 ... command: CommandA
255 ... - arguments: {param: B}
256 ... command: CommandB
257 ... - arguments: {param: C}
258 ... command: CommandA
259 ... - arguments: {param: D}
260 ... command: CommandB
262 >>> c = FileCommandStack()
263 >>> c.from_string(string)
264 >>> print [repr(cm) for cm in c] # doctest: +NORMALIZE_WHITESPACE
265 ['<CommandMessage CommandA {param: A}>',
266 '<CommandMessage CommandB {param: B}>',
267 '<CommandMessage CommandA {param: C}>',
268 '<CommandMessage CommandB {param: D}>']
270 for x in yaml.load(string):
271 self.append(CommandMessage(command=x['command'],
272 arguments=x['arguments']))