git.cworth.org Git - turbot/blob - turbot/help.py

   1 overview = """
   2 *Turbot help*
   3 Here is an overview of commands that Turbot makes available. You can
   4 actually get at all functionality by just typing `/hunt` and then
   5 clicking buttons that are provided in the result. But many operations
   6 will be much more efficient by using a special-purpose command, (such
   7 as `/solved SOLUTION`).
   8
   9 Type `/help <command-name>` for more details on any command below.
  10
  11 *Hunt creation and editing*
  12     `/new hunt`: Create a new hunt (from any channel)
  13     `/edit`: Edit the current hunt (from a hunt channel)
  14     `/edit hunt`: Edit the current hunt (from a puzzle channel)
  15
  16 *Puzzle creation and editing* (in a puzzle channel unless specified)
  17     `/new`: Create a new puzzle (in a hunt or puzzle channel)
  18     `/edit`: Edit the current puzzle (from a puzzle channel)
  19     `/state <update>`: Capture the current state
  20     `/solved <solution>`: Mark current puzzle solved
  21     `/tag [+ADD_TAG|-REMOVE_TAG]`: Tag/untag current puzzle
  22
  23 *Hunt overview and searching for puzzles*
  24     `/hunt <search_terms>`: Search for puzzles (in a hunt/puzzle channel)
  25     `/round <search_terms>`: Show puzzles in current round (puzzle channel)
  26     `/puzzle`: Display state of current puzzle (puzzle channel)
  27
  28 *Solving support* (from any channel)
  29     `/help me`: Get a suggestion of something to try
  30     `/rot [*|COUNT] <text_to_rotate>`: Perform a Caesar shift on text
  31 """
  32
  33 commands = {
  34     "edit": {
  35         "summary": "Edit the puzzle or hunt for the current channel",
  36         "usage": "`/edit`, `/edit hunt`, `/edit puzzle`",
  37         "details": ("This command will bring up a dialog window where you " +
  38                     "can edit the current hunt or puzzle. With `/edit` " +
  39                     "alone it will edit whatever is associated with the " +
  40                     "current channel (hunt or puzzle). With `/edit hunt` " +
  41                     "you can edit the hunt from a puzzle channel.")
  42     },
  43     "hunt": {
  44         "summary": "Search for and display puzzles in the current hunt",
  45         "usage": "`/hunt [unsolved|solved|all] [meta|plain] <search_terms>`",
  46         "details": ("With `/hunt` alone, this command will display all " +
  47                     "unsolved puzzles in the current hunt. All output from " +
  48                     "`/hunt` is entirely private to you, so you do not need " +
  49                     "to worry about cluttering up the channel's chat " +
  50                     "traffic with this command." +
  51                     "\n\n" +
  52                     "The output for each puzzle will include all of the " +
  53                     "information displayed by the `/puzzle` command so see " +
  54                     "`/help puzzle` for details." +
  55                     "\n\n"
  56                     "An initial argument can be used to instead display " +
  57                     "only `solved` puzzles or `all` puzzles (both unsolved " +
  58                     "and solved). Additional arguments are search terms. " +
  59                     "Only puzzles that match all provided terms will be " +
  60                     " displayed. The terms can match the puzzle title, " +
  61                     " round title, puzzle URL, puzzle type (`meta` or " +
  62                     "`plain`), tags, or a puzzle's solution." +
  63                     "\n\n" +
  64                     "Use quotation marks in search terms to search for a " +
  65                     "phrase such as `/hunt \"good times\"`." +
  66                     "\n\n" +
  67                     "Search terms can include regular expression syntax." +
  68                     "\n\n" +
  69                     "This command also supports `/hunt new` and " +
  70                     "`/hunt edit` which are identical to `/new hunt` " +
  71                     "and `/edit hunt` so see `/help new` or `/help edit`" +
  72                     "for details.")
  73     },
  74     "new": {
  75         "summary": "Create a new puzzle (or a new hunt)",
  76         "usage": "`/new`, `/new puzzle`, `/new hunt`",
  77         "details": ("With `/new` alone, this command will bring up a " +
  78                     "dialog window where you will be prompted for " +
  79                     "information to create a new puzzle. The only field " +
  80                     "required for a new puzzle is the puzzle's name " +
  81                     "but any additional information you have will be " +
  82                     "useful to add (such as an external URL for the puzzle.)" +
  83                     "\n\n" +
  84                     "A puzzle can be marked as a meta-puzzle and can be " +
  85                     "assigned to one or more rounds. If the round(s) for " +
  86                     "this puzzle already exist, simply click on them in " +
  87                     "the \"Round(s)\" field. If this is the first puzzle " +
  88                     "for a new round, then type the name of the round in " +
  89                     "the \"New round(s)\" field." +
  90                     "\n\n" +
  91                     "For the new puzzle, Turbot will create a Slack channel " +
  92                     "and a shared spreadsheet for the puzzle. It will also " +
  93                     "announce the new puzzle in the hunt's channel, where " +
  94                     "members of the hunt can click to join the puzzle's " +
  95                     "channel and then click through to the puzzle's sheet." +
  96                     "\n\n" +
  97                     "This command can also be issued as `/new hunt` from " +
  98                     "any channel to create an entirely new hunt.")
  99     },
 100     "puzzle": {
 101         "summary": "Display the status of the current puzzle",
 102         "usage": "`/puzzle`, `/puzzle new`, `/puzzle edit",
 103         "details": ("When you issue `/puzzle` alone in a puzzle channel, " +
 104                     "Turbot will reply (privately to you) with all the " +
 105                     "information it has about the current puzzle. For all " +
 106                     "puzzles this includes the solved status (either an " +
 107                     "unchecked or checked checkbox), the puzzle title, " +
 108                     "links to the puzzle's external web page and sheet, " +
 109                     "the rounds of the puzzle, and tags, and the puzzle's " +
 110                     "state string." +
 111                     "\n\n" +
 112                     "If this is a meta-puzzle the output will also include " +
 113                     "the names (and solutions where known) of all other " +
 114                     "puzzles in the same round as the current puzzle." +
 115                     "\n\n" +
 116                     "This command also support `/puzzle new` and " +
 117                     "`/puzzle edit` which are identical to `/new puzzle` " +
 118                     "and `/edit puzzle` so see `/help new` and `/help edit` " +
 119                     "for details.")
 120     },
 121     "round": {
 122         "summary": "Display puzzles in the same round as the current puzzle",
 123         "usage": "`/round [unsolved|solved|all] [meta|plain] <search_terms>`",
 124         "details": ("The `/round` command can be issued from any puzzle " +
 125                     "channel and will display (by default) all puzzles " +
 126                     "belonging to the same round(s) as the current puzzle." +
 127                     "\n\n"
 128                     "To filter to only solved or unsolved puzzles, issue " +
 129                     "`/round solved` or `/round unsolved` instead." +
 130                     "\n\n" +
 131                     "This command also supports all of the same options as " +
 132                     "the `/hunt` command for searching/filtering which " +
 133                     "puzzles to display. So see `/help hunt` for details.")
 134     },
 135     "rot": {
 136         "summary": "Perform a Caesar shift rotation on some text",
 137         "usage": "`/rot TEXT`, `/rot * TEXT`, `/rot COUNT TEXT`",
 138         "details": ("This command performs a Caesar shift rotation on the " +
 139                     "text you provide to the command. An initial numeric " +
 140                     "argument indicates how many places through the " +
 141                     "alphabet each character should be rotated." +
 142                     "\n\n" +
 143                     "If the numeric argument is omitted, or is the " +
 144                     "character `*` this command will emit every possible " +
 145                     "rotation of the provided text." +
 146                     "\n\n"
 147                     "Note: Unlike commands such as `/hunt` or `/puzzle` the " +
 148                     "output from `/rot` will be presented to the current " +
 149                     "channel rather than privately to you. The idea behind " +
 150                     "this is that others working on the same puzzle might " +
 151                     "benefit from this output as well." +
 152                     "\n\n" +
 153                     "If you would like to execute this command privately, " +
 154                     "may issue it in a direct-message conversation with " +
 155                     "Turbot.")
 156     },
 157     "state": {
 158         "summary": "Updates the state of this puzzle",
 159         "usage": "`/state <WHERE THINGS STAND>`",
 160         "details": ("This command allows you to capture a high-level " +
 161                     "description of the state of a puzzle. This is " +
 162                     "particularly useful when you are switching away from " +
 163                     "a puzzle to let the next solvers know the state of " +
 164                     "things." +
 165                     "\n\n" +
 166                     "Turbot will present the state string in every view it " +
 167                     "generates for the puzzle." +
 168                     "\n\n" +
 169                     "An example state string might be something like: " +
 170                     "`/state Grid is filled, but we need help on extraction`" +
 171                     " or similar.")
 172     },
 173     "solved": {
 174         "summary": "Record the solution of a puzzle",
 175         "usage": "`/solved SOLUTION HERE`",
 176         "details": ("Once you've submitted a solution to the hunt's website " +
 177                     "and it has been confirmed, issue the `/solved` command " +
 178                     "so that Turbot knows the puzzle is solved. Turbot will " +
 179                     "report to the hunt's channel that the puzzle has been " +
 180                     "solved.")
 181     },
 182     "tag": {
 183         "summary": "Add or remove a tag to a puzzle",
 184         "usage": "`/tag NEW_TAG`",
 185         "details": ("This command allows you to add brief descriptive tags " +
 186                     "to a puzzle. This might include puzzle types, specific " +
 187                     "domain knowledge, or metadata from the puzzle’s " +
 188                     "presentation which might be used elsewhere." +
 189                     "\n\n" +
 190                     "Tags can only consist of letters, numbers, and the " +
 191                     "underscore character `_`." +
 192                     "\n\n" +
 193                     "You can also add a tag by typing `/tag +TAG_TO_ADD` " +
 194                     "and remove a tag with `/tag -TAG_TO_REMOVE`.")
 195     }
 196 }
 197
 198 def turbot_help(args):
 199     """The top-level implementation of the Turbot help system
 200
 201     With empty args, gives a summary of available commands.
 202
 203     With any command name, gives detailed help on that command.
 204     """
 205
 206     if not args:
 207         return overview
 208
 209     # We only look at the first word here
 210     command = args.split(" ", 1)[0]
 211
 212     # Ignore any slash prefix the user may have given
 213     if command[0] == '/':
 214         command = command[1:]
 215
 216     if command not in commands:
 217         valid = list(commands.keys())
 218         valid.sort()
 219         return "Unknown command: {}. Valid commands are: {}".format(
 220             command, ", ".join(valid))
 221
 222     dict = commands[command]
 223     return ("*Help on `/{}`*".format(command) +
 224             "\n`/{}`: {}".format(command, dict["summary"]) +
 225             "\nUsage: {}".format(dict["usage"]) +
 226             "\n\n{}".format(dict["details"]))