slashparse

README

slashparse

Go module for parsing slash commands

This is in the proof of concept stages of development, I'm not exactly sure how it will all turn out or if it has a lot of value.

Design Goals

1. Support many Go implementation of Slash commands,
2. Provide useful tooling to generate help docs and autocompletion in popular formats
3. Be opinionated about standardization and conventions in Slash commands.
4. Use text like YAML or JSON to define a command in an effort to make definitions multi-platform and easy to translate to other written languages.

How to use

Define your slash command in Yaml

---
name: Print
description: Echos back what you type.
arguments:
  - name: text
    argtype: quoted text
    description: text you want to print
    errorMsg: foo is not a valid value for text. Expected format is quoted text.
    position: 1
subcommands:
  - name: quote
    description: helps you stand on the shoulders of giants by using words from histories most articulate people
    subcommands:
      - name: random
        description: print a random quote from the a random author
      - name: author
        description: prints a quote from the specified author
        arguments:
          - name: authorName
            argtype: text
            description: Full Name of an author
            errorMsg: Please provide a valid author name, try someone famous "

Use slashParse to parse your arguments

package main

import com.gitlab.ericjaystevens.slashparse

const pathToYaml = "path/to/yaml"

ExecuteCommand(args string) (responce string, Error) {

  //define the slash command
  slashDef, _ := ioutil.ReadFile(pathToYaml)
  slashCommand, _ = slashparse.NewSlashCommand(slashDef)
	
  //parse it to get a command string and a map with all your arguments and their values
  //This should provie a helpfull error if a require argument is missing or the command is not valid
  command, values, err := p.slashCommand.Parse(args.Command)
	if err != nil {
		text := "bad command see help"
		return text, err
	}


	switch command {
	case "Print":
		return executePrint(values["text"])
	case "help":
		markdownHelp := p.slashCommand.GetSlashHelp()
		return markdownHelp, nil
  case "quote random":
    return executeQuoteRandom()
  case "quote author":
    return executeQuoteByAuthor(values["authorName"])
	default:
		text := "Unknown unknown"
	}

}

func print(input string) string{
	return input
}

What your users will see

argument parsing

> /print "Hello World!"

will provide the expected output

Hello World!

Alternatively if they could use the flags you set instead of position

Help

If your user can access generated help by running your slash command and help.

/print help

Slash parse give nice help output.

Print: "Prints the things you want"

/print "text"

  Text: -t,--tex
    text you want to display

Invalid commands

This examples requires quotes for the string so if a user runs

/print foo

They will receive the error message you defined.

Invalid Command. Please run /print help for more information

Documentation

Overview

Package slashparse is a parser for slash commands.

Index

• func GetPositionalArgs(argString string) []string
• type Argument
• type SlashCommand
  • func NewSlashCommand(slashDef []byte) (s SlashCommand, err error)
  • func (s *SlashCommand) Execute(slashString string) (string, error)
  • func (s *SlashCommand) GetSlashHelp() string
  • func (s *SlashCommand) Parse(slashString string) (string, map[string]string, error)
  • func (s *SlashCommand) SetHandler(commandString string, handler func(map[string]string) (string, error)) error
• type SubCommand

Functions

func GetPositionalArgs

func GetPositionalArgs(argString string) []string

GetPositionalArgs takes a string of arguments and splits it up by spaces and double quotes

Types

type Argument

type Argument struct {
	Name        string `yaml:"name" json:"name"`
	ArgType     string `yaml:"argtype" json:"argtype"`
	Description string `yaml:"description" json:"description"`
	ErrorMsg    string `yaml:"errorMsg" json:"errorMsg"`
	Position    int    `yaml:"position" json:"position"`
	Required    bool   `yaml:"required" json:"required"`
}

Argument defines and argument in a slash command

type SlashCommand

type SlashCommand struct {
	Name        string       `yaml:"name" json:"name,omitempty"`
	Description string       `yaml:"description" json:"description"`
	Arguments   []Argument   `yaml:"arguments" json:"arguments,omitempty"`
	SubCommands []SubCommand `yaml:"subcommands" json:"subcommands"`
}

SlashCommand defines the structure of a slash command string

func NewSlashCommand

func NewSlashCommand(slashDef []byte) (s SlashCommand, err error)

NewSlashCommand define a new slash command to parse

func (*SlashCommand) Execute

func (s *SlashCommand) Execute(slashString string) (string, error)

Execute parses and runs the configured handler to process your command.

func (*SlashCommand) GetSlashHelp

func (s *SlashCommand) GetSlashHelp() string

GetSlashHelp returns a markdown formated help for a slash command

func (*SlashCommand) Parse

func (s *SlashCommand) Parse(slashString string) (string, map[string]string, error)

Parse parse the command string

func (*SlashCommand) SetHandler

func (s *SlashCommand) SetHandler(commandString string, handler func(map[string]string) (string, error)) error

SetHandler sets the function that should be called based on the set of slash command and subcommands

type SubCommand

type SubCommand struct {
	Name        string       `yaml:"name" json:"name"`
	Description string       `yaml:"description" json:"description"`
	Arguments   []Argument   `yaml:"arguments" json:"arguments"`
	SubCommands []SubCommand `yaml:"subcommands" json:"subcommands"`
	// contains filtered or unexported fields
}

SubCommand defines a command that proceeded the slash command