Initial mapping.json spec

This is an initial cursory specification for the mapping.json format and a mapping.json interpreter. Final specifications will be done after implementation.

A mapping.json file maps a series of commands to shortcuts.

1. A typical mapping file, for example a mapping for for git commands, could be named git.mappings.json, however, any number of mappings for different commands can be put in the same mapping.json. If you'd like to separate them out into their own files then make sure that the last part of the file name is mapping.json.
2. Mapping files can map a simple command to one shortcut and it's various options or switches shortcuts. Or it can map a command to its sub-commands and their various switches and options shortcuts.
3. Single switches or options don't need a mapping. They will automatically be added to the created command as a single switch or option.
4. For more complex commands like, git push [remote] [branch], one can use formulas to specify necessary arguments and the order in which they should be passed.
5. Use enumerables for commands that take a number n at some point.

####Two different formats####

Single command to its options and switches.

{
  "ls": {
    "shortcut": "l",
    "default": "-ls",
    "options": {
      "t": "-lkh"
    }
  }
}

This maps ls command to a t option that maps to the options -lkh. Inputting ls -t would output ls -lkh. This is a simple example.

One can have unlimited nested sub-commands. This is useful for more complex commands like git.

{
  "git": {
    "shortcut": "g",
    "default": "help",
    "mappings": {
      "commit": {
        "shortcut": "c",
        "default": "-a",
        "options": {
          "m": "-am"
        }
      },
      "diff": {
        "shortcut": "d",
        "always": "--color",
        "options": {
          "h": "--histogram"
        }
      }
    }
  }
}

Here inputting g would output git help. Inputting g c -m would output git commit -am.

####Formulas####

Formulas are a way of specifying how the produced command should look i.e. the order in which the shortcuts passed in should map to a place in the produced command.

{
  "git": {
    "shortcut": "g",
    "default": "help",
    "mappings": {
      "push": {
        "shortcut": "p",
        "formula": "%1 %2 %o",
        "default": {
          "1": "origin",
          "2": "master",
          "o": "--tag"
        },
        "options": {
          "t": "--tag",
          "d": "--delete"
        }
      }
    }
  }
}

Inputting g p -td origin master would map to git origin master --tag --delete. Formulas can be any valid JSON string, the special values %s, %o, and %1...%n, are available to you. Where:

• %s is the shortcuts command value. In the previous example this would be push
• %o is the options that have been passed.
• %1...%n is the series of arguments passed that are not proceeded by a -.

If a formula and a default mapping is specified the default value must specify all the arguments that the formula is looking for.

####Commands that take a number####

For commands that take a number such as any git command that utilizes the HEAD~n syntax you can simply add a formula to the mapping that will take the first number passed to it in the - switch syntax. You can also pass in a number for specific command line switches. The number must occur directly after the letter mapping to the command line switch. If a number occurs after a command line switch which does not map to an option with a number formula then it is understood to be intended for the mappings formula.

{
  "git": {
    "shortcut": "g",
    "default": "help",
    "mappings": {
      "reset": {
        "shortcut": "r",
        "default": "--hard HEAD",
        "formula": "%o HEAD~%n",
        "options": {
          "h": "--hard",
          "s": "--soft"
        }
      },
      "diff": {
        "shortcut": "d",
        "always": "--color",
        "options": {
          "u": "unified=%n"
        }
      }
    }
  }
}

For example inputting g r -h2 would output git reset --hard HEAD~2.

Inputting g d -u8 would output git diff --color --unified=8.