Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Adopt botriot style description and help #249

Closed
atmos opened this Issue · 20 comments
@atmos

@jonrohan showed me this earlier today and I'd love for our scripts to support something like these.

exports.wiki = {
  description: 'Searches Wikipedia.org for the given input and returns a link to the most relevant article.',
  func: function (room, msg, options) {
    if (!msg) {
      return room.error(new UserError("You must provide some input. I can't read your mind."))
    }

    var uri = 'http://en.wikipedia.org/w/api.php?action=opensearch&search=' + encodeURIComponent(msg) + '&format=json'
    jsonHelper(room, uri, function(body) {
      if (body[1].length > 0) {
        var key = body[1][0]
        room.speak("http://en.wikipedia.org/wiki/"+encodeURIComponent(key))
      } else {
        room.speak("No wikipedia article found")
      }
    })
  }
}
  • First the description is tied to the trigger response, this will inevitably be a pain in the ass to upgrade to.
  • some commands are using commander, an optparse like library to make commands more unix like, kinda cool.

Any thoughts on doing something like this for hubot 3 @tombell ?

@atmos
@jonrohan
Admin

Here's an example with commander.js

exports.define = {
  description: 'Searches Wordnik for the top 3 definitions of the supplied word.',
  options: [
    ['-u, --urban', 'Search through urban dictionary']
  ],
  func: function(room, msg, options) {
    if (!msg) {
      room.speak("You must provide a word.")
      return
    }
    if(options.urban) {
      ...
    } else {
      ...
    }
  }
}

typing /define -h will return

Searches Wordnik for the top 3 definitions of the supplied word.

  Usage: define [options]

  Options:

    -h --help    output usage information
    -u, --urban  Search through urban dictionary
@iangreenleaf

What about a line to show example usage?

@technicalpickles

I really like this style. To avoid having to rewriting all of the hubot-scripts at once, it'd make a lot of sense to have backwards compatibility. Plus, shouldn't be that tricky to implement.

Maybe it could also have examples. I've found the regex used for those can be a little too aggressive (ie, any comments that have dashes in them). So, having that be in the response/hear/command would be nice:

robot.respond
  desc: 'Search Wikipedia.org for the given <input> and return a link to the most relevant article.'
  match: /wiki( me)? (.*)/i
  example: 'wiki me <input>' 
  func: (room, message, matches) ->
    # do some funky magic...
@tombell tombell closed this
@tombell tombell reopened this
@sirkitree

Does this make the help more useful looking as well?

For instance, currently when you type hubot help you get a separate message for every single line in a script, essentially flooding a channel.

I've seen other bots that instead list all available commands in one message and direct you to type something like bot help <command> for the longer description.

If what I'm talking about is unrelated, I'd be happy to open another issue about it.

@atmos

@sirkitree yeah if you're on IRC there's no way to easily send multiline things and it seems spammy/floody. This won't help with IRC but it'll help with discoverability.

@sirkitree

Thanks @atmos. If I wanted to work on something to change that where would I begin? In hubot itself or the scripts?

@skalnik
Admin

I really enjoy the description stuff in the Botriot or commander.js style. Right now asking Hubot for help is a big mish-mash of different styles, and I feel like having something like that would help it be a bit more consistent.

@Jellyfrog

I vote Botriot Style, should solve the problem @skalnik is talking about

@technicalpickles

I think having a style guide for descriptions would have the same effect on documentation. We've done passes through hubot-script at various points to help normalize and make them more consistent. Not saying -1, just that the documentation can be fixed in other ways.

I do like @tombell's last proposed botriot style. It's extremely readable, which is important when you are touching random scipts (like while maintaining hubot-scripts).

@drdamour

i like the look of that botriot style, lends itself very nicely to adding more things to a respond/condition so the bot could offer more core services (authentication, required config check, other types of pre or post processors, you could even have an error handler in there). Could see hubot growing from RegEx matches to something more complex w/ meme extraction & matching.

@atmos
@atmos
@jonrohan
Admin

@tombell not sure what you mean about outside a bin. (just getting caught up with this thread)

@jonrohan
Admin

I haven't thought about it in a while, but I just stripped api keys and stuff from the repo and open sourced it https://github.com/botriot/bot

@wadey

@tombell this is the key part for making it work with passed messages: https://github.com/botriot/bot/blob/master/common/commands/index.js#L61-L69

We also forked commander.js, but I don't remember what we had to change: https://github.com/botriot/commander.js

@wadey

This new module might be a good alternative, designed to be used outside of command line: https://github.com/substack/minimist

@technicalpickles

Been thinking about this a lot too. I'm not sure we necessarily need a different convention than responds. If we added additional meta data to respond (like I suggested awhile back), then commands could be a subset of responds, like respond is a subset.

robot.command 'wiki'
  desc: 'Search Wikipedia.org for the given <input> and return a link to the most relevant article.'
  match:  /( me)? (.*)/i
  examples: [
    "hubot wiki me a river"
  ]
  call: (msg) ->

That would be would call under the hood:

robot.respond /wiki ( me)? (.*)/i,
  desc: 'Search Wikipedia.org for the given <input> and return a link to the most relevant article.'
  examples: [
    "hubot wiki me a river"
  ]
  call: (msg) ->

Actually, having typed that, I'm not sure if the command syntax would buy you much more than support for metadata as part of a robot.respond, except to maybe get away from straight up regex more.

I'd also say, I'm not sure I'm a fan of the idea of argument flags like -a or --force or whatever. I think using a keyword approach is a lot more natural when calling from chat.

@atmos atmos closed this
@ileathan

@sirkitree to edit the help behavior you would edit the ./node_modules/hubot-help/ scripts. I personally just have the bot spit out a html page and then people can browse all the commands in their browser.

For example you can add something like robot.respond /help (\S+)/i, (msg) -> and spit out different messages depending on msg.match[1]

@technicalpickles I like this script pattern alot more than another one i looked at but i sure hope this doesnt add more complexity when i code I havnt done more than just look at it, but i notice its VERY READABLE unlike the other one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.