angular-hint-log

Angular Hint Log

A library to format messages for AngularHint.

See the AngularHintLog NPM Module and the AngularHint NPM Module.

Usage

###1. Overview

AngularHint provides runtime hinting for AngularJS. This hinting relies on various AngularHint modules that cover different areas of AngularJS such as controllers and modules. To collect and format the messages from these various modules, AngularHintLog provides a message queue. Inside this message queue, messages are categorized according to their source module. This allows AngularHint to provide grouped messages.

###2. API

####logMessage

#####Use as: logMessage(moduleName, message, severity)

Log a message to the AngularHintLog queue.

####Example

var hintLog = require('angular-hint-log');
var message = 'The best practice is to name controllers with "Controller"'
//adds the message to the queue
//marks as coming from the `Controllers` module and being a `Suggestion Message`
hintLog.logMessage('Controllers', message, 3);

####Params

Param	Type	Description
moduleName	String	The name of the AngularHintModule from which the message is logged
message	String	A message to deliver to add to the queue
severity	number	A number from 1-3 corresponding to the severity of the message. 1 -> 'Error Messages', 2 -> 'Warning Messages', 3 -> 'Suggestion Messages'

####flush

#####Use as: flush()

Return - and empty - the current AngularHintLog queue.

####Example

var hintLog = require('angular-hint-log');

hintLog.logMessage('##Controllers## The best practice is to name controllers with "Controller"');
//Assigns the queue to 'log'
var log = hintLog.flush();
//Assigns 'The best practice is to name controllers with "Controller"' to 'message1'
var message1 = Object.keys(log['Controllers']);
//Assigns an empty object as the queue is now empty
var empty = hintLog.flush();

####Returns

Type	Description
Object	An Object with keys representing names of modules identified by ## syntax. Each module name is keyed to an object representing that module's messages. Messages not logged with the ## name syntax are keyed to General.

####onMessage

#####Use as: onMessage = function(message) {};

Set a behavior to be done when each message is logged. This is an optional step to allow custom behavior when messages are logged. It does not affect the behavior of logMessage or flush.

####Example

var hintLog = require('angular-hint-log');

hintLog.onMessage = function(message) {
  throw new Error(message);
}

//Throws the error '##Controllers## The best practice is to name controllers with "Controller"'
hintLog.logMessage('##Controllers## The best practice is to name controllers with "Controller"');

##Building Angular Hint Log

The following instructions describe how to include the AngularHintLog dependency in the working directory of an AngularHint module.

1. Working in the module's main directory, install the necessary npm packages:

npm install angular-hint-log browserify gulp vinyl-source-stream --save

1. Create a gulpfile.js file to give instructions to gulp to build the module:

//gulpfile.js

var gulp = require('gulp');
var source = require('vinyl-source-stream');
var browserify = require('browserify');

var main = require('./package.json').main;

gulp.task('watch', function(){
  gulp.watch(['./**/*.js', '!./dist/*.js'], ['browserify']);
});

gulp.task('browserify', function() {
  var bundleStream = browserify('./' + main).bundle().pipe(source(main));
  return bundleStream.pipe(gulp.dest('./dist'));
});

gulp.task('default', ['browserify']);

1. Add the AngularHintLog dependency to the module's files using require:

var hintLog = angular.hint = require('angular-hint-log');

In the build step, browserify interprets the require command to load the functionality of AngularHintLog into the hintLog variable. Creating angular.hint allows use of var hintLog = angular.hint in unit testing.

1. Since the module is now built by gulp using browserify, it must be built before use and testing. For unit testing with karma, install the following package with npm:

npm install karma-bro --save

And update the karma.conf.js to pre-process the files:

  //karma.conf.js
  frameworks: ['browserify', 'jasmine'],
  preprocessors: {
      'your-module-file.js': ['browserify']
  }

Alternatively, use the gulp command to build the files. Built files will be located in the \dist directory.

1. AngularHintLog is ready to log messages!

hintLog.logMessage('ModuleName', 'Error message', 1);

This call adds a message to the AngularHintLog queue.

License

Copyright 2014 Google, Inc. http://angularjs.org

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.