extension/lib/public.coffee

   1 ###
   2 # Copyright Simon Lydell 2015.
   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 provides VimFx’s public API (defined in api.coffee) for public
  21 # consumption.
  22
  23 EXPORTED_SYMBOLS = ['getAPI']
  24
  25 # Once VimFx has been installed, this file will be available on the file system,
  26 # and the `api_url` pref will be available in Firefox’s prefs system. That’s all
  27 # that is needed to `Cu.import` this file, regardless of whether VimFx has
  28 # loaded or not. When VimFx _is_ loaded, `api` (which requires access to the
  29 # global `VimFx` instance) is set by main.coffee and passed to all consumers.
  30 api = null
  31
  32 # All requests for the API are stored here.
  33 callbacks = []
  34
  35 # Any time the API is set (when Firefox starts, when VimFx is updated or when
  36 # VimFx is disabled and then enabled), call all callbacks with the new API. This
  37 # takes care of API-consuming add-ons that happen to load before VimFx, as well
  38 # as the case where VimFx is updated in the middle of the session (see below).
  39 setAPI = (passed_api) ->
  40   api = passed_api
  41   callback(api) for callback in callbacks
  42   return
  43
  44 # All callbacks are always stored, in case they need to be re-run in the future.
  45 # If the API is already available, pass it back immediately.
  46 getAPI = (callback) ->
  47   callbacks.push(callback)
  48   callback(api) unless api == null
  49
  50 # main.coffee calls this function on shutdown instead of `Cu.unload(apiUrl)`.
  51 # This means that if VimFx is updated (or disabled and then enabled), all
  52 # `getAPI` calls for the old version are re-run with the new version. Otherwise
  53 # you’d have to either restart Firefox, or disable and enable every add-on using
  54 # the API in order for them to take effect.
  55 removeAPI = -> api = null