1 # Copyright (C) 2010-2012 W. Trevor King <wking@tremily.us>
3 # This file is part of Hooke.
5 # Hooke is free software: you can redistribute it and/or modify it under the
6 # terms of the GNU Lesser General Public License as published by the Free
7 # Software Foundation, either version 3 of the License, or (at your option) any
10 # Hooke is distributed in the hope that it will be useful, but WITHOUT ANY
11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
12 # A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
15 # You should have received a copy of the GNU Lesser General Public License
16 # along with Hooke. If not, see <http://www.gnu.org/licenses/>.
18 """The `engine` module provides :class:`CommandEngine` for executing
19 :class:`hooke.command.Command`\s.
23 from Queue import Queue, Empty
25 from .command import NullQueue
28 class QueueMessage (object):
30 return self.__class__.__name__
33 class CloseEngine (QueueMessage):
37 class CommandMessage (QueueMessage):
38 """A message storing a command to run, `command` should be the
39 name of a :class:`hooke.command.Command` instance, and `arguments`
40 should be a :class:`dict` with `argname` keys and `value` values
41 to be passed to the command.
43 def __init__(self, command, arguments=None):
44 self.command = command
47 self.arguments = arguments
48 self.explicit_user_call = True
49 """Message is explicitly user-executed. This is useful for
50 distinguishing auto-generated calls (for which
51 `explicit_user_call` should be `False` such as the GUIs
52 current status requests.
56 return str(self.__unicode__())
58 def __unicode__(self):
59 """Return a unicode representation of the `CommandMessage`.
63 >>> from .compat.odict import odict
64 >>> cm = CommandMessage('command A')
66 <CommandMessage command A>
67 >>> cm.arguments = odict([('param a','value a'), ('param b', 'value b')])
69 <CommandMessage command A {param a: value a, param b: value b}>
71 The parameters are sorted by name, so you won't be surprised
74 >>> cm.arguments = odict([('param b','value b'), ('param a', 'value a')])
76 <CommandMessage command A {param a: value a, param b: value b}>
78 if len(self.arguments) > 0:
79 return u'<%s %s {%s}>' % (
80 self.__class__.__name__, self.command,
81 ', '.join(['%s: %s' % (key, value)
82 for key,value in sorted(self.arguments.items())]))
83 return u'<%s %s>' % (self.__class__.__name__, self.command)
89 class CommandEngine (object):
90 def run(self, hooke, ui_to_command_queue, command_to_ui_queue):
91 """Get a :class:`QueueMessage` from the incoming
92 `ui_to_command_queue` and act accordingly.
94 If the message is a :class:`CommandMessage` instance, the
95 command run may read subsequent input from
96 `ui_to_command_queue` (if it is an interactive command). The
97 command may also put assorted data into `command_to_ui_queue`.
99 When the command completes, it will put a
100 :class:`hooke.command.CommandExit` instance into
101 `command_to_ui_queue`, at which point the `CommandEngine` will
102 be ready to receive the next :class:`QueueMessage`.
104 log = logging.getLogger('hooke')
105 log.debug('engine starting')
106 for playlist in hooke.playlists: # Curve._hooke is not pickled.
107 for curve in playlist:
108 curve.set_hooke(hooke)
110 log.debug('engine waiting for command')
111 msg = ui_to_command_queue.get()
112 if isinstance(msg, CloseEngine):
113 command_to_ui_queue.put(hooke)
115 'engine closing, placed hooke instance in return queue')
117 assert isinstance(msg, CommandMessage), type(msg)
118 log.debug('engine running %s' % msg)
119 cmd = hooke.command_by_name[msg.command]
120 cmd.run(hooke, ui_to_command_queue, command_to_ui_queue,
123 def run_command(self, hooke, command, arguments):
124 """Run the command named `command` with `arguments` using
125 :meth:`~hooke.engine.CommandEngine.run_command`.
127 This allows commands to execute sub commands and enables
128 :class:`~hooke.command_stack.CommandStack` execution.
130 Note that these commands *do not* have access to the usual UI
131 communication queues, so make sure they will not need user
134 log = logging.getLogger('hooke')
135 log.debug('engine running internal %s'
136 % CommandMessage(command, arguments))
138 cmd = hooke.command_by_name[command]
139 cmd.run(hooke, NullQueue(), outqueue, **arguments)
142 msg = outqueue.get(block=False)
145 log.debug('engine message from %s (%s): %s' % (command, type(msg), msg))