commit 3fc675f911aba1d4581d1db3e7b60b2cb96428ac Author: Damian Johnson atagar@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