@wordpress/shortcode
Version:
Shortcode module for WordPress.
351 lines (311 loc) • 9.14 kB
JavaScript
/**
* External dependencies
*/
import memize from 'memize';
export * from './types';
/**
* Find the next matching shortcode.
*
* @param {string} tag Shortcode tag.
* @param {string} text Text to search.
* @param {number} index Index to start search from.
*
* @return {import('./types').ShortcodeMatch | undefined} Matched information.
*/
export function next( tag, text, index = 0 ) {
const re = regexp( tag );
re.lastIndex = index;
const match = re.exec( text );
if ( ! match ) {
return;
}
// If we matched an escaped shortcode, try again.
if ( '[' === match[ 1 ] && ']' === match[ 7 ] ) {
return next( tag, text, re.lastIndex );
}
const result = {
index: match.index,
content: match[ 0 ],
shortcode: fromMatch( match ),
};
// If we matched a leading `[`, strip it from the match and increment the
// index accordingly.
if ( match[ 1 ] ) {
result.content = result.content.slice( 1 );
result.index++;
}
// If we matched a trailing `]`, strip it from the match.
if ( match[ 7 ] ) {
result.content = result.content.slice( 0, -1 );
}
return result;
}
/**
* Replace matching shortcodes in a block of text.
*
* @param {string} tag Shortcode tag.
* @param {string} text Text to search.
* @param {import('./types').ReplaceCallback} callback Function to process the match and return
* replacement string.
*
* @return {string} Text with shortcodes replaced.
*/
export function replace( tag, text, callback ) {
return text.replace(
regexp( tag ),
function ( match, left, $3, attrs, slash, content, closing, right ) {
// If both extra brackets exist, the shortcode has been properly
// escaped.
if ( left === '[' && right === ']' ) {
return match;
}
// Create the match object and pass it through the callback.
const result = callback( fromMatch( arguments ) );
// Make sure to return any of the extra brackets if they weren't used to
// escape the shortcode.
return result || result === '' ? left + result + right : match;
}
);
}
/**
* Generate a string from shortcode parameters.
*
* Creates a shortcode instance and returns a string.
*
* Accepts the same `options` as the `shortcode()` constructor, containing a
* `tag` string, a string or object of `attrs`, a boolean indicating whether to
* format the shortcode using a `single` tag, and a `content` string.
*
* @param {Object} options
*
* @return {string} String representation of the shortcode.
*/
export function string( options ) {
return new shortcode( options ).string();
}
/**
* Generate a RegExp to identify a shortcode.
*
* The base regex is functionally equivalent to the one found in
* `get_shortcode_regex()` in `wp-includes/shortcodes.php`.
*
* Capture groups:
*
* 1. An extra `[` to allow for escaping shortcodes with double `[[]]`
* 2. The shortcode name
* 3. The shortcode argument list
* 4. The self closing `/`
* 5. The content of a shortcode when it wraps some content.
* 6. The closing tag.
* 7. An extra `]` to allow for escaping shortcodes with double `[[]]`
*
* @param {string} tag Shortcode tag.
*
* @return {RegExp} Shortcode RegExp.
*/
export function regexp( tag ) {
return new RegExp(
'\\[(\\[?)(' +
tag +
')(?![\\w-])([^\\]\\/]*(?:\\/(?!\\])[^\\]\\/]*)*?)(?:(\\/)\\]|\\](?:([^\\[]*(?:\\[(?!\\/\\2\\])[^\\[]*)*)(\\[\\/\\2\\]))?)(\\]?)',
'g'
);
}
/**
* Parse shortcode attributes.
*
* Shortcodes accept many types of attributes. These can chiefly be divided into
* named and numeric attributes:
*
* Named attributes are assigned on a key/value basis, while numeric attributes
* are treated as an array.
*
* Named attributes can be formatted as either `name="value"`, `name='value'`,
* or `name=value`. Numeric attributes can be formatted as `"value"` or just
* `value`.
*
* @param {string} text Serialised shortcode attributes.
*
* @return {import('./types').ShortcodeAttrs} Parsed shortcode attributes.
*/
export const attrs = memize( ( text ) => {
const named = {};
const numeric = [];
// This regular expression is reused from `shortcode_parse_atts()` in
// `wp-includes/shortcodes.php`.
//
// Capture groups:
//
// 1. An attribute name, that corresponds to...
// 2. a value in double quotes.
// 3. An attribute name, that corresponds to...
// 4. a value in single quotes.
// 5. An attribute name, that corresponds to...
// 6. an unquoted value.
// 7. A numeric attribute in double quotes.
// 8. A numeric attribute in single quotes.
// 9. An unquoted numeric attribute.
const pattern =
/([\w-]+)\s*=\s*"([^"]*)"(?:\s|$)|([\w-]+)\s*=\s*'([^']*)'(?:\s|$)|([\w-]+)\s*=\s*([^\s'"]+)(?:\s|$)|"([^"]*)"(?:\s|$)|'([^']*)'(?:\s|$)|(\S+)(?:\s|$)/g;
// Map zero-width spaces to actual spaces.
text = text.replace( /[\u00a0\u200b]/g, ' ' );
let match;
// Match and normalize attributes.
while ( ( match = pattern.exec( text ) ) ) {
if ( match[ 1 ] ) {
named[ match[ 1 ].toLowerCase() ] = match[ 2 ];
} else if ( match[ 3 ] ) {
named[ match[ 3 ].toLowerCase() ] = match[ 4 ];
} else if ( match[ 5 ] ) {
named[ match[ 5 ].toLowerCase() ] = match[ 6 ];
} else if ( match[ 7 ] ) {
numeric.push( match[ 7 ] );
} else if ( match[ 8 ] ) {
numeric.push( match[ 8 ] );
} else if ( match[ 9 ] ) {
numeric.push( match[ 9 ] );
}
}
return { named, numeric };
} );
/**
* Generate a Shortcode Object from a RegExp match.
*
* Accepts a `match` object from calling `regexp.exec()` on a `RegExp` generated
* by `regexp()`. `match` can also be set to the `arguments` from a callback
* passed to `regexp.replace()`.
*
* @param {import('./types').Match} match Match array.
*
* @return {InstanceType<import('./types').shortcode>} Shortcode instance.
*/
export function fromMatch( match ) {
let type;
if ( match[ 4 ] ) {
type = 'self-closing';
} else if ( match[ 6 ] ) {
type = 'closed';
} else {
type = 'single';
}
return new shortcode( {
tag: match[ 2 ],
attrs: match[ 3 ],
type,
content: match[ 5 ],
} );
}
/**
* Creates a shortcode instance.
*
* To access a raw representation of a shortcode, pass an `options` object,
* containing a `tag` string, a string or object of `attrs`, a string indicating
* the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a
* `content` string.
*
* @type {import('./types').shortcode} Shortcode instance.
*/
const shortcode = Object.assign(
function ( options ) {
const { tag, attrs: attributes, type, content } = options || {};
Object.assign( this, { tag, type, content } );
// Ensure we have a correctly formatted `attrs` object.
this.attrs = {
named: {},
numeric: [],
};
if ( ! attributes ) {
return;
}
const attributeTypes = [ 'named', 'numeric' ];
// Parse a string of attributes.
if ( typeof attributes === 'string' ) {
this.attrs = attrs( attributes );
// Identify a correctly formatted `attrs` object.
} else if (
attributes.length === attributeTypes.length &&
attributeTypes.every( ( t, key ) => t === attributes[ key ] )
) {
this.attrs = attributes;
// Handle a flat object of attributes.
} else {
Object.entries( attributes ).forEach( ( [ key, value ] ) => {
this.set( key, value );
} );
}
},
{
next,
replace,
string,
regexp,
attrs,
fromMatch,
}
);
Object.assign( shortcode.prototype, {
/**
* Get a shortcode attribute.
*
* Automatically detects whether `attr` is named or numeric and routes it
* accordingly.
*
* @param {(number|string)} attr Attribute key.
*
* @return {string} Attribute value.
*/
get( attr ) {
return this.attrs[ typeof attr === 'number' ? 'numeric' : 'named' ][
attr
];
},
/**
* Set a shortcode attribute.
*
* Automatically detects whether `attr` is named or numeric and routes it
* accordingly.
*
* @param {(number|string)} attr Attribute key.
* @param {string} value Attribute value.
*
* @return {InstanceType< import('./types').shortcode >} Shortcode instance.
*/
set( attr, value ) {
this.attrs[ typeof attr === 'number' ? 'numeric' : 'named' ][ attr ] =
value;
return this;
},
/**
* Transform the shortcode into a string.
*
* @return {string} String representation of the shortcode.
*/
string() {
let text = '[' + this.tag;
this.attrs.numeric.forEach( ( value ) => {
if ( /\s/.test( value ) ) {
text += ' "' + value + '"';
} else {
text += ' ' + value;
}
} );
Object.entries( this.attrs.named ).forEach( ( [ name, value ] ) => {
text += ' ' + name + '="' + value + '"';
} );
// If the tag is marked as `single` or `self-closing`, close the tag and
// ignore any additional content.
if ( 'single' === this.type ) {
return text + ']';
} else if ( 'self-closing' === this.type ) {
return text + ' /]';
}
// Complete the opening tag.
text += ']';
if ( this.content ) {
text += this.content;
}
// Add the closing tag.
return text + '[/' + this.tag + ']';
},
} );
export default shortcode;