slash-command
Version:
Simple slash command parsing module
123 lines (88 loc) • 4.32 kB
Markdown
# slash-command
[](https://travis-ci.org/krismuniz/slash-command) [](https://coveralls.io/github/krismuniz/slash-command?branch=master) [](http://opensource.org/licenses/MIT)
A simple ***slash command parsing module*** written in JavaScript. In other words, a function that parses a string and returns an object which separates the command keyword(s) from the body of the command.
##### Example:
```js
slashCommand('/mycommand This is the command body');
```
`slashCommand()` returns the following object:
```js
{
slashcommand: '/mycommand', // command(s) as stated
command: 'mycommand', // main command name (first in string)
subcommands: null, // array of subcommands; see below for more info.
body: 'This is the command body', // the body of the command
original: '/mycommand This is the command body' // the original string
}
```
## Features
This tiny module abstracts away the string-parsing process: string manipulation, matching regular expressions, mapping arrays, replacing strings, etc.
`slash-command` takes a string, parses it, and returns an object containing the slash command keywords, subcommands (see [below](#subcommands)), body, and the original string.
#### Use cases
`slash-command` is useful when building:
* chat clients that support slash commands
* CLI-like software
* messaging platform chatbots (e.g. for Slack or HipChat)
* platform-agnostic conversational interfaces and bots (e.g. email, SMS, IRC, etc.)
* Twitter bots, Tumblr bots, etc.
## Installation
Installing the ```slash-command``` module is as simple as installing any other [npm](https://npmjs.com) module:
```shell
$ npm install slash-command --save
```
## Usage
`slash-command` exports a single function, so it is quite to use:
```js
var slashCommand = require('slash-command');
/* OR, some ES6 module-loading love: */
import slashCommand from 'slash-command';
slashCommand('/tweet This is a tweet.');
```
`slashCommand()` returns the following object:
```js
{
slashcommand: '/tweet', // command(s) as stated
command: 'tweet', // main command (first in string)
subcommands: null, // array of all subcommands; null if there are none
body: 'This is a tweet.', // the body of the command
original: '/tweet This is a tweet.' // the original string
}
```
##### Subcommands
Let's suppose there are multiple consecutive slash commands in the string. We could use them!
I call these **subcommands**, and `slash-command` supports them very well. It returns all of them in a "`subcommands`" array inside the result object (in order of appearance; from left to right) so you can do whatever crazy thing you want with them.
```js
var slashCommand = require('slash-command');
/* or, for some ES6 module-loading love */
import slashCommand from 'slash-command';
slashCommand('/google/calendar Meeting with Sarah at 6pm.');
```
`slashCommand()` returns the following object:
```js
{
slashcommand: '/google/calendar', // command(s) as stated
command: 'google', // main command (first in string)
subcommands: ['calendar'], // array of all subcommands
body: 'Meeting with Sarah at 6pm.', // the body of the command
original: '/google/calendar Meeting with Sarah at 6pm.' // the original string
}
```
##### Required Parameters:
* `string` (`[string]`): The string argument; contains a slash command.
## Testing
Want to run the tests? Go ahead and type the following in your terminal/command prompt:
```shell
$ npm install
$ npm test
```
## Contributing
#### Bug Reports & Feature Requests
Something does not work as expected or perhaps you think this module needs a feature? Please [open an issue](https://github.com/krismuniz/slash-command/issues/new) using GitHub's [issue tracker](https://github.com/krismuniz/slash-command/issues).
#### Developing
Pull Requests (PRs) are welcome. Just make sure you follow the same basic style conventions as the original code.
## License
[The MIT License (MIT)](http://opensource.org/licenses/MIT)
---
<center>
<b>Copyright (c) 2015 Kristian Muñiz [https://krismuniz.com/]</b>
</center>