autolinker - npm Package Compare versions

Comparing version 0.12.1 to 0.12.2

dist/Autolinker.min.js

 /*!
  * Autolinker.js
- * 0.12.1
+ * 0.12.2
  *
@@ -5,0 +5,0 @@ * Copyright(c) 2014 Gregory Jacobs <[e-mail]>

Gruntfile.js

@@ -1,5 +0,7 @@
-/*global module */
+/*global require, module */
+/*jshint devel:true */
 module.exports = function(grunt) {
 	'use strict';
 	
+	var exec = require( 'child_process' ).exec;
 	var banner = createBanner();
@@ -72,2 +74,19 @@
 			}
+		},
+		
+		jsduck: {
+			main: {
+				// source paths with your code
+				src: [
+					'src/**/*.js'
+				],
+		
+				// docs output dir
+				dest: 'docs',
+		
+				// extra options
+				options: {
+					'title': 'Autolinker API Docs'
+				}
+			}
 		}
@@ -82,9 +101,9 @@ } );
 	grunt.loadNpmTasks( 'grunt-contrib-jshint' );
+	grunt.loadNpmTasks( 'grunt-jsduck' );
 
 	// Tasks
-	grunt.registerTask( 'default', [ 'lint', 'build', 'doTest' ] );
-	grunt.registerTask( 'lint', [ 'jshint' ] );
-	grunt.registerTask( 'test', [ 'build', 'doTest' ] );
-	grunt.registerTask( 'doTest', [ 'jasmine' ] );
+	grunt.registerTask( 'default', [ 'jshint', 'build', 'jasmine' ] );
 	grunt.registerTask( 'build', [ 'concat:development', 'uglify:production' ] );
+	grunt.registerTask( 'test', [ 'build', 'jasmine' ] );
+	grunt.registerTask( 'doc', "Builds the documentation.", [ 'jshint', 'jsduck' ] );
 	grunt.registerTask( 'serve', [ 'connect:server:keepalive' ] );
@@ -91,0 +110,0 @@

package.json

 {
   "name": "autolinker",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Utility to automatically link the URLs, email addresses, and Twitter handles in a given block of text/HTML",
@@ -37,4 +37,5 @@ "main": "dist/Autolinker.js",
     "grunt-contrib-concat": "^0.4.0",
-    "grunt-contrib-jshint": "^0.10.0"
+    "grunt-contrib-jshint": "^0.10.0",
+    "grunt-jsduck": "^1.0.1"
   }
 }

README.md

@@ -223,3 +223,7 @@ # Autolinker.js
 
+## Full API Docs
 
+The full API docs for Autolinker may be referenced at: [http://gregjacobs.github.io/Autolinker.js/docs/](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker)
+
+
 ## Changelog:
@@ -226,0 +230,0 @@

src/AnchorTagBuilder.js

@@ -9,2 +9,18 @@ /*global Autolinker */
  * Builds anchor (<a>) tags for the Autolinker utility when a match is found.
+ * 
+ * Normally this class is instantiated, configured, and used internally by an {@link Autolinker} instance, but may 
+ * actually be retrieved in a {@link Autolinker#replaceFn replaceFn} to create {@link Autolinker.HtmlTag HtmlTag} instances
+ * which may be modified before returning from the {@link Autolinker#replaceFn replaceFn}. For example:
+ * 
+ *     var html = Autolinker.link( "Test google.com", {
+ *         replaceFn : function( autolinker, match ) {
+ *             var tag = autolinker.getTagBuilder().build( match );  // returns an {@link Autolinker.HtmlTag} instance
+ *             tag.setAttr( 'rel', 'nofollow' );
+ *             
+ *             return tag;
+ *         }
+ *     } );
+ *     
+ *     // generated html:
+ *     //   Test <a href="http://google.com" target="_blank" rel="nofollow">google.com</a>
  */
@@ -15,4 +31,3 @@ Autolinker.AnchorTagBuilder = Autolinker.Util.extend( Object, {
 	 * @cfg {Boolean} newWindow
-	 * 
-	 * See {@link Autolinker#newWindow} for details.
+	 * @inheritdoc Autolinker#newWindow
 	 */
@@ -22,4 +37,3 @@
 	 * @cfg {Number} truncate
-	 * 
-	 * See {@link Autolinker#truncate} for details.
+	 * @inheritdoc Autolinker#truncate
 	 */
@@ -29,4 +43,3 @@
 	 * @cfg {String} className
-	 * 
-	 * See {@link Autolinker#className} for details.
+	 * @inheritdoc Autolinker#className
 	 */
@@ -107,4 +120,3 @@
 	/**
-	 * Processes the `anchorText` by stripping the URL prefix (if {@link #stripPrefix} is `true`), removing
-	 * any trailing slash, and truncating the text according to the {@link #truncate} config.
+	 * Processes the `anchorText` by truncating the text according to the {@link #truncate} config.
 	 * 
@@ -111,0 +123,0 @@ * @private

src/Autolinker.js

@@ -39,32 +39,42 @@ /**
  * 
- * var input = "...";  // string with URLs, Email Addresses, and Twitter Handles
- * 
- * var linkedText = Autolinker.link( input, {
- *     replaceFn : function( autolinker, match ) {
- *         console.log( "href = ", match.getAnchorHref() );
- *         console.log( "text = ", match.getAnchorText() );
+ *     var input = "...";  // string with URLs, Email Addresses, and Twitter Handles
  *     
- *         switch( match.getType() ) {
- *             case 'url' : 
- *                 console.log( "url: ", match.getUrl() );
- *                 return true;  // let Autolinker perform its normal anchor tag replacement
+ *     var linkedText = Autolinker.link( input, {
+ *         replaceFn : function( autolinker, match ) {
+ *             console.log( "href = ", match.getAnchorHref() );
+ *             console.log( "text = ", match.getAnchorText() );
+ *         
+ *             switch( match.getType() ) {
+ *                 case 'url' : 
+ *                     console.log( "url: ", match.getUrl() );
+ *                     
+ *                     if( match.getUrl().indexOf( 'mysite.com' ) === -1 ) {
+ *                         var tag = autolinker.getTagBuilder().build( match );  // returns an `Autolinker.HtmlTag` instance, which provides mutator methods for easy changes
+ *                         tag.setAttr( 'rel', 'nofollow' );
+ *                         tag.addClass( 'external-link' );
+ *                         
+ *                         return tag;
+ *                         
+ *                     } else {
+ *                         return true;  // let Autolinker perform its normal anchor tag replacement
+ *                     }
+ *                     
+ *                 case 'email' :
+ *                     var email = match.getEmail();
+ *                     console.log( "email: ", email );
+ *                     
+ *                     if( email === "[e-mail]" ) {
+ *                         return false;  // don't auto-link this particular email address; leave as-is
+ *                     } else {
+ *                         return;  // no return value will have Autolinker perform its normal anchor tag replacement (same as returning `true`)
+ *                     }
  *                 
- *             case 'email' :
- *                 var email = match.getEmail();
- *                 console.log( "email: ", email );
- *                 
- *                 if( email === "[e-mail]" ) {
- *                     return false;  // don't auto-link this particular email address; leave as-is
- *                 } else {
- *                     return;  // no return value will have Autolinker perform its normal anchor tag replacement (same as returning `true`)
- *                 }
- *             
- *             case 'twitter' :
- *                 var twitterHandle = match.getTwitterHandle();
- *                 console.log( twitterHandle );
- *                 
- *                 return '<a href="http://newplace.to.link.twitter.handles.to/">' + twitterHandle + '</a>';
+ *                 case 'twitter' :
+ *                     var twitterHandle = match.getTwitterHandle();
+ *                     console.log( twitterHandle );
+ *                     
+ *                     return '<a href="http://newplace.to.link.twitter.handles.to/">' + twitterHandle + '</a>';
+ *             }
  *         }
- *     }
- * } );
+ *     } );
  * 
@@ -76,4 +86,5 @@ *
  * - `false` (Boolean): Do not replace the current match at all - leave as-is.
- * - Any string: If a string is returned from the function, the string will be used directly as the replacement HTML for
+ * - Any String: If a string is returned from the function, the string will be used directly as the replacement HTML for
  *   the match.
+ * - An {@link Autolinker.HtmlTag} instance, which can be used to build/modify an HTML tag before writing out its HTML text.
  * 
@@ -146,5 +157,5 @@ * @constructor
 	 * 
-	 * 1) URL links will have the CSS classes: "myLink myLink-url"
-	 * 2) Email links will have the CSS classes: "myLink myLink-email", and
-	 * 3) Twitter links will have the CSS classes: "myLink myLink-twitter"
+	 * - URL links will have the CSS classes: "myLink myLink-url"
+	 * - Email links will have the CSS classes: "myLink myLink-email", and
+	 * - Twitter links will have the CSS classes: "myLink myLink-twitter"
 	 */
@@ -159,2 +170,10 @@ className : "",
 	 * See the class's description for usage.
+	 * 
+	 * This function is called with the following parameters:
+	 * 
+	 * @cfg {Autolinker} replaceFn.autolinker The Autolinker instance, which may be used to retrieve child objects from (such
+	 *   as the instance's {@link #getTagBuilder tag builder}).
+	 * @cfg {Autolinker.match.Match} replaceFn.match The Match instance which can be used to retrieve information about the
+	 *   {@link Autolinker.match.Url URL}/{@link Autolinker.match.Email email}/{@link Autolinker.match.Twitter Twitter}
+	 *   match that the `replaceFn` is currently processing.
 	 */
@@ -181,6 +200,6 @@
 	 * 
-	 * 1. Group that is used to determine if there is a Twitter handle match (i.e. @someTwitterUser). Simply check for its 
+	 * 1. Group that is used to determine if there is a Twitter handle match (i.e. \@someTwitterUser). Simply check for its 
 	 *    existence to determine if there is a Twitter handle match. The next couple of capturing groups give information 
 	 *    about the Twitter handle match.
-	 * 2. The whitespace character before the @sign in a Twitter handle. This is needed because there are no lookbehinds in
+	 * 2. The whitespace character before the \@sign in a Twitter handle. This is needed because there are no lookbehinds in
 	 *    JS regular expressions, and can be used to reconstruct the original string in a replace().
@@ -288,2 +307,10 @@ * 3. The Twitter handle itself in a Twitter match. If the match is '@someTwitterUser', the handle is 'someTwitterUser'.
 	 * @private
+	 * @property {Autolinker.HtmlParser} htmlParser
+	 * 
+	 * The HtmlParser instance used to skip over HTML tags, while finding text nodes to process. This is lazily instantiated
+	 * in the {@link #getHtmlParser} method.
+	 */
+	
+	/**
+	 * @private
 	 * @property {Autolinker.AnchorTagBuilder} tagBuilder
@@ -375,2 +402,17 @@ *
 	 * 
+	 * This method may be used in a {@link #replaceFn} to generate the {@link Autolinker.HtmlTag HtmlTag} instance that 
+	 * Autolinker would normally generate, and then allow for modifications before returning it. For example:
+	 * 
+	 *     var html = Autolinker.link( "Test google.com", {
+	 *         replaceFn : function( autolinker, match ) {
+	 *             var tag = autolinker.getTagBuilder().build( match );  // returns an {@link Autolinker.HtmlTag} instance
+	 *             tag.setAttr( 'rel', 'nofollow' );
+	 *             
+	 *             return tag;
+	 *         }
+	 *     } );
+	 *     
+	 *     // generated html:
+	 *     //   Test <a href="http://google.com" target="_blank" rel="nofollow">google.com</a>
+	 * 
 	 * @return {Autolinker.AnchorTagBuilder}
@@ -377,0 +419,0 @@ */

src/HtmlParser.js

 /*global Autolinker */
 /**
+ * @private
  * @class Autolinker.HtmlParser
  * @extends Object
  * 
- * An HTML parser which simply walks an HTML string and calls the provided visitor functions to process HTML 
- * and text nodes.
+ * An HTML parser implementation which simply walks an HTML string and calls the provided visitor functions to process 
+ * HTML and text nodes.
  * 
- * Autolinker uses this to only link URLs/emails/Twitter handles in text nodes, basically ignoring HTML tags.
+ * Autolinker uses this to only link URLs/emails/Twitter handles within text nodes, basically ignoring HTML tags.
  */
@@ -11,0 +12,0 @@ Autolinker.HtmlParser = Autolinker.Util.extend( Object, {

src/HtmlTag.js

@@ -7,3 +7,71 @@ /*global Autolinker */
  * 
- * Represents an HTML tag, which can be used to build HTML tags piece-by-piece programmatically.
+ * Represents an HTML tag, which can be used to easily build/modify HTML tags programmatically.
+ * 
+ * Autolinker uses this abstraction to create HTML tags, and then write them out as strings. You may also use
+ * this class in your code, especially within a {@link Autolinker#replaceFn replaceFn}.
+ * 
+ * ## Examples
+ * 
+ * Example instantiation:
+ * 
+ *     var tag = new Autolinker.HtmlTag( {
+ *         tagName : 'a',
+ *         attrs   : { 'href': 'http://google.com', 'class': 'external-link' },
+ *         innerHtml : 'Google'
+ *     } );
+ *     
+ *     tag.toString();  // <a href="http://google.com" class="external-link">Google</a>
+ *     
+ *     // Individual accessor methods
+ *     tag.getTagName();                 // 'a'
+ *     tag.getAttr( 'href' );            // 'http://google.com'
+ *     tag.hasClass( 'external-link' );  // true
+ * 
+ * 
+ * Using mutator methods (which may be used in combination with instantiation config properties):
+ * 
+ *     var tag = new Autolinker.HtmlTag();
+ *     tag.setTagName( 'a' );
+ *     tag.setAttr( 'href', 'http://google.com' );
+ *     tag.addClass( 'external-link' );
+ *     tag.setInnerHtml( 'Google' );
+ *     
+ *     tag.getTagName();                 // 'a'
+ *     tag.getAttr( 'href' );            // 'http://google.com'
+ *     tag.hasClass( 'external-link' );  // true
+ *     
+ *     tag.toString();  // <a href="http://google.com" class="external-link">Google</a>
+ *     
+ * 
+ * ## Example use within a {@link Autolinker#replaceFn replaceFn}
+ * 
+ *     var html = Autolinker.link( "Test google.com", {
+ *         replaceFn : function( autolinker, match ) {
+ *             var tag = autolinker.getTagBuilder().build( match );  // returns an {@link Autolinker.HtmlTag} instance, configured with the Match's href and anchor text
+ *             tag.setAttr( 'rel', 'nofollow' );
+ *             
+ *             return tag;
+ *         }
+ *     } );
+ *     
+ *     // generated html:
+ *     //   Test <a href="http://google.com" target="_blank" rel="nofollow">google.com</a>
+ *     
+ *     
+ * ## Example use with a new tag for the replacement
+ * 
+ *     var html = Autolinker.link( "Test google.com", {
+ *         replaceFn : function( autolinker, match ) {
+ *             var tag = new Autolinker.HtmlTag( {
+ *                 tagName : 'button',
+ *                 attrs   : { 'title': 'Load URL: ' + match.getAnchorHref() },
+ *                 innerHtml : 'Load URL: ' + match.getAnchorText()
+ *             } );
+ *             
+ *             return tag;
+ *         }
+ *     } );
+ *     
+ *     // generated html:
+ *     //   Test <button title="Load URL: http://google.com">Load URL: google.com</button>
  */
@@ -10,0 +78,0 @@ Autolinker.HtmlTag = Autolinker.Util.extend( Object, {

src/match/Email.js

 /*global Autolinker */
 /**
- * @private
  * @class Autolinker.match.Email
+ * @extends Autolinker.match.Match
  * 
  * Represents a Email match found in an input string which should be Autolinked.
+ * 
+ * See this class's superclass ({@link Autolinker.match.Match}) for more details.
  */
@@ -8,0 +10,0 @@ Autolinker.match.Email = Autolinker.Util.extend( Autolinker.match.Match, {

src/match/Match.js

 /*global Autolinker */
 /**
- * @private
  * @abstract
  * @class Autolinker.match.Match
  * 
- * Represents a match found in an input string which should be Autolinked.
+ * Represents a match found in an input string which should be Autolinked. A Match object is what is provided in a 
+ * {@link Autolinker#replaceFn replaceFn}, and may be used to query for details about the match.
+ * 
+ * For example:
+ * 
+ *     var input = "...";  // string with URLs, Email Addresses, and Twitter Handles
+ *     
+ *     var linkedText = Autolinker.link( input, {
+ *         replaceFn : function( autolinker, match ) {
+ *             console.log( "href = ", match.getAnchorHref() );
+ *             console.log( "text = ", match.getAnchorText() );
+ *         
+ *             switch( match.getType() ) {
+ *                 case 'url' : 
+ *                     console.log( "url: ", match.getUrl() );
+ *                     
+ *                 case 'email' :
+ *                     console.log( "email: ", match.getEmail() );
+ *                     
+ *                 case 'twitter' :
+ *                     console.log( "twitter: ", match.getTwitterHandle() );
+ *             }
+ *         }
+ *     } );
+ *     
+ * See the {@link Autolinker} class for more details on using the {@link Autolinker#replaceFn replaceFn}.
  */
@@ -9,0 +33,0 @@ Autolinker.match.Match = Autolinker.Util.extend( Object, {

src/match/Twitter.js

 /*global Autolinker */
 /**
- * @private
  * @class Autolinker.match.Twitter
+ * @extends Autolinker.match.Match
  * 
  * Represents a Twitter match found in an input string which should be Autolinked.
+ * 
+ * See this class's superclass ({@link Autolinker.match.Match}) for more details.
  */
@@ -8,0 +10,0 @@ Autolinker.match.Twitter = Autolinker.Util.extend( Autolinker.match.Match, {

src/match/Url.js

 /*global Autolinker */
 /**
- * @private
- * @class Autolinker.match.Twitter
+ * @class Autolinker.match.Url
+ * @extends Autolinker.match.Match
  * 
  * Represents a Url match found in an input string which should be Autolinked.
+ * 
+ * See this class's superclass ({@link Autolinker.match.Match}) for more details.
  */
@@ -25,4 +27,3 @@ Autolinker.match.Url = Autolinker.Util.extend( Autolinker.match.Match, {
 	 * @cfg {Boolean} stripPrefix (required)
-	 * 
-	 * See {@link Autolinker#stripPrefix} for details.
+	 * @inheritdoc {@link Autolinker#stripPrefix}
 	 */
@@ -162,4 +163,4 @@
 		return anchorText;
-	},
+	}
 	
 } );

New alerts

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

230057

increased by6.93%

Lines of code

4206

increased by8.18%

Number of lines in readme file

343

increased by1.18%

Worsened metrics

Dev dependency count

8

increased by14.29%

No dependency changes