Packages

Packages you should know about

• clipboard
• auto-spacing
• alphabet

Registering a package

The following returns a Package instance:

var myPackage = Packages.register({
  name: 'my-package',
  description: 'does awesome stuff',
  platforms: ['darwin', 'unix', 'windows'],

  // optional
  scope: 'my-custom-scope',

  // optional
  // list of bundle ids(darwin) commands should be scoped under
  applications: ['bundle.id'],
  // or a single application
  application: 'bundle.id',
  // and/or condition(s)
  conditions: function(input, context) {return true}
  condition: function(input, context) {return true}
})

Unless scope is specified name, applications¹ and condition are being used to auto generate a scope for given package. This scope will be applied to all commands defined/implemented the package unless explicitly specified otherwise.

name is the machine name for this package. All commands defined will be prefixed by it like my-package:first-command

Defining commands

A package can define one or many commands. Each command must have a spoken parameter, which is the vocal trigger. The package does not necessarily need to implement, i.e provide action for a given command. Implementations could reside elsewhere.

// single
myPackage.command('single-command', {
  spoken: 'single spoken trigger',
  action: function() {
    this.string('this command has an action!')
  }
})

// multiple
myPackage.commands({
  'first-command': {spoken: 'first spoken trigger'},
  'second-command': {spoken: 'second spoken trigger'}
})

// multiple with default properties
myPackage.commands(
  {
    description: '',
    tags: ['my', 'recommended']
  },
  {
    'third-command': {spoken: 'third spoken trigger'},
    'fourth-command': {spoken: 'fourth spoken trigger'},
  }
)

Implementing commands

Attaching action to previously defined command:

myPackage.implement({
  'my-package:first-command': function(){},
  'my-package:second-command': function(){}
})

Custom scopes

See Scopes for definition of my-custom-scope

myPackage.implement(
  {
    scope: 'my-custom-scope'
  },
  {
    'my-package:third-command': function(){},
    'my-package:fourth-command': function(){}
  }
)

Miscellaneous

Packages::await

If you need to wait for another package to initialize before running some code:

Packages.await('someOtherPackage', (pack) => {
  console.log(pack.name) // => someOtherPackage
})

Package::defer

Useful if your package code needs to wait until all other packages and user settings have been evaluated. A common case would be if the package creates commands based on a list of settings, and those settings might be modified by user code.

pack.defer(() => {
  if (pack.settings().bracketMatcher) {
    pack.implement({
      'symbols:surround-parentheses': (input, context) => {
        this.key("(")
      }
    })
  }
})

Packages codebase

http://updates.voicecode.io/packages/

Workflow for contributing to packages

• go to http://updates.voicecode.io/packages/
• fork the package repo
• quit VoiceCode
• cd ~/voicecode/packages
• rm -rf [package name]
• git clone [forked package url]
• start VoiceCode
• make changes (will update live in VoiceCode)
• commit with informative messages
• git push
• when ready, pull-request

¹. can be a function (lazy loading). Must return an Array ↩