Path

Paths are the smallest and most essential node for conversations. They allow matching message text against multiple branches in a tightly scoped context.

A path is open when branches are added and closed when a branch is matched. While open, it can process incoming messages against the possible branches.

A matched branch can respond to the user and lay more branches to keep the path open, until finally a branch is matched without any new ones added.

Kind: global class

• Path
  • new Path(robot, [branches], [options], [key])
  • .addBranch(regex, [strings], [callback])
  • .getHandler(strings, callback) ⇒ function
  • .catchHandler() ⇒ function
  • .match(res) ⇒ Promise

---

new Path(robot, [branches], [options], [key])

Param	Type	Description
robot	Robot	Hubot Robot instance
[branches]	array	Array of args for each branch, each containing: - RegExp for listener - String to send and/or - Function to call on match
[options]	Object	Key/val options for config
[options.catchMessage]	Object	Message to send via catch handler
[options.catchCallback]	Object	Function to call within catch handler
[key]	string	Key name for this instance

Example (showing branch argument variations)

let choice = new Path(robot, [
  [ /door 1/, 'foo' ]
  [ /door 2/, 'bar', () => bar() ]
  [ /door 3/, () => baz() ]
])

Example (with message and callback options)

let choice = new Path(robot, {
  catchMessage: 'sorry, nothing matched'
  catchCallback: () => noMatch()
})

---

path.addBranch(regex, [strings], [callback])

Add an optional dialogue branch.

Each branch is assigned a handler to call on match, which can sends a message and/or fire a given callback.

Branch handlers are called by .match, if input matches a branch, which then returns the matched handler’s return value.

Kind: instance method of Path

Param	Type	Description
regex	RegExp	Matching pattern (accepts string, will cast as RegExp)
[strings]	string/array	Message text for response on match
[callback]	function	Function called when matched

Example (with regex, message and callback)

path.addBranch(/hello/i, 'hello there', helloCallback)

---

path.getHandler(strings, callback) ⇒ function

Ready a function to call on a match or catch, sending stirngs and/or doing a callback.

Handlers return a promise that resolves with a merged object containing the conext returned by send middleware if strings were sent, and the return value of the callback if there was one.

Either may return a promise so the result is wrapped to resolve both.

Kind: instance method of Path
Returns: function - The handler

Param	Type	Description
strings	string/array	Message text to send on match
callback	function	Function to call on match

---

path.catchHandler() ⇒ function

Get handler for when nothing matches, if configured.

If neither catchMessage or catchCallback is set, nothing happens.

Kind: instance method of Path
Returns: function - Handler (or undefined)

---

path.match(res) ⇒ Promise

Attempt to match an incoming response object. Overrides the response match (from the more general dialogue listener) even if null.

Matching closes the path and fires the handler which may add branches, re-opening it. Without a match, it will attempt to use a catch handler (which may be null). The matched branch or catch handler method may return a promise or not, the response is returned wrapped in a promise either way.

Kind: instance method of Path
Returns: Promise - Resolves with matched/catch branch handler result

Param	Type	Description
res	Response	Hubot Response object

Example

listener matching against possible branches
let choice = new Path(robot, [
  [ /door 1/, 'pies' ]
  [ /door 2/, 'lies' ]
])
robot.hear(/door/, (res) => choice.match(res))

---