highlight/js/highlight-base.js

/**
Provides methods for highlighting strings within other strings by wrapping
them in HTML.

@module highlight
@submodule highlight-base
@main
@since 3.3.0
**/

/**
Provides methods for highlighting strings within other strings by wrapping
them in HTML.

The highlight methods first escape any special HTML characters in the input
strings and then highlight the appropriate substrings by wrapping them in a
`<b class="yui3-highlight"></b>` element. The `<b>` element is used rather than
`<strong>` in accordance with HTML5's definition of `<b>` as being purely
presentational, which is exactly what highlighting is.

@class Highlight
@static
**/

var YArray    = Y.Array,
    Escape    = Y.Escape,
    WordBreak = Y.Text.WordBreak,

    isArray = Y.Lang.isArray,

    EMPTY_OBJECT = {},

    // Regex string that captures zero or one unclosed HTML entities. Used in
    // the static regex template properties below. The entity matching is
    // intentionally loose here, since there's a world of complexity involved in
    // doing strict matching for this use case.
    UNCLOSED_ENTITY = '(&[^;\\s]*)?',

Highlight = {
    // -- Protected Static Properties ------------------------------------------

    /**
    Regular expression template for highlighting a match that occurs anywhere
    in a string. The placeholder `%needles` will be replaced with a list of
    needles to match, joined by `|` characters.

    This regex should have two capturing subpatterns:

      1. Zero or one unclosed HTML entity (e.g. "&amp" without a ";" at the
         end).
      2. The `%needles` placeholder.

    The first subpattern match is used to emulate a negative lookbehind
    assertion in order to prevent highlighting inside HTML entities.

    @property _REGEX
    @type String
    @protected
    @static
    @final
    **/
    _REGEX: UNCLOSED_ENTITY + '(%needles)',

    /**
    Regex replacer function or string for normal matches.

    @property _REPLACER
    @type Function|String
    @protected
    @static
    @final
    **/
    _REPLACER: function (match, p1, p2) {
         // Mimicking a negative lookbehind assertion to prevent matches inside
         // HTML entities. Hat tip to Steven Levithan for the technique:
         // http://blog.stevenlevithan.com/archives/mimic-lookbehind-javascript
         return p1 && !(/\s/).test(p2) ? match :
                    Highlight._TEMPLATE.replace(/\{s\}/g, p2);
     },

    /**
    Regular expression template for highlighting start-of-string matches
    (i.e., only matches that occur at the beginning of a string). The
    placeholder `%needles` will be replaced with a list of needles to match,
    joined by `|` characters.

    See `_REGEX` for a description of the capturing subpatterns this regex
    string should contain.

    @property _START_REGEX
    @type String
    @protected
    @static
    @final
     */
    _START_REGEX: '^' + UNCLOSED_ENTITY + '(%needles)',

    /**
    Highlight template which will be used as a replacement for matched
    substrings. The placeholder `{s}` will be replaced with the matched
    substring.

    @property _TEMPLATE
    @type String
    @default '<b class="yui3-highlight">{s}</b>'
    @protected
    @static
    @final
    **/
    _TEMPLATE: '<b class="' + Y.ClassNameManager.getClassName('highlight') + '">{s}</b>',

    // -- Public Static Methods ------------------------------------------------

    /**
    Highlights all occurrences in the _haystack_ string of the items in the
    _needles_ array, regardless of where they occur. The returned string will
    have all HTML characters escaped except for the highlighting markup.

    @method all
    @param {String} haystack String to apply highlighting to.
    @param {String|String[]} needles String or array of strings that should be
        highlighted.
    @param {Object} [options] Options object.
    @param {Boolean} [options.caseSensitive=false] If `true`, matching will
        be case-sensitive.
    @param {Boolean} [options.startsWith=false] If `true`, matches must be
        anchored to the beginning of the string.
    @return {String} Escaped and highlighted copy of _haystack_.
    @static
    **/
    all: function (haystack, needles, options) {
        var validNeedles = [],
            esc, i, len, needle, regex, replacer;

        if (!options) {
            options = EMPTY_OBJECT;
        }

        // TODO: document options.replacer
        esc      = options.escapeHTML !== false;
        regex    = options.startsWith ? Highlight._START_REGEX : Highlight._REGEX;
        replacer = options.replacer || Highlight._REPLACER;
        needles  = isArray(needles) ? needles : [needles];

        // Escape HTML characters and special regular expression characters in
        // the needles so they can be used in a regex and matched against the
        // escaped haystack.
        for (i = 0, len = needles.length; i < len; ++i) {
            needle = needles[i];

            if (needle) {
                validNeedles.push(Escape.regex(esc ? Escape.html(needle) : needle));
            }
        }

        // Escape HTML characters in the haystack to prevent HTML injection.
        if (esc) {
            haystack = Escape.html(haystack);
        }

        // No point continuing if there are no needles.
        if (!validNeedles.length) {
            return haystack;
        }

        return haystack.replace(
            new RegExp(
                regex.replace('%needles', validNeedles.join('|')),
                options.caseSensitive ? 'g' : 'gi'
            ),
            replacer
        );
    },

    /**
    Same as `all()`, but case-sensitive by default.

    @method allCase
    @param {String} haystack String to apply highlighting to.
    @param {String|String[]} needles String or array of strings that should be
      highlighted.
    @param {Object} [options] Options object. See `all()` for details.
    @return {String} Escaped and highlighted copy of _haystack_.
    @static
    **/
    allCase: function (haystack, needles, options) {
        return Highlight.all(haystack, needles,
                Y.merge(options || EMPTY_OBJECT, {caseSensitive: true}));
    },

    /**
    Highlights _needles_ that occur at the start of _haystack_. The returned
    string will have all HTML characters escaped except for the highlighting
    markup.

    @method start
    @param {String} haystack String to apply highlighting to.
    @param {String|String[]} needles String or array of strings that should be
      highlighted.
    @param {Object} [options] Options object.
    @param {Boolean} [options.caseSensitive=false] If `true`, matching will
        be case-sensitive.
    @return {String} Escaped and highlighted copy of _haystack_.
    @static
    **/
    start: function (haystack, needles, options) {
        return Highlight.all(haystack, needles,
                Y.merge(options || EMPTY_OBJECT, {startsWith: true}));
    },

    /**
    Same as `start()`, but case-sensitive by default.

    @method startCase
    @param {String} haystack String to apply highlighting to.
    @param {String|String[]} needles String or array of strings that should be
      highlighted.
    @return {String} Escaped and highlighted copy of _haystack_.
    @static
    **/
    startCase: function (haystack, needles) {
        // No options passthru for now, since it would be redundant. If start()
        // ever supports more options than caseSensitive, then we'll start
        // passing the options through.
        return Highlight.start(haystack, needles, {caseSensitive: true});
    },

    /**
    Highlights complete words in the _haystack_ string that are also in the
    _needles_ array. The returned string will have all HTML characters escaped
    except for the highlighting markup.

    @method words
    @param {String} haystack String to apply highlighting to.
    @param {String|String[]} needles String or array of strings containing words
      that should be highlighted. If a string is passed, it will be split
      into words; if an array is passed, it is assumed to have already been
      split.
    @param {Object} [options] Options object.
    @param {Boolean} [options.caseSensitive=false] If `true`, matching will
        be case-sensitive.
    @return {String} Escaped and highlighted copy of _haystack_.
    @static
    **/
    words: function (haystack, needles, options) {
        var caseSensitive,
            mapper,
            template = Highlight._TEMPLATE,
            words;

        if (!options) {
            options = EMPTY_OBJECT;
        }

        caseSensitive = !!options.caseSensitive;

        // Convert needles to a hash for faster lookups.
        needles = YArray.hash(
            isArray(needles) ? needles : WordBreak.getUniqueWords(needles, {
                ignoreCase: !caseSensitive
            })
        );

        // The default word mapping function can be overridden with a custom
        // one. This is used to implement accent-folded highlighting in the
        // highlight-accentfold module.
        mapper = options.mapper || function (word, needles) {
            if (needles.hasOwnProperty(caseSensitive ? word : word.toLowerCase())) {
                return template.replace(/\{s\}/g, Escape.html(word));
            }

            return Escape.html(word);
        };

        // Split the haystack into an array of words, including punctuation and
        // whitespace so we can rebuild the string later.
        words = WordBreak.getWords(haystack, {
            includePunctuation: true,
            includeWhitespace : true
        });

        return YArray.map(words, function (word) {
            return mapper(word, needles);
        }).join('');
    },

    /**
    Same as `words()`, but case-sensitive by default.

    @method wordsCase
    @param {String} haystack String to apply highlighting to.
    @param {String|String[]} needles String or array of strings containing words
      that should be highlighted. If a string is passed, it will be split
      into words; if an array is passed, it is assumed to have already been
      split.
    @return {String} Escaped and highlighted copy of _haystack_.
    @static
    **/
    wordsCase: function (haystack, needles) {
        // No options passthru for now, since it would be redundant. If words()
        // ever supports more options than caseSensitive, then we'll start
        // passing the options through.
        return Highlight.words(haystack, needles, {caseSensitive: true});
    }
};

Y.Highlight = Highlight;