extension/lib/api.coffee

   1 ###
   2 # Copyright Simon Lydell 2015, 2016.
   3 #
   4 # This file is part of VimFx.
   5 #
   6 # VimFx is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 3 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # VimFx is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with VimFx.  If not, see <http://www.gnu.org/licenses/>.
  18 ###
  19
  20 # This file defines VimFx’s config file API.
  21
  22 defaults = require('./defaults')
  23 prefs = require('./prefs')
  24 utils = require('./utils')
  25 Vim = require('./vim')
  26
  27 counter = new utils.Counter({start: 10000, step: 100})
  28
  29 createConfigAPI = (vimfx, {allowDeprecated = true} = {}) -> {
  30   get: (inputPref) ->
  31     pref = alias(inputPref, allowDeprecated)
  32     if pref != inputPref
  33       try return prefs.get(inputPref)
  34     return switch
  35       when pref of defaults.parsed_options
  36         vimfx.options[pref]
  37       when pref of defaults.all_prefs or pref?.startsWith('custom.')
  38         prefs.get(pref)
  39       else
  40         throw new Error("VimFx: Unknown option: #{pref}")
  41
  42   getDefault: (inputPref) ->
  43     pref = alias(inputPref, allowDeprecated)
  44     if pref != inputPref
  45       try return prefs.default.get(inputPref)
  46     return switch
  47       when pref of defaults.parsed_options or pref?.startsWith('custom.')
  48         throw new Error("VimFx: No default for option: #{pref}")
  49       when pref of defaults.all_prefs
  50         defaults.all_prefs[pref]
  51       else
  52         throw new Error("VimFx: Unknown option: #{pref}")
  53
  54   set: (inputPref, value) ->
  55     pref = alias(inputPref, allowDeprecated)
  56     switch
  57       when pref of defaults.parsed_options
  58         previousValue = vimfx.options[pref]
  59         vimfx.options[pref] = value
  60         onShutdown(vimfx, -> vimfx.options[pref] = previousValue)
  61       when pref of defaults.all_prefs or pref?.startsWith('custom.')
  62         previousValue = if prefs.has(pref) then prefs.get(pref) else null
  63         prefs.set(pref, value)
  64         onShutdown(vimfx, -> prefs.set(pref, previousValue))
  65       else
  66         throw new Error("VimFx: Unknown option: #{pref}")
  67
  68   addCommand: ({name, description, mode, category, order} = {}, fn) ->
  69     mode ?= 'normal'
  70     category ?= if mode == 'normal' then 'misc' else ''
  71     order ?= counter.tick()
  72
  73     unless typeof name == 'string'
  74       throw new Error(
  75         "VimFx: A command name as a string is required. Got: #{name}"
  76       )
  77     unless /^[a-z_]+$/.test(name)
  78       throw new Error(
  79         "VimFx: Command names should only consist of a-z (lowercase) and
  80          underscores. Got: #{name}"
  81       )
  82     unless typeof description == 'string' and description != ''
  83       throw new Error(
  84         "VimFx: Commands must have a non-empty description. Got: #{description}"
  85       )
  86     unless utils.has(vimfx.modes, mode)
  87       modes = Object.keys(vimfx.modes).join(', ')
  88       throw new Error(
  89         "VimFx: Unknown mode. Available modes are: #{modes}. Got: #{mode}"
  90       )
  91     unless utils.has(vimfx.options.categories, category)
  92       categories = Object.keys(vimfx.options.categories).join(', ')
  93       throw new Error(
  94         "VimFx: Unknown category. Available categories are: #{categories}.
  95          Got: #{category}"
  96       )
  97     unless typeof order == 'number'
  98       throw new Error("VimFx: Command order must be a number. Got: #{order}")
  99     unless typeof fn == 'function'
 100       throw new Error("VimFx: Commands need a function to run. Got: #{fn}")
 101
 102     pref = "#{defaults.BRANCH}custom.mode.#{mode}.#{name}"
 103     prefs.root.default.set(pref, '')
 104     vimfx.modes[mode].commands[name] = {
 105       pref, category, order, run: fn, description
 106     }
 107     onShutdown(vimfx, -> delete vimfx.modes[mode].commands[name])
 108
 109   addOptionOverrides: (rules...) ->
 110     unless vimfx.optionOverrides
 111       vimfx.optionOverrides = []
 112       vimfx.options = new Proxy(vimfx.options, {
 113         get: (options, pref) ->
 114           location = utils.getCurrentLocation()
 115           return options[pref] unless location
 116           overrides = getOverrides(vimfx.optionOverrides, location)
 117           return overrides?[pref] ? options[pref]
 118       })
 119       onShutdown(vimfx, -> vimfx.optionOverrides = [])
 120     vimfx.optionOverrides.push(rules...)
 121
 122   addKeyOverrides: (rules...) ->
 123     unless vimfx.keyOverrides
 124       vimfx.keyOverrides = []
 125       vimfx.options.keyValidator = (keyStr, mode) ->
 126         location = utils.getCurrentLocation()
 127         return true unless location
 128         overrides = getOverrides(vimfx.keyOverrides, location, mode)
 129         return keyStr not in (overrides ? [])
 130       onShutdown(vimfx, -> vimfx.keyOverrides = [])
 131     vimfx.keyOverrides.push(rules...)
 132
 133   send: (vim, message, data = null, callback = null) ->
 134     unless vim instanceof Vim
 135       throw new Error(
 136         "VimFx: The first argument must be a vim object. Got: #{vim}"
 137       )
 138     unless typeof message == 'string'
 139       throw new Error(
 140         "VimFx: The second argument must be a message string. Got: #{message}"
 141       )
 142     if typeof data == 'function'
 143       throw new Error(
 144         "VimFx: The third argument must not be a function. Got: #{data}"
 145       )
 146
 147     unless typeof callback == 'function' or callback == null
 148       throw Error(
 149         "VimFx: If provided, `callback` must be a function. Got: #{callback}"
 150       )
 151     vim._send(message, data, callback, {prefix: 'config:'})
 152
 153   on: (event, listener) ->
 154     vimfx.on(event, listener)
 155     onShutdown(vimfx, -> vimfx.off(event, listener))
 156
 157   off: vimfx.off.bind(vimfx)
 158   modes: vimfx.modes
 159 }
 160
 161 # Don’t crash the users’s entire config file on startup if they happen to try to
 162 # set a renamed pref (only warn), but do throw an error if they reload the
 163 # config file; then they could update while editing the file anyway.
 164 alias = (pref, allowDeprecated) ->
 165   if pref of renamedPrefs
 166     newPref = renamedPrefs[pref]
 167     message = "VimFx: `#{pref}` has been renamed to `#{newPref}`."
 168     if allowDeprecated
 169       console.warn(message)
 170       return newPref
 171     else
 172       throw new Error(message)
 173   else
 174     return pref
 175
 176 renamedPrefs = {
 177   'hint_chars': 'hints.chars'
 178   'hints_sleep': 'hints.sleep'
 179   'hints_timeout': 'hints.matched_timeout'
 180   'hints_peek_through': 'hints.peek_through'
 181   'hints_toggle_in_tab': 'hints.toggle_in_tab'
 182   'hints_toggle_in_background': 'hints.toggle_in_background'
 183   'mode.hints.delete_hint_char': 'mode.hints.delete_char'
 184 }
 185
 186 getOverrides = (rules, args...) ->
 187   for [match, overrides] in rules
 188     return overrides if match(args...)
 189   return null
 190
 191 onShutdown = (vimfx, handler) ->
 192   fn = ->
 193     handler()
 194     vimfx.off('shutdown', fn)
 195   vimfx.on('shutdown', fn)
 196
 197 module.exports = createConfigAPI