Mercurial > public > mercurial-scm > hg-stable

comparison mercurial/extensions.py @ 24124:042d95beeee8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
extensions: allow extending command synopsis and docstring Mercurial uses a synopsis string and the docstring of a command for the command's help output. Today there is no way for an extension that adds functionality to a command to extend either of these help strings. This patch enables appending to both the doctring and the synopsis, and adds a test for this functionality. Example usage is shown in the test and is also described in the docstring of extensions.wrapcommand().
author Ryan McElroy <rm@fb.com>
date Mon, 09 Feb 2015 11:02:45 -0800
parents d8837ad682dd
children 28af978c8f13
comparison
equal deleted inserted replaced
24123:eb2d41c6ec37 24124:042d95beeee8
150 if extension in _extensions: 150 if extension in _extensions:
151 callback(loaded=False) 151 callback(loaded=False)
152 else: 152 else:
153 _aftercallbacks.setdefault(extension, []).append(callback) 153 _aftercallbacks.setdefault(extension, []).append(callback)
154 154
155 def wrapcommand(table, command, wrapper): 155 def wrapcommand(table, command, wrapper, synopsis=None, docstring=None):
156 '''Wrap the command named `command' in table 156 '''Wrap the command named `command' in table
157 157
158 Replace command in the command table with wrapper. The wrapped command will 158 Replace command in the command table with wrapper. The wrapped command will
159 be inserted into the command table specified by the table argument. 159 be inserted into the command table specified by the table argument.
160 160
162 162
163 wrapper(orig, *args, **kwargs) 163 wrapper(orig, *args, **kwargs)
164 164
165 where orig is the original (wrapped) function, and *args, **kwargs 165 where orig is the original (wrapped) function, and *args, **kwargs
166 are the arguments passed to it. 166 are the arguments passed to it.
167
168 Optionally append to the command synopsis and docstring, used for help.
169 For example, if your extension wraps the ``bookmarks`` command to add the
170 flags ``--remote`` and ``--all`` you might call this function like so:
171
172 synopsis = ' [-a] [--remote]'
173 docstring = """
174
175 The ``remotenames`` extension adds the ``--remote`` and ``--all`` (``-a``)
176 flags to the bookmarks command. Either flag will show the remote bookmarks
177 known to the repository; ``--remote`` will also supress the output of the
178 local bookmarks.
179 """
180
181 extensions.wrapcommand(commands.table, 'bookmarks', exbookmarks,
182 synopsis, docstring)
167 ''' 183 '''
168 assert callable(wrapper) 184 assert callable(wrapper)
169 aliases, entry = cmdutil.findcmd(command, table) 185 aliases, entry = cmdutil.findcmd(command, table)
170 for alias, e in table.iteritems(): 186 for alias, e in table.iteritems():
171 if e is entry: 187 if e is entry:
175 origfn = entry[0] 191 origfn = entry[0]
176 def wrap(*args, **kwargs): 192 def wrap(*args, **kwargs):
177 return util.checksignature(wrapper)( 193 return util.checksignature(wrapper)(
178 util.checksignature(origfn), *args, **kwargs) 194 util.checksignature(origfn), *args, **kwargs)
179 195
180 wrap.__doc__ = getattr(origfn, '__doc__')
181 wrap.__module__ = getattr(origfn, '__module__') 196 wrap.__module__ = getattr(origfn, '__module__')
197
198 doc = getattr(origfn, '__doc__')
199 if docstring is not None:
200 doc += docstring
201 wrap.__doc__ = doc
182 202
183 newentry = list(entry) 203 newentry = list(entry)
184 newentry[0] = wrap 204 newentry[0] = wrap
205 if synopsis is not None:
206 newentry[2] += synopsis
185 table[key] = tuple(newentry) 207 table[key] = tuple(newentry)
186 return entry 208 return entry
187 209
188 def wrapfunction(container, funcname, wrapper): 210 def wrapfunction(container, funcname, wrapper):
189 '''Wrap the function named funcname in container 211 '''Wrap the function named funcname in container