[tor-commits] [stem/master] Moving remaining /help information to config
atagar at torproject.org
atagar at torproject.org
Tue May 6 01:21:13 UTC 2014
commit 3fc675f911aba1d4581d1db3e7b60b2cb96428ac
Author: Damian Johnson <atagar at torproject.org>
Date: Sat Apr 19 15:55:00 2014 -0700
Moving remaining /help information to config
Moving the last of our /help output that remained in commands.py.
---
stem/interpretor/commands.py | 40 ++-------------
stem/interpretor/settings.cfg | 109 +++++++++++++++++++++++++++++++----------
2 files changed, 87 insertions(+), 62 deletions(-)
diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py
index 34d736d..833918f 100644
--- a/stem/interpretor/commands.py
+++ b/stem/interpretor/commands.py
@@ -15,33 +15,6 @@ OUTPUT_FORMAT = (Color.BLUE, )
BOLD_OUTPUT_FORMAT = (Color.BLUE, Attr.BOLD)
ERROR_FORMAT = (Attr.BOLD, Color.RED)
-HELP_OPTIONS = {
- 'HELP': ("/help [OPTION]", 'help.help'),
- 'EVENTS': ("/events [types]", 'help.events'),
- 'INFO': ("/info [relay fingerprint, nickname, or IP address]", 'help.info'),
- 'QUIT': ("/quit", 'help.quit'),
- 'GETINFO': ("GETINFO OPTION", 'help.getinfo'),
- 'GETCONF': ("GETCONF OPTION", 'help.getconf'),
- 'SETCONF': ("SETCONF PARAM[=VALUE]", 'help.setconf'),
- 'RESETCONF': ("RESETCONF PARAM[=VALUE]", 'help.resetconf'),
- 'SIGNAL': ("SIGNAL SIG", 'help.signal'),
- 'SETEVENTS': ("SETEVENTS [EXTENDED] [EVENTS]", 'help.setevents'),
- 'USEFEATURE': ("USEFEATURE OPTION", 'help.usefeature'),
- 'SAVECONF': ("SAVECONF", 'help.saveconf'),
- 'LOADCONF': ("LOADCONF...", 'help.loadconf'),
- 'MAPADDRESS': ("MAPADDRESS SOURCE_ADDR=DESTINATION_ADDR", 'help.mapaddress'),
- 'POSTDESCRIPTOR': ("POSTDESCRIPTOR [purpose=general/controller/bridge] [cache=yes/no]...", 'help.postdescriptor'),
- 'EXTENDCIRCUIT': ("EXTENDCIRCUIT CircuitID [PATH] [purpose=general/controller]", 'help.extendcircuit'),
- 'SETCIRCUITPURPOSE': ("SETCIRCUITPURPOSE CircuitID purpose=general/controller", 'help.setcircuitpurpose'),
- 'CLOSECIRCUIT': ("CLOSECIRCUIT CircuitID [IfUnused]", 'help.closecircuit'),
- 'ATTACHSTREAM': ("ATTACHSTREAM StreamID CircuitID [HOP=HopNum]", 'help.attachstream'),
- 'REDIRECTSTREAM': ("REDIRECTSTREAM StreamID Address [Port]", 'help.redirectstream'),
- 'CLOSESTREAM': ("CLOSESTREAM StreamID Reason [Flag]", 'help.closestream'),
- 'RESOLVE': ("RESOLVE [mode=reverse] address", 'help.resolve'),
- 'TAKEOWNERSHIP': ("TAKEOWNERSHIP", 'help.takeownership'),
- 'PROTOCOLINFO': ("PROTOCOLINFO [ProtocolVersion]", 'help.protocolinfo'),
-}
-
@uses_settings
def _get_commands(config, controller):
@@ -107,12 +80,6 @@ def _get_commands(config, controller):
else:
commands.append('SIGNAL ')
- # adds interpretor commands
-
- for cmd in HELP_OPTIONS:
- if HELP_OPTIONS[cmd][0].startswith('/'):
- commands.append('/' + cmd.lower())
-
# adds help options for the previous commands
base_cmd = set([cmd.split(' ')[0].replace('+', '').replace('/', '') for cmd in commands])
@@ -167,6 +134,7 @@ class ControlInterpretor(object):
"""
arg = arg.upper()
+ usage_info = config.get('help.usage', {})
# If there's multiple arguments then just take the first. This is
# particularly likely if they're trying to query a full command (for
@@ -192,12 +160,12 @@ class ControlInterpretor(object):
output += format(line[cmd_start:] + '\n', *OUTPUT_FORMAT)
else:
output += format(line + '\n', *BOLD_OUTPUT_FORMAT)
- elif arg in HELP_OPTIONS:
+ elif arg in usage_info:
# Provides information for the tor or interpretor argument. This bolds
# the usage information and indents the description after it.
- usage, attr = HELP_OPTIONS[arg]
- description = msg(attr)
+ usage = usage_info[arg]
+ description = config.get('help.description.%s' % arg.lower(), '')
output = format(usage + '\n', *BOLD_OUTPUT_FORMAT)
diff --git a/stem/interpretor/settings.cfg b/stem/interpretor/settings.cfg
index 553cdae..feec575 100644
--- a/stem/interpretor/settings.cfg
+++ b/stem/interpretor/settings.cfg
@@ -4,6 +4,10 @@
#
################################################################################
+ ##################
+# GENERAL MESSAGES #
+ ##################
+
msg.multiline_unimplemented_notice Multi-line control options like this are not yet implemented.
msg.help
@@ -19,11 +23,11 @@ msg.help
|prompt -i 1643 attach to control port 1643
|prompt -s ~/.tor/socket attach to a control socket in your home directory
-help.quit Terminates the interpretor.
-help.saveconf Writes Tor's current configuration to its torrc.
-help.postdescriptor Simulates getting a new relay descriptor.
-help.setcircuitpurpose Sets the purpose attribute for a circuit.
-help.takeownership Instructs Tor to gracefully shut down when this control connection is closed.
+ #################
+# OUTPUT OF /HELP #
+ #################
+
+# Response for the '/help' command without any arguments.
help.general
|Interpretor commands include:
@@ -56,7 +60,36 @@ help.general
|
|For more information use '/help [OPTION]'.
-help.help
+# Usage of tor and interpretor commands.
+
+help.usage HELP => /help [OPTION]
+help.usage EVENTS => /events [types]
+help.usage INFO => /info [relay fingerprint, nickname, or IP address]
+help.usage QUIT => /quit
+help.usage GETINFO => GETINFO OPTION
+help.usage GETCONF => GETCONF OPTION
+help.usage SETCONF => SETCONF PARAM[=VALUE]
+help.usage RESETCONF => RESETCONF PARAM[=VALUE]
+help.usage SIGNAL => SIGNAL SIG
+help.usage SETEVENTS => SETEVENTS [EXTENDED] [EVENTS]
+help.usage USEFEATURE => USEFEATURE OPTION
+help.usage SAVECONF => SAVECONF
+help.usage LOADCONF => LOADCONF...
+help.usage MAPADDRESS => MAPADDRESS SOURCE_ADDR=DESTINATION_ADDR
+help.usage POSTDESCRIPTOR => POSTDESCRIPTOR [purpose=general/controller/bridge] [cache=yes/no]...
+help.usage EXTENDCIRCUIT => EXTENDCIRCUIT CircuitID [PATH] [purpose=general/controller]
+help.usage SETCIRCUITPURPOSE => SETCIRCUITPURPOSE CircuitID purpose=general/controller
+help.usage CLOSECIRCUIT => CLOSECIRCUIT CircuitID [IfUnused]
+help.usage ATTACHSTREAM => ATTACHSTREAM StreamID CircuitID [HOP=HopNum]
+help.usage REDIRECTSTREAM => REDIRECTSTREAM StreamID Address [Port]
+help.usage CLOSESTREAM => CLOSESTREAM StreamID Reason [Flag]
+help.usage RESOLVE => RESOLVE [mode=reverse] address
+help.usage TAKEOWNERSHIP => TAKEOWNERSHIP
+help.usage PROTOCOLINFO => PROTOCOLINFO [ProtocolVersion]
+
+# Longer description of what tor and interpretor commands do.
+
+help.description.help
|Provides usage information for the given interpretor, tor command, or tor
|configuration option.
|
@@ -64,24 +97,27 @@ help.help
| /help info # provides a description of the '/info' option
| /help GETINFO # usage information for tor's GETINFO controller option
-help.events
+help.description.events
|Provides events that we've received belonging to the given event types. If
|no types are specified then this provides all the messages that we've
|received.
-help.info
+help.description.info
|Provides general information for a relay that's currently in the consensus.
|If no relay is specified then this provides information on ourselves.
-help.getinfo
+help.description.quit
+|Terminates the interpretor.
+
+help.description.getinfo
|Queries the tor process for information. Options are...
|
-help.getconf
+help.description.getconf
|Provides the current value for a given configuration value. Options include...
|
-help.setconf
+help.description.setconf
|Sets the given configuration parameters. Values can be quoted or non-quoted
|strings, and reverts the option to 0 or NULL if not provided.
|
@@ -92,7 +128,7 @@ help.setconf
| * Sets an exit policy that only includes port 80/443
| SETCONF ExitPolicy=\"accept *:80, accept *:443, reject *:*\"\
-help.resetconf
+help.description.resetconf
|Reverts the given configuration options to their default values. If a value
|is provided then this behaves in the same way as SETCONF.
|
@@ -103,11 +139,11 @@ help.resetconf
| * Uses the default exit policy and sets our nickname to be 'Goomba'
| RESETCONF ExitPolicy Nickname=Goomba
-help.signal
+help.description.signal
|Issues a signal that tells the tor process to reload its torrc, dump its
|stats, halt, etc.
-help.setevents
+help.description.setevents
|Sets the events that we will receive. This turns off any events that aren't
|listed so sending 'SETEVENTS' without any values will turn off all event reporting.
|
@@ -118,11 +154,14 @@ help.setevents
|Events include...
|
-help.usefeature
+help.description.usefeature
|Customizes the behavior of the control port. Options include...
|
-help.loadconf
+help.description.saveconf
+|Writes Tor's current configuration to its torrc.
+
+help.description.loadconf
|Reads the given text like it belonged to our torrc.
|
|Example:
@@ -133,40 +172,49 @@ help.loadconf
| ExitPolicy reject *:*
| .
-help.mapaddress
+help.description.mapaddress
|Replaces future requests for one address with another.
|
|Example:
| MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
-help.extendcircuit
+help.description.postdescriptor
+|Simulates getting a new relay descriptor.
+
+help.description.extendcircuit
|Extends the given circuit or create a new one if the CircuitID is zero. The
|PATH is a comma separated list of fingerprints. If it isn't set then this
|uses Tor's normal path selection.
-help.closecircuit
+help.description.setcircuitpurpose
+|Sets the purpose attribute for a circuit.
+
+help.description.closecircuit
|Closes the given circuit. If "IfUnused" is included then this only closes
|the circuit if it isn't currently being used.
-help.attachstream
+help.description.attachstream
|Attaches a stream with the given built circuit (tor picks one on its own if
|CircuitID is zero). If HopNum is given then this hop is used to exit the
|circuit, otherwise the last relay is used.
-help.redirectstream
+help.description.redirectstream
|Sets the destination for a given stream. This can only be done after a
|stream is created but before it's attached to a circuit.
-help.closestream
+help.description.closestream
|Closes the given stream, the reason being an integer matching a reason as
|per section 6.3 of the tor-spec.
-help.resolve
+help.description.resolve
|Performs IPv4 DNS resolution over tor, doing a reverse lookup instead if
|"mode=reverse" is included. This request is processed in the background and
|results in a ADDRMAP event with the response.
-help.protocolinfo
+help.description.takeownership
+|Instructs Tor to gracefully shut down when this control connection is closed.
+
+help.description.protocolinfo
|Provides bootstrapping information that a controller might need when first
|starting, like Tor's version and controller authentication. This can be done
|before authenticating to the control port.
@@ -179,9 +227,18 @@ help.signal.options HALT / TERM => immediately shut down
help.signal.options CLEARDNSCACHE => clears any cached DNS results
help.signal.options NEWNYM => clears the DNS cache and uses new circuits for future connections
-# Autocompletion commands. We dynamically load more, such as GETINFO and
-# GETCONF options tor will recognize so this just includes other base commands.
+ ################
+# TAB COMPLETION #
+ ################
+
+# Commands we'll autocomplete when the user hits tab. This is just the start of
+# our autocompletion list - more are determined dynamically by checking what
+# tor supports.
+autocomplete /help
+autocomplete /events
+autocomplete /info
+autocomplete /quit
autocomplete SAVECONF
autocomplete MAPADDRESS
autocomplete EXTENDCIRCUIT
More information about the tor-commits
mailing list