Index: formatting.php
===================================================================
--- formatting.php (revision 8780)
+++ formatting.php (working copy)
@@ -51,7 +51,7 @@
$dynamic_replacements = array('’$1','$1‘', '$1″', '$1′', '$1’$2', '$1“$2', '”$1', '’$1', '$1×$2');
for ( $i = 0; $i < $stop; $i++ ) {
- $curl = $textarr[$i];
+ $curl = $textarr[$i];
if ( !empty($curl) && '<' != $curl{0} && '[' != $curl{0} && $next && !$has_pre_parent) { // If it's not a tag
// static strings
@@ -72,7 +72,7 @@
$output .= $curl;
}
- return $output;
+ return $output;
}
/**
@@ -105,7 +105,7 @@
* A group of regex replaces used to identify text formatted with newlines and
* replace double line-breaks with HTML paragraph tags. The remaining
* line-breaks after conversion become <
> tags, unless $br is set to '0'
- * or 'false'.
+ * or 'false'.
*
* @since 0.71
*
@@ -154,8 +154,6 @@
/**
* Checks to see if a string is utf8 encoded.
*
- * {@internal Missing Long Description}}
- *
* @since 1.2.1
*
* @param string $Str The string to be checked
@@ -183,7 +181,7 @@
* Converts a number of special characters into their HTML entities.
*
* Differs from htmlspecialchars as existing HTML entities will not be encoded.
- * Specificically changes: & to &, < to < and > to >.
+ * Specifically changes: & to &, < to < and > to >.
*
* $quotes can be set to 'single' to encode ' to ', 'double' to encode " to
* ", or '1' to do both. Default is 0 where no quotes are encoded.
@@ -267,8 +265,6 @@
/**
* Replaces accents in a string.
*
- * {@internal Missing Long Description}}
- *
* @since 1.2.1
*
* @param string $string The text to be filtered.
@@ -423,11 +419,10 @@
$name = preg_replace('|-+|', '-', $name);
$name = trim($name, '-');
return $name;
-
}
/**
- * Removes characters from the username.
+ * Sanitize username stripping out unsafe characters.
*
* If $strict is true, only alphanumeric characters (as well as _, space, ., -,
* @) are returned.
@@ -456,7 +451,7 @@
}
/**
- * Returns a string which has been sanitized.
+ * Sanitizes title or use fallback title.
*
* Specifically, HTML and PHP tags are stripped. Further actions can be added
* via the plugin API. If $title is empty and $fallback_title is set, the latter
@@ -479,9 +474,10 @@
}
/**
- * Replaces the string with safe characters. Whitespace becomes a dash.
+ * Sanitizes title, replacing whitespace with dashes.
*
* Limits the output to alphanumeric characters, underscore (_) and dash (-).
+ * Whitespace becomes a dash.
*
* @since 1.2.0
*
@@ -603,7 +599,7 @@
/**
* Fixes javascript bugs in browsers.
*
- * {@internal Missing Long Description}}
+ * Converts unicode characters to HTML numbered entities.
*
* @since 1.5.0
* @uses $is_macIE
@@ -616,6 +612,7 @@
// Fixes for browsers' javascript bugs
global $is_macIE, $is_winIE;
+ /** @todo use preg_replace_callback() instead */
if ( $is_winIE || $is_macIE )
$text = preg_replace("/\%u([0-9A-F]{4,4})/e", "'&#'.base_convert('\\1',16,10).';'", $text);
@@ -623,9 +620,11 @@
}
/**
- * balanceTags() - {@internal Missing Short Description}}
+ * Will only balance the tags if forced to and the option is set to balance tags.
*
- * {@internal Missing Long Description}}
+ * The option 'use_balanceTags' is used for whether the tags will be balanced.
+ * Both the $force parameter and 'use_balanceTags' option will have to be true
+ * before the tags will be balanced.
*
* @since 0.71
*
@@ -796,7 +795,9 @@
/**
* Add leading zeros when necessary.
*
- * {@internal Missing Long Description}}
+ * If you set the threshold to '4' and the number is '10', then you will get
+ * back '0010'. If you set the number to '4' and the number is '5000', then you
+ * will get back '5000'.
*
* @since 0.71
*
@@ -804,15 +805,13 @@
* @param int $threshold Amount of digits
* @return string Adds leading zeros to number if needed
*/
-function zeroise($number,$threshold) {
+function zeroise($number, $threshold) {
return sprintf('%0'.$threshold.'s', $number);
}
/**
* Adds backslashes before letters and before a number at the start of a string.
*
- * {@internal Missing Long Description}}
- *
* @since 0.71
*
* @param string $string Value to which backslashes will be added.
@@ -861,8 +860,8 @@
/**
* Adds slashes to escape strings.
*
- * Slashes will first be removed if magic_quotes_gpc is set,
- * see {@link http://www.php.net/magic_quotes} for more details.
+ * Slashes will first be removed if magic_quotes_gpc is set, see {@link
+ * http://www.php.net/magic_quotes} for more details.
*
* @since 0.71
*
@@ -882,9 +881,8 @@
/**
* Navigates through an array and removes slashes from the values.
*
- * If an array is passed, the array_map() function causes a callback to
- * pass the value back to the function. The slashes from this value will
- * removed.
+ * If an array is passed, the array_map() function causes a callback to pass the
+ * value back to the function. The slashes from this value will removed.
*
* @since 2.0.0
*
@@ -892,11 +890,8 @@
* @return array|string Stripped array (or string in the callback).
*/
function stripslashes_deep($value) {
- $value = is_array($value) ?
- array_map('stripslashes_deep', $value) :
- stripslashes($value);
-
- return $value;
+ $value = is_array($value) ? array_map('stripslashes_deep', $value) : stripslashes($value);
+ return $value;
}
/**
@@ -911,11 +906,8 @@
* @return array|string $value The encoded array (or string from the callback).
*/
function urlencode_deep($value) {
- $value = is_array($value) ?
- array_map('urlencode_deep', $value) :
- urlencode($value);
-
- return $value;
+ $value = is_array($value) ? array_map('urlencode_deep', $value) : urlencode($value);
+ return $value;
}
/**
@@ -947,15 +939,16 @@
}
/**
- * _make_url_clickable_cb() - {@internal Missing Short Description}}
+ * Callback to convert URI match to HTML A element.
*
- * {@internal Missing Long Description}}
+ * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
+ * make_clickable()}.
*
- * @since 2.5.0
+ * @since 2.3.2
* @access private
*
- * @param unknown_type $matches
- * @return unknown
+ * @param array $matches Single Regex Match.
+ * @return string HTML A element with URI address.
*/
function _make_url_clickable_cb($matches) {
$ret = '';
@@ -972,15 +965,16 @@
}
/**
- * _make_web_ftp_clickable_cb() - {@internal Missing Short Description}}
+ * Callback to convert URL match to HTML A element.
*
- * {@internal Missing Long Description}}
+ * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
+ * make_clickable()}.
*
- * @since 2.5.0
+ * @since 2.3.2
* @access private
*
- * @param unknown_type $matches
- * @return unknown
+ * @param array $matches Single Regex Match.
+ * @return string HTML A element with URL address.
*/
function _make_web_ftp_clickable_cb($matches) {
$ret = '';
@@ -998,15 +992,16 @@
}
/**
- * _make_email_clickable_cb() - {@internal Missing Short Description}}
+ * Callback to convert email address match to HTML A element.
*
- * {@internal Missing Long Description}}
+ * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
+ * make_clickable()}.
*
- * @since 2.5.0
+ * @since 2.3.2
* @access private
*
- * @param unknown_type $matches
- * @return unknown
+ * @param array $matches Single Regex Match.
+ * @return string HTML A element with email address.
*/
function _make_email_clickable_cb($matches) {
$email = $matches[2] . '@' . $matches[3];
@@ -1014,14 +1009,15 @@
}
/**
- * make_clickable() - {@internal Missing Short Description}}
+ * Convert plaintext URI to HTML links.
*
- * {@internal Missing Long Description}}
+ * Converts URI, www and ftp, and email addresses. Finishes by fixing links
+ * within links.
*
* @since 0.71
*
- * @param unknown_type $ret
- * @return unknown
+ * @param string $ret Content to convert URIs.
+ * @return string Content with converted URIs.
*/
function make_clickable($ret) {
$ret = ' ' . $ret;
@@ -1077,8 +1073,8 @@
*
* @since 0.71
*
- * @param unknown_type $text
- * @return unknown
+ * @param string $text
+ * @return string
*/
function convert_smilies($text) {
global $wp_smiliessearch, $wp_smiliesreplace;
@@ -1104,8 +1100,6 @@
/**
* Checks to see if the text is a valid email address.
*
- * {@internal Missing Long Description}}
- *
* @since 0.71
*
* @param string $user_email The email address to be checked.
@@ -1149,8 +1143,8 @@
/**
* Returns a date in the GMT equivalent.
*
- * Requires and returns a date in the Y-m-d H:i:s format.
- * Simply subtracts the value of gmt_offset.
+ * Requires and returns a date in the Y-m-d H:i:s format. Simply subtracts the
+ * value of gmt_offset.
*
* @since 1.2.0
*
@@ -1167,8 +1161,8 @@
/**
* Converts a GMT date into the correct format for the blog.
*
- * Requires and returns in the Y-m-d H:i:s format. Simply
- * adds the value of gmt_offset.
+ * Requires and returns in the Y-m-d H:i:s format. Simply adds the value of
+ * gmt_offset.
*
* @since 1.2.0
*
@@ -1185,8 +1179,6 @@
/**
* Computes an offset in seconds from an iso8601 timezone.
*
- * {@internal Missing Long Description}}
- *
* @since 1.5.0
*
* @param string $timezone Either 'Z' for 0 offset or '±hhmm'.
@@ -1208,17 +1200,17 @@
/**
* Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt].
*
- * {@internal Missing Long Description}}
- *
* @since 1.5.0
*
* @param string $date_string Date and time in ISO 8601 format {@link http://en.wikipedia.org/wiki/ISO_8601}.
- * @param unknown_type $timezone Optional. If set to GMT returns the time minus gmt_offset. Default USER.
+ * @param string $timezone Optional. If set to GMT returns the time minus gmt_offset. Default is 'user'.
* @return string The date and time in MySQL DateTime format - Y-m-d H:i:s.
*/
-function iso8601_to_datetime($date_string, $timezone = USER) {
- if ($timezone == GMT) {
+function iso8601_to_datetime($date_string, $timezone = 'user') {
+ $timezone = strtolower($timezone);
+ if ($timezone == 'gmt') {
+
preg_match('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', $date_string, $date_bits);
if (!empty($date_bits[7])) { // we have a timezone, so let's compute an offset
@@ -1232,7 +1224,7 @@
return gmdate('Y-m-d H:i:s', $timestamp);
- } else if ($timezone == USER) {
+ } else if ($timezone == 'user') {
return preg_replace('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', '$1-$2-$3 $4:$5:$6', $date_string);
}
}
@@ -1269,8 +1261,8 @@
/**
* Determines the difference between two timestamps.
*
- * The difference is returned in a human readable format such as
- * "1 hour", "5 mins", "2 days".
+ * The difference is returned in a human readable format such as "1 hour",
+ * "5 mins", "2 days".
*
* @since 1.5.0
*
@@ -1305,16 +1297,18 @@
}
/**
- * Generates an excerpt from the content if needed.
+ * Generates an excerpt from the content, if needed.
*
- * {@internal Missing Long Description}}
+ * The excerpt word amount will be 55 words and if the amount is greater than
+ * that, then the string '[...]' will be appended to the excerpt. If the string
+ * is less than 55 words, then the content will be returned as is.
*
* @since 1.5.0
*
* @param string $text The exerpt. If set to empty an excerpt is generated.
* @return string The excerpt.
*/
-function wp_trim_excerpt($text) { // Fakes an excerpt if needed
+function wp_trim_excerpt($text) {
if ( '' == $text ) {
$text = get_the_content('');
@@ -1337,8 +1331,6 @@
/**
* Converts named entities into numbered entities.
*
- * {@internal Missing Long Description}}
- *
* @since 1.5.1
*
* @param string $text The text within which entities will be converted.
@@ -1609,10 +1601,10 @@
}
/**
- * Formats text for the rich text editor and applies filter.
+ * Formats text for the rich text editor.
*
- * The filter 'richedit_pre' is applied here. If $text is empty
- * the filter will be applied to an empty string.
+ * The filter 'richedit_pre' is applied here. If $text is empty the filter will
+ * be applied to an empty string.
*
* @since 2.0.0
*
@@ -1631,12 +1623,12 @@
}
/**
- * Formats text for the HTML editor and applies a filter.
+ * Formats text for the HTML editor.
*
- * Unless $output is empty it will pass through htmlspecialchars
- * before the 'htmledit_pre' filter is applied.
+ * Unless $output is empty it will pass through htmlspecialchars before the
+ * 'htmledit_pre' filter is applied.
*
- * @since unknown
+ * @since 2.5.0
*
* @param string $output The text to be formatted.
* @return string Formatted text after filter applied.
@@ -1651,13 +1643,13 @@
/**
* Checks and cleans a URL.
*
- * A number of characters are removed from the URL. If the URL is
- * for displaying (the default behaviour) amperstands are also replaced.
- * The 'clean_url' filter is applied to the returned cleaned URL.
+ * A number of characters are removed from the URL. If the URL is for displaying
+ * (the default behaviour) amperstands are also replaced. The 'clean_url' filter
+ * is applied to the returned cleaned URL.
*
* @since 1.2.0
* @uses wp_kses_bad_protocol() To only permit protocols in the URL set
- * via $protocols or the common ones set in the function.
+ * via $protocols or the common ones set in the function.
*
* @param string $url The URL to be cleaned.
* @param array $protocols Optional. An array of acceptable protocols.
@@ -1711,8 +1703,6 @@
/**
* Convert entities, while preserving already-encoded entities.
*
- * {@internal Missing Long Description}}
- *
* @link http://www.php.net/htmlentities Borrowed from the PHP Manual user notes.
*
* @since 1.2.2
@@ -1746,7 +1736,7 @@
/**
* Escaping for HTML attributes.
*
- * @since unknown
+ * @since 2.0.6
*
* @param string $text
* @return string
@@ -1759,7 +1749,7 @@
/**
* Escape a HTML tag name.
*
- * @since unknown
+ * @since 2.5.0
*
* @param string $tag_name
* @return string
@@ -1772,7 +1762,7 @@
/**
* Escapes text for SQL LIKE special characters % and _.
*
- * @since unknown
+ * @since 2.5.0
*
* @param string $text The text to be escaped.
* @return string text, safe for inclusion in LIKE query.
@@ -1782,22 +1772,25 @@
}
/**
- * {@internal Missing Short Description}}
+ * Convert full URL paths to absolute paths.
*
- * @since unknown
+ * Removes the http or https protocols and the domain. Keeps the path '/' at the
+ * beginning, so it isn't a true relative link, but from the web root base.
*
- * @param string $link
- * @return string
+ * @since 2.1.0
+ *
+ * @param string $link Full URL path.
+ * @return string Absolute path.
*/
function wp_make_link_relative( $link ) {
- return preg_replace('|https?://[^/]+(/.*)|i', '$1', $link );
+ return preg_replace( '|https?://[^/]+(/.*)|i', '$1', $link );
}
/**
* Sanitises various option values based on the nature of the option.
*
- * This is basically a switch statement which will pass $value through
- * a number of functions depending on the $option.
+ * This is basically a switch statement which will pass $value through a number
+ * of functions depending on the $option.
*
* @since 2.0.5
*
@@ -1805,7 +1798,7 @@
* @param string $value The unsanitised value.
* @return string Sanitized value.
*/
-function sanitize_option($option, $value) { // Remember to call stripslashes!
+function sanitize_option($option, $value) {
switch ($option) {
case 'admin_email':
@@ -1882,8 +1875,8 @@
/**
* Parses a string into variables to be stored in an array.
*
- * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes
- * if {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on.
+ * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes if
+ * {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on.
*
* @since 2.2.1
* @uses apply_filters() for the 'wp_parse_str' filter.
@@ -1904,7 +1897,7 @@
* KSES already converts lone greater than signs.
*
* @uses wp_pre_kses_less_than_callback in the callback function.
- * @since unknown
+ * @since 2.3.0
*
* @param string $text Text to be converted.
* @return string Converted text.
@@ -1916,8 +1909,8 @@
/**
* Callback function used by preg_replace.
*
- * @since unknown
* @uses wp_specialchars to format the $matches text.
+ * @since 2.3.0
*
* @param array $matches Populated by matches to preg_replace.
* @return string The text returned after wp_specialchars if needed.
@@ -1931,7 +1924,7 @@
/**
* WordPress implementation of PHP sprintf() with filters.
*
- * @since unknown
+ * @since 2.5.0
* @link http://www.php.net/sprintf
*
* @param string $pattern The string which formatted args are inserted.
@@ -1991,13 +1984,17 @@
}
/**
- * List specifier %l for wp_sprintf.
+ * Localize list items before the rest of the content.
*
- * @since unknown
+ * The '%l' must be at the first characters can then contain the rest of the
+ * content. The list items will have ', ', ', and', and ' and ' added depending
+ * on the amount of list items in the $args parameter.
*
- * @param unknown_type $pattern
- * @param unknown_type $args
- * @return unknown
+ * @since 2.5.0
+ *
+ * @param string $pattern Content containing '%l' at the beginning.
+ * @param array $args List items to prepend to the content and replace '%l'.
+ * @return string Localized list items and rest of the content.
*/
function wp_sprintf_l($pattern, $args) {
// Not a match
@@ -2020,7 +2017,9 @@
if ( count($args) == 1 )
$result .= $l['between_only_two'] . array_shift($args);
// Loop when more than two args
- while ( count($args) ) {
+ // There is a bug in this code that doesn't meet the above comment's
+ // requirements.
+ while ( $i = count($args) ) {
$arg = array_shift($args);
if ( $i == 1 )
$result .= $l['between_last_two'] . $arg;
@@ -2037,6 +2036,8 @@
* be counted as one character. For example & will be counted as 4, < as
* 3, etc.
*
+ * @since 2.5.0
+ *
* @param integer $str String to get the excerpt from.
* @param integer $count Maximum number of characters to take.
* @return string The excerpt.
@@ -2052,11 +2053,10 @@
/**
* Add a Base url to relative links in passed content.
*
- * By default it supports the 'src' and 'href' attributes,
- * However this may be changed via the 3rd param.
+ * By default it supports the 'src' and 'href' attributes. However this can be
+ * changed via the 3rd param.
*
- * @package WordPress
- * @since 2.7
+ * @since 2.7.0
*
* @param string $content String to search for links in.
* @param string $base The base URL to prefix to links.
@@ -2073,10 +2073,9 @@
/**
* Callback to add a base url to relative links in passed content.
*
+ * @since 2.7.0
+ * @access private
*
- * @package WordPress
- * @since 2.7
- *
* @param string $m The matched link.
* @param string $base The base URL to prefix to links.
* @return string The processed link.
@@ -2093,13 +2092,13 @@
/**
* Adds a Target attribute to all links in passed content.
*
- * This function by default only applies to tags,
- * however this can be modified by the 3rd param.
- * NOTE: Any current target attributed will be striped and replaced.
+ * This function by default only applies to tags, however this can be
+ * modified by the 3rd param.
*
- * @package WordPress
- * @since 2.7
+ * NOTE: Any current target attributed will be striped and replaced.
*
+ * @since 2.7.0
+ *
* @param string $content String to search for links in.
* @param string $target The Target to add to the links.
* @param array $tags An array of tags to apply to.
@@ -2114,10 +2113,9 @@
/**
* Callback to add a target attribute to all links in passed content.
*
+ * @since 2.7.0
+ * @access private
*
- * @package WordPress
- * @since 2.7
- *
* @param string $m The matched link.
* @param string $target The Target to add to the links.
* @return string The processed link.