1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
|
# Copyright (c) 2009, Google Inc. All rights reserved.
# Copyright (c) 2009 Apple Inc. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above
# copyright notice, this list of conditions and the following disclaimer
# in the documentation and/or other materials provided with the
# distribution.
# * Neither the name of Google Inc. nor the names of its
# contributors may be used to endorse or promote products derived from
# this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# MultiCommandTool provides a framework for writing svn-like/git-like tools
# which are called with the following format:
# tool-name [global options] command-name [command options]
import sys
from optparse import OptionParser, IndentedHelpFormatter, SUPPRESS_USAGE, make_option
from webkitpy.grammar import pluralize
from webkitpy.webkit_logging import log
class Command(object):
name = None
show_in_main_help = False
def __init__(self, help_text, argument_names=None, options=None, long_help=None, requires_local_commits=False):
self.help_text = help_text
self.long_help = long_help
self.argument_names = argument_names
self.required_arguments = self._parse_required_arguments(argument_names)
self.options = options
self.requires_local_commits = requires_local_commits
self.tool = None
# option_parser can be overriden by the tool using set_option_parser
# This default parser will be used for standalone_help printing.
self.option_parser = HelpPrintingOptionParser(usage=SUPPRESS_USAGE, add_help_option=False, option_list=self.options)
# This design is slightly awkward, but we need the
# the tool to be able to create and modify the option_parser
# before it knows what Command to run.
def set_option_parser(self, option_parser):
self.option_parser = option_parser
self._add_options_to_parser()
def _add_options_to_parser(self):
options = self.options or []
for option in options:
self.option_parser.add_option(option)
# The tool calls bind_to_tool on each Command after adding it to its list.
def bind_to_tool(self, tool):
# Command instances can only be bound to one tool at a time.
if self.tool and tool != self.tool:
raise Exception("Command already bound to tool!")
self.tool = tool
@staticmethod
def _parse_required_arguments(argument_names):
required_args = []
if not argument_names:
return required_args
split_args = argument_names.split(" ")
for argument in split_args:
if argument[0] == '[':
# For now our parser is rather dumb. Do some minimal validation that
# we haven't confused it.
if argument[-1] != ']':
raise Exception("Failure to parse argument string %s. Argument %s is missing ending ]" % (argument_names, argument))
else:
required_args.append(argument)
return required_args
def name_with_arguments(self):
usage_string = self.name
if self.options:
usage_string += " [options]"
if self.argument_names:
usage_string += " " + self.argument_names
return usage_string
def parse_args(self, args):
return self.option_parser.parse_args(args)
def check_arguments_and_execute(self, options, args, tool=None):
if len(args) < len(self.required_arguments):
log("%s required, %s provided. Provided: %s Required: %s\nSee '%s help %s' for usage." % (
pluralize("argument", len(self.required_arguments)),
pluralize("argument", len(args)),
"'%s'" % " ".join(args),
" ".join(self.required_arguments),
tool.name(),
self.name))
return 1
return self.execute(options, args, tool) or 0
def standalone_help(self):
help_text = self.name_with_arguments().ljust(len(self.name_with_arguments()) + 3) + self.help_text + "\n\n"
if self.long_help:
help_text += "%s\n\n" % self.long_help
help_text += self.option_parser.format_option_help(IndentedHelpFormatter())
return help_text
def execute(self, options, args, tool):
raise NotImplementedError, "subclasses must implement"
# main() exists so that Commands can be turned into stand-alone scripts.
# Other parts of the code will likely require modification to work stand-alone.
def main(self, args=sys.argv):
(options, args) = self.parse_args(args)
# Some commands might require a dummy tool
return self.check_arguments_and_execute(options, args)
# FIXME: This should just be rolled into Command. help_text and argument_names do not need to be instance variables.
class AbstractDeclarativeCommand(Command):
help_text = None
argument_names = None
long_help = None
def __init__(self, options=None, **kwargs):
Command.__init__(self, self.help_text, self.argument_names, options=options, long_help=self.long_help, **kwargs)
class HelpPrintingOptionParser(OptionParser):
def __init__(self, epilog_method=None, *args, **kwargs):
self.epilog_method = epilog_method
OptionParser.__init__(self, *args, **kwargs)
def error(self, msg):
self.print_usage(sys.stderr)
error_message = "%s: error: %s\n" % (self.get_prog_name(), msg)
# This method is overriden to add this one line to the output:
error_message += "\nType \"%s --help\" to see usage.\n" % self.get_prog_name()
self.exit(1, error_message)
# We override format_epilog to avoid the default formatting which would paragraph-wrap the epilog
# and also to allow us to compute the epilog lazily instead of in the constructor (allowing it to be context sensitive).
def format_epilog(self, epilog):
if self.epilog_method:
return "\n%s\n" % self.epilog_method()
return ""
class HelpCommand(AbstractDeclarativeCommand):
name = "help"
help_text = "Display information about this program or its subcommands"
argument_names = "[COMMAND]"
def __init__(self):
options = [
make_option("-a", "--all-commands", action="store_true", dest="show_all_commands", help="Print all available commands"),
]
AbstractDeclarativeCommand.__init__(self, options)
self.show_all_commands = False # A hack used to pass --all-commands to _help_epilog even though it's called by the OptionParser.
def _help_epilog(self):
# Only show commands which are relevant to this checkout's SCM system. Might this be confusing to some users?
if self.show_all_commands:
epilog = "All %prog commands:\n"
relevant_commands = self.tool.commands[:]
else:
epilog = "Common %prog commands:\n"
relevant_commands = filter(self.tool.should_show_in_main_help, self.tool.commands)
longest_name_length = max(map(lambda command: len(command.name), relevant_commands))
relevant_commands.sort(lambda a, b: cmp(a.name, b.name))
command_help_texts = map(lambda command: " %s %s\n" % (command.name.ljust(longest_name_length), command.help_text), relevant_commands)
epilog += "%s\n" % "".join(command_help_texts)
epilog += "See '%prog help --all-commands' to list all commands.\n"
epilog += "See '%prog help COMMAND' for more information on a specific command.\n"
return epilog.replace("%prog", self.tool.name()) # Use of %prog here mimics OptionParser.expand_prog_name().
# FIXME: This is a hack so that we don't show --all-commands as a global option:
def _remove_help_options(self):
for option in self.options:
self.option_parser.remove_option(option.get_opt_string())
def execute(self, options, args, tool):
if args:
command = self.tool.command_by_name(args[0])
if command:
print command.standalone_help()
return 0
self.show_all_commands = options.show_all_commands
self._remove_help_options()
self.option_parser.print_help()
return 0
class MultiCommandTool(object):
global_options = None
def __init__(self, name=None, commands=None):
self._name = name or OptionParser(prog=name).get_prog_name() # OptionParser has nice logic for fetching the name.
# Allow the unit tests to disable command auto-discovery.
self.commands = commands or [cls() for cls in self._find_all_commands() if cls.name]
self.help_command = self.command_by_name(HelpCommand.name)
# Require a help command, even if the manual test list doesn't include one.
if not self.help_command:
self.help_command = HelpCommand()
self.commands.append(self.help_command)
for command in self.commands:
command.bind_to_tool(self)
@classmethod
def _add_all_subclasses(cls, class_to_crawl, seen_classes):
for subclass in class_to_crawl.__subclasses__():
if subclass not in seen_classes:
seen_classes.add(subclass)
cls._add_all_subclasses(subclass, seen_classes)
@classmethod
def _find_all_commands(cls):
commands = set()
cls._add_all_subclasses(Command, commands)
return sorted(commands)
def name(self):
return self._name
def _create_option_parser(self):
usage = "Usage: %prog [options] COMMAND [ARGS]"
return HelpPrintingOptionParser(epilog_method=self.help_command._help_epilog, prog=self.name(), usage=usage)
@staticmethod
def _split_command_name_from_args(args):
# Assume the first argument which doesn't start with "-" is the command name.
command_index = 0
for arg in args:
if arg[0] != "-":
break
command_index += 1
else:
return (None, args[:])
command = args[command_index]
return (command, args[:command_index] + args[command_index + 1:])
def command_by_name(self, command_name):
for command in self.commands:
if command_name == command.name:
return command
return None
def path(self):
raise NotImplementedError, "subclasses must implement"
def should_show_in_main_help(self, command):
return command.show_in_main_help
def should_execute_command(self, command):
return True
def _add_global_options(self, option_parser):
global_options = self.global_options or []
for option in global_options:
option_parser.add_option(option)
def handle_global_options(self, options):
pass
def main(self, argv=sys.argv):
(command_name, args) = self._split_command_name_from_args(argv[1:])
option_parser = self._create_option_parser()
self._add_global_options(option_parser)
command = self.command_by_name(command_name) or self.help_command
if not command:
option_parser.error("%s is not a recognized command" % command_name)
command.set_option_parser(option_parser)
(options, args) = command.parse_args(args)
self.handle_global_options(options)
(should_execute, failure_reason) = self.should_execute_command(command)
if not should_execute:
log(failure_reason)
return 0 # FIXME: Should this really be 0?
return command.check_arguments_and_execute(options, args, self)
|