Prefs.js

/**
 * Wrapper around brackets pref system to ensure preferences are stored in in one single object instead of using multiple keys.
 * This is to make it easy for the user who edits their preferences file to easily manage the potentially numerous lines of preferences generated by the persisting code-folding state.
 * @author Patrick Oladimeji
 * @date 3/22/14 20:39:53 PM
 */
/*jslint vars: true, plusplus: true, devel: true, nomen: true, indent: 4, maxerr: 50 */
/*global define, brackets*/
define(function (require, exports, module) {
    "use strict";
    var PreferencesManager      = brackets.getModule("preferences/PreferencesManager"),
        ProjectManager          = brackets.getModule("project/ProjectManager"),
        prefs                   = PreferencesManager.getExtensionPrefs("brackets-code-folding"),
        strings                 = require("strings"),
        store                   = {},
        DefaultSettings         = require("DefaultSettings"),
        foldsKey                = "bracket-code-folding.folds";

        //define default preference values if they have not yet been defined
        prefs.definePreference("enabled", "boolean", true,
                               {name: strings.ENABLE_CODE_FOLDING, description: strings.ENABLE_CODE_FOLDING});
        prefs.definePreference("minFoldSize", "number", 2,
                               {name: strings.MIN_FOLD_SIZE, description: strings.MIN_FOLD_SIZE_HELP});
        prefs.definePreference("saveFoldStates", "boolean", true,
                               {name: strings.SAVE_FOLD_STATES, description: strings.SAVE_FOLD_STATES_HELP});
        prefs.definePreference("alwaysUseIndentFold", "boolean", true,
                               {name: strings.ALWAYS_USE_INDENT_FOLD, description: strings.ALWAYS_USE_INDENT_FOLD_HELP});
        prefs.definePreference("enableRegionFolding", "boolean", true,
                               {name: strings.ENABLE_REGION_FOLDING, description: strings.ENABLE_REGION_FOLDING});
        prefs.definePreference("hideUntilMouseover", "boolean", false,
                               {name: strings.FADE_FOLD_BUTTONS, description: strings.FADE_FOLD_BUTTONS_HELP});
        prefs.definePreference("maxFoldLevel", "number", 2,
                               {name: strings.MAX_FOLD_LEVEL, description: strings.MAX_FOLD_LEVEL_HELP});
        PreferencesManager.stateManager.definePreference(foldsKey, "object", {});

    /**
        Simplifies the fold ranges into an array of pairs of numbers.
        @param {!{number: {from: {ch, line}, to: {ch, line}} folds the raw fold ranges indexed by line numbers
        @returns {number: Array<Array<number>>} an object whose keys are line numbers and the values are array
        of two 2-element arrays. First array contains [from.line, from.ch] and the second contains [to.line, to.ch]
    */
    function simplify(folds) {
        if (!folds) {
            return;
        }
        var res = {}, range;
        Object.keys(folds).forEach(function (line) {
            range = folds[line];
            res[line] = Array.isArray(range) ? range : [[range.from.line, range.from.ch], [range.to.line, range.to.ch]];
        });
        return res;
    }

    /**
        Inflates the fold ranges stored as simplified numeric arrays. The inflation converts the data into
        objects whose keys are line numbers and whose values are objects in the format {from: {line, ch}, to: {line, ch}}.
        @param {number: Array<Array<number>>}  folds the simplified fold ranges
        @returns {number: {from: {line, ch}, to: {line, ch}}}
    */
    function inflate(folds) {
        if (!folds) {
            return;
        }
         //transform the folds into objects with from and to properties
        var ranges = {}, obj;
        Object.keys(folds).forEach(function (line) {
            obj = folds[line];
            ranges[line] = {from: {line: obj[0][0], ch: obj[0][1]}, to: {line: obj[1][0], ch: obj[1][1]}};
        });

        return ranges;
    }

    /**
     * Returns a 'context' object for getting/setting project-specific view state preferences.
     * Similar to code in MultiRangeInlineEditor._getPrefsContext()...
     */
    function getViewStateContext() {
        var projectRoot = ProjectManager.getProjectRoot();  // note: null during unit tests!
        return { location : { scope: "user",
                              layer: "project",
                              layerID: projectRoot && projectRoot.fullPath } };
    }

    /**
      * Gets the line folds saved for the specified path.
      * @param {string} path the document path
      * @return {Object} the line folds for the document at the specified path
      */
    function getFolds(path) {
        var context = getViewStateContext();
        var folds = PreferencesManager.getViewState(foldsKey, context);
        return inflate(folds[path]);
    }

    /**
      * Saves the line folds for the specified path
      * @param {!string} path the path to the document
      * @param {Object} folds the fold ranges to save for the current document
      */
    function setFolds(path, folds) {
        var context = getViewStateContext();
        var allFolds = PreferencesManager.getViewState(foldsKey, context);
        allFolds[path] = simplify(folds);
        PreferencesManager.setViewState(foldsKey, allFolds, context);
    }

    /**
      * Get the code folding setting with the specified key from the store
      * @param {!string} key The key for the setting to retrieve
      * @return {string} the setting with the specified key
      */
    function getSetting(key) {
        return prefs.get(key);
    }
    /**
        Set the code folding setting attributed to the given key using the value supplied
        @param {!string} key the key for the setting to set
        @param {object} value the new value for the object
    */
    function setSetting(key, value) {
        prefs.set(key, value);
    }

    /**
        Gets all the values for code folding settings.
        @returns {object} all settings saved in the preferences.
    */
    function getAllSettings() {
        var res = {};
        Object.keys(DefaultSettings).forEach(function (key) {
            res[key] = getSetting(key);
        });
        return res;
    }

    /**
        Clears all the saved line folds for all documents.
    */
    function clearAllFolds() {
        PreferencesManager.setViewState(foldsKey, {});
    }

    module.exports.getFolds = getFolds;

    module.exports.setFolds = setFolds;

    module.exports.getSetting = getSetting;

    module.exports.setSetting = setSetting;

    module.exports.getAllSettings = getAllSettings;

    module.exports.clearAllFolds = clearAllFolds;

});