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         return true unless mode == 'normal'
 127         location = utils.getCurrentLocation()
 128         return true unless location
 129         overrides = getOverrides(vimfx.keyOverrides, location)
 130         return keyStr not in (overrides ? [])
 131       onShutdown(vimfx, -> vimfx.keyOverrides = [])
 132     vimfx.keyOverrides.push(rules...)
 133
 134   send: (vim, message, data = null, callback = null) ->
 135     unless vim instanceof Vim
 136       throw new Error(
 137         "VimFx: The first argument must be a vim object. Got: #{vim}"
 138       )
 139     unless typeof message == 'string'
 140       throw new Error(
 141         "VimFx: The second argument must be a message string. Got: #{message}"
 142       )
 143     if typeof data == 'function'
 144       throw new Error(
 145         "VimFx: The third argument must not be a function. Got: #{data}"
 146       )
 147
 148     unless typeof callback == 'function' or callback == null
 149       throw Error(
 150         "VimFx: If provided, `callback` must be a function. Got: #{callback}"
 151       )
 152     vim._send(message, data, callback, {prefix: 'config:'})
 153
 154   on: (event, listener) ->
 155     vimfx.on(event, listener)
 156     onShutdown(vimfx, -> vimfx.off(event, listener))
 157
 158   off: vimfx.off.bind(vimfx)
 159   modes: vimfx.modes
 160 }
 161
 162 # Don’t crash the users’s entire config file on startup if they happen to try to
 163 # set a renamed pref (only warn), but do throw an error if they reload the
 164 # config file; then they could update while editing the file anyway.
 165 alias = (pref, allowDeprecated) ->
 166   if pref of renamedPrefs
 167     newPref = renamedPrefs[pref]
 168     message = "VimFx: `#{pref}` has been renamed to `#{newPref}`."
 169     if allowDeprecated
 170       console.warn(message)
 171       return newPref
 172     else
 173       throw new Error(message)
 174   else
 175     return pref
 176
 177 renamedPrefs = {
 178   'hint_chars': 'hints.chars'
 179   'hints_sleep': 'hints.sleep'
 180   'hints_timeout': 'hints.matched_timeout'
 181   'hints_peek_through': 'hints.peek_through'
 182   'hints_toggle_in_tab': 'hints.toggle_in_tab'
 183   'hints_toggle_in_background': 'hints.toggle_in_background'
 184   'mode.hints.delete_hint_char': 'mode.hints.delete_char'
 185 }
 186
 187 getOverrides = (rules, args...) ->
 188   for [match, overrides] in rules
 189     return overrides if match(args...)
 190   return null
 191
 192 onShutdown = (vimfx, handler) ->
 193   fn = ->
 194     handler()
 195     vimfx.off('shutdown', fn)
 196   vimfx.on('shutdown', fn)
 197
 198 module.exports = createConfigAPI