2052.3.2
by John Arbash Meinel
Change Copyright .. by Canonical to Copyright ... Canonical |
1 |
# Copyright (C) 2004, 2005, 2006 Canonical Ltd
|
1887.1.1
by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines, |
2 |
#
|
351
by Martin Pool
- Split out help functions into bzrlib.help |
3 |
# This program is free software; you can redistribute it and/or modify
|
4 |
# it under the terms of the GNU General Public License as published by
|
|
5 |
# the Free Software Foundation; either version 2 of the License, or
|
|
6 |
# (at your option) any later version.
|
|
1887.1.1
by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines, |
7 |
#
|
351
by Martin Pool
- Split out help functions into bzrlib.help |
8 |
# This program is distributed in the hope that it will be useful,
|
9 |
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
10 |
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
11 |
# GNU General Public License for more details.
|
|
1887.1.1
by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines, |
12 |
#
|
351
by Martin Pool
- Split out help functions into bzrlib.help |
13 |
# You should have received a copy of the GNU General Public License
|
14 |
# along with this program; if not, write to the Free Software
|
|
4183.7.1
by Sabin Iacob
update FSF mailing address |
15 |
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
351
by Martin Pool
- Split out help functions into bzrlib.help |
16 |
|
1162
by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to |
17 |
# TODO: Some way to get a list of external commands (defined by shell
|
18 |
# scripts) so that they can be included in the help listing as well.
|
|
19 |
# It should be enough to just list the plugin directory and look for
|
|
20 |
# executable files with reasonable names.
|
|
21 |
||
22 |
# TODO: `help commands --all` should show hidden commands
|
|
351
by Martin Pool
- Split out help functions into bzrlib.help |
23 |
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
24 |
import sys |
1185.12.55
by Aaron Bentley
did test wrapping for option text |
25 |
import textwrap |
2023.1.1
by ghigo
add topics help |
26 |
|
2070.4.3
by John Arbash Meinel
code and doc cleanup |
27 |
from bzrlib import ( |
2432.1.3
by Robert Collins
Create a HelpContexts object to do help lookups. |
28 |
commands as _mod_commands, |
2432.1.5
by Robert Collins
Initial stub for topic searching. |
29 |
errors, |
2070.4.3
by John Arbash Meinel
code and doc cleanup |
30 |
help_topics, |
31 |
osutils, |
|
2432.1.24
by Robert Collins
Add plugins as a help index. |
32 |
plugin, |
2432.1.31
by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function. |
33 |
symbol_versioning, |
2070.4.3
by John Arbash Meinel
code and doc cleanup |
34 |
)
|
1993.4.4
by John Arbash Meinel
cleanup help.py |
35 |
|
36 |
||
3984.4.5
by Ian Clatworthy
help xxx is full help; xxx -h is concise help |
37 |
def help(topic=None, outfile=None): |
2070.4.3
by John Arbash Meinel
code and doc cleanup |
38 |
"""Write the help for the specific topic to outfile"""
|
1993.4.4
by John Arbash Meinel
cleanup help.py |
39 |
if outfile is None: |
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
40 |
outfile = sys.stdout |
2070.4.13
by John Arbash Meinel
Switch help_topics to use a Registry. |
41 |
|
2432.1.16
by Robert Collins
Correct spelling of Indexs to Indices. |
42 |
indices = HelpIndices() |
2743.2.3
by Daniel Watkins
If an alias exists, it is displayed regardless of help also to be displayed. |
43 |
|
44 |
alias = _mod_commands.get_alias(topic) |
|
2743.2.1
by Daniel Watkins
Modified bzrlib.help to show the alias of a command if a NoHelpTopic exception is raised, reraising it if no alias exists. |
45 |
try: |
46 |
topics = indices.search(topic) |
|
47 |
shadowed_terms = [] |
|
48 |
for index, topic in topics[1:]: |
|
2762.1.1
by Ian Clatworthy
(Daniel Watkins) teach bzr help to recognize aliases |
49 |
shadowed_terms.append('%s%s' % (index.prefix, |
50 |
topic.get_help_topic())) |
|
3984.4.2
by Ian Clatworthy
make help on commands concise by default |
51 |
source = topics[0][1] |
3984.4.5
by Ian Clatworthy
help xxx is full help; xxx -h is concise help |
52 |
outfile.write(source.get_help_text(shadowed_terms)) |
2743.2.1
by Daniel Watkins
Modified bzrlib.help to show the alias of a command if a NoHelpTopic exception is raised, reraising it if no alias exists. |
53 |
except errors.NoHelpTopic: |
2743.2.5
by Daniel Watkins
Modified bzrlib.help as per abentley's comments. |
54 |
if alias is None: |
55 |
raise
|
|
56 |
||
57 |
if alias is not None: |
|
2762.1.1
by Ian Clatworthy
(Daniel Watkins) teach bzr help to recognize aliases |
58 |
outfile.write("'bzr %s' is an alias for 'bzr %s'.\n" % (topic, |
59 |
" ".join(alias))) |
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
60 |
|
61 |
||
1162
by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to |
62 |
def help_commands(outfile=None): |
351
by Martin Pool
- Split out help functions into bzrlib.help |
63 |
"""List all commands"""
|
2070.4.13
by John Arbash Meinel
Switch help_topics to use a Registry. |
64 |
if outfile is None: |
65 |
outfile = sys.stdout |
|
66 |
outfile.write(_help_commands_to_text('commands')) |
|
67 |
||
68 |
||
69 |
def _help_commands_to_text(topic): |
|
70 |
"""Generate the help text for the list of commands"""
|
|
71 |
out = [] |
|
1551.9.14
by Aaron Bentley
Change topic to hidden-commands |
72 |
if topic == 'hidden-commands': |
1551.9.13
by Aaron Bentley
add "hidden" topic |
73 |
hidden = True |
74 |
else: |
|
75 |
hidden = False |
|
4119.3.4
by Robert Collins
Add Command lookup hooks: list_commands and get_command. |
76 |
names = list(_mod_commands.all_command_names()) |
2432.1.3
by Robert Collins
Create a HelpContexts object to do help lookups. |
77 |
commands = ((n, _mod_commands.get_cmd_object(n)) for n in names) |
1551.9.13
by Aaron Bentley
add "hidden" topic |
78 |
shown_commands = [(n, o) for n, o in commands if o.hidden == hidden] |
2034.1.3
by Aaron Bentley
Changes from review and tweaks |
79 |
max_name = max(len(n) for n, o in shown_commands) |
80 |
indent = ' ' * (max_name + 1) |
|
2034.1.1
by Aaron Bentley
Condense command help text |
81 |
width = osutils.terminal_width() - 1 |
2070.4.13
by John Arbash Meinel
Switch help_topics to use a Registry. |
82 |
|
2034.1.3
by Aaron Bentley
Changes from review and tweaks |
83 |
for cmd_name, cmd_object in sorted(shown_commands): |
1733.2.5
by Michael Ellerman
Show which plugin (if any) provides a command. |
84 |
plugin_name = cmd_object.plugin_name() |
2034.1.1
by Aaron Bentley
Condense command help text |
85 |
if plugin_name is None: |
86 |
plugin_name = '' |
|
87 |
else: |
|
2034.1.4
by Aaron Bentley
Change angle brackets to square brackets |
88 |
plugin_name = ' [%s]' % plugin_name |
1733.2.5
by Michael Ellerman
Show which plugin (if any) provides a command. |
89 |
|
1162
by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to |
90 |
cmd_help = cmd_object.help() |
91 |
if cmd_help: |
|
92 |
firstline = cmd_help.split('\n', 1)[0] |
|
2034.1.1
by Aaron Bentley
Condense command help text |
93 |
else: |
94 |
firstline = '' |
|
2034.1.3
by Aaron Bentley
Changes from review and tweaks |
95 |
helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name) |
4070.11.2
by Martin Pool
Ask textwrap not to break long words or on hyphens |
96 |
lines = textwrap.wrap( |
97 |
helpstring, subsequent_indent=indent, |
|
98 |
width=width, |
|
4070.11.5
by Martin Pool
textwrap break_on_hyphens option is not available in python2.5 |
99 |
break_long_words=False) |
2034.1.1
by Aaron Bentley
Condense command help text |
100 |
for line in lines: |
2070.4.13
by John Arbash Meinel
Switch help_topics to use a Registry. |
101 |
out.append(line + '\n') |
102 |
return ''.join(out) |
|
103 |
||
104 |
||
105 |
help_topics.topic_registry.register("commands", |
|
106 |
_help_commands_to_text, |
|
2666.1.1
by Ian Clatworthy
Bazaar User Reference generated from online help |
107 |
"Basic help for all commands", |
108 |
help_topics.SECT_HIDDEN) |
|
2432.1.1
by Robert Collins
Add a HelpTopicContext object. |
109 |
help_topics.topic_registry.register("hidden-commands", |
1551.9.13
by Aaron Bentley
add "hidden" topic |
110 |
_help_commands_to_text, |
2666.1.1
by Ian Clatworthy
Bazaar User Reference generated from online help |
111 |
"All hidden commands", |
112 |
help_topics.SECT_HIDDEN) |
|
2432.1.3
by Robert Collins
Create a HelpContexts object to do help lookups. |
113 |
|
114 |
||
2432.1.16
by Robert Collins
Correct spelling of Indexs to Indices. |
115 |
class HelpIndices(object): |
2432.1.31
by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function. |
116 |
"""Maintainer of help topics across multiple indices.
|
3943.8.1
by Marius Kruger
remove all trailing whitespace from bzr source |
117 |
|
2432.1.31
by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function. |
118 |
It is currently separate to the HelpTopicRegistry because of its ordered
|
119 |
nature, but possibly we should instead structure it as a search within the
|
|
120 |
registry and add ordering and searching facilities to the registry. The
|
|
121 |
registry would probably need to be restructured to support that cleanly
|
|
122 |
which is why this has been implemented in parallel even though it does as a
|
|
123 |
result permit searching for help in indices which are not discoverable via
|
|
2432.1.9
by Robert Collins
Expand HelpContexts documentation. |
124 |
'help topics'.
|
2432.1.31
by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function. |
125 |
|
126 |
Each index has a unique prefix string, such as "commands", and contains
|
|
127 |
help topics which can be listed or searched.
|
|
2432.1.9
by Robert Collins
Expand HelpContexts documentation. |
128 |
"""
|
2432.1.3
by Robert Collins
Create a HelpContexts object to do help lookups. |
129 |
|
130 |
def __init__(self): |
|
131 |
self.search_path = [ |
|
2432.1.15
by Robert Collins
Rename Context (in bzrlib.help) to Index, for a clearer name. |
132 |
help_topics.HelpTopicIndex(), |
133 |
_mod_commands.HelpCommandIndex(), |
|
2432.1.24
by Robert Collins
Add plugins as a help index. |
134 |
plugin.PluginsHelpIndex(), |
2432.1.3
by Robert Collins
Create a HelpContexts object to do help lookups. |
135 |
]
|
2432.1.5
by Robert Collins
Initial stub for topic searching. |
136 |
|
2432.1.19
by Robert Collins
Ensure each HelpIndex has a unique prefix. |
137 |
def _check_prefix_uniqueness(self): |
138 |
"""Ensure that the index collection is able to differentiate safely."""
|
|
139 |
prefixes = {} |
|
140 |
for index in self.search_path: |
|
141 |
prefixes.setdefault(index.prefix, []).append(index) |
|
142 |
for prefix, indices in prefixes.items(): |
|
143 |
if len(indices) > 1: |
|
144 |
raise errors.DuplicateHelpPrefix(prefix) |
|
145 |
||
2432.1.5
by Robert Collins
Initial stub for topic searching. |
146 |
def search(self, topic): |
147 |
"""Search for topic across the help search path.
|
|
3943.8.1
by Marius Kruger
remove all trailing whitespace from bzr source |
148 |
|
2432.1.5
by Robert Collins
Initial stub for topic searching. |
149 |
:param topic: A string naming the help topic to search for.
|
2432.1.15
by Robert Collins
Rename Context (in bzrlib.help) to Index, for a clearer name. |
150 |
:raises: NoHelpTopic if none of the indexs in search_path have topic.
|
2432.1.7
by Robert Collins
HelpContexts.search now returns the found topics. |
151 |
:return: A list of HelpTopics which matched 'topic'.
|
2432.1.5
by Robert Collins
Initial stub for topic searching. |
152 |
"""
|
2432.1.19
by Robert Collins
Ensure each HelpIndex has a unique prefix. |
153 |
self._check_prefix_uniqueness() |
2432.1.6
by Robert Collins
HelpContexts.search now invokes get_topics on each context. |
154 |
result = [] |
2432.1.15
by Robert Collins
Rename Context (in bzrlib.help) to Index, for a clearer name. |
155 |
for index in self.search_path: |
2432.1.20
by Robert Collins
Modify the result of HelpIndices.search to include the index each result was found in. |
156 |
result.extend([(index, _topic) for _topic in index.get_topics(topic)]) |
2432.1.6
by Robert Collins
HelpContexts.search now invokes get_topics on each context. |
157 |
if not result: |
158 |
raise errors.NoHelpTopic(topic) |
|
2432.1.7
by Robert Collins
HelpContexts.search now returns the found topics. |
159 |
else: |
160 |
return result |