I noticed a search engine referral that asked “How to use Yasca”. Maybe it seems obvious to me only because I’ve been using it for over a year. Here are some examples of what you’ll probably want to do with it:

Scenario #1 - Simple PHP Project
Suppose you have a PHP project with source code in c:\work\myproject\src\. You could run:
yasca c:\work\myproject\src
The output is placed in a folder called Yasca on your desktop.

Alternatively, since you know you don’t have any Java, C, or C++ files there, you can exclude certain plugins that definitely won’t find anything to scan. (This is optional; if you ignore this, execution time will just take a few seconds longer.)
yasca -px FindBugs,Antic,JLint,PMD c:\work\myproject\src

Scenario #2 - Java Project, Output To File Share
Suppose you have a Java project in c:\work\myproject, but you want the output from Yasca to go to a file share (Z:\Yasca_Output). You could run:
yasca -o z:\Yasca_Output c:\work\myproject

Scenario #3 - Only See Critical Issues
You can “turn up the dial” and view only critical issues by using the –level parameter:
yasca --level 1 c:\work\myproject

These are some typical uses. Please leave a comment if you’d like examples of any others.

Share/Save

So you’ve downloaded and installed Yasca, and like the results, but you want it to write your own plugin. This tutorial will show you how easy it is to do.

First, you should understand how Yasca is designed. Yasca is basically a file scanning engine with the ability to run plug-ins that find interesting things in those files and report the results back to the engine for inclusion into the report. Everything that goes into a report comes from a plugin. (Yasca can do nothing without them.)

Yasca comes with a number of plug-ins by default, including FindBugs, PMD, Jlint, and Grep. The first three are external tools that are maintained by others, but included because I think they provide great information. I wrote the Grep plugin to make it easy to create simple rules that only require regular expression matching. In the first part of this tutorial, we’ll create a new Grep plugin to search for something interesting.

Writing a New Grep Plugin

Writing a Grep plug-in requires you to have a few pieces of information (and a few more optional pieces):

• the regular expression to search for, and
• the category (single-line description) of the plug-in

Let’s pretend you want to search for social security numbers within a code base. Create a new file called SocialSecurityNumber.grep. The base name of the file is not important, but the extension (.grep) is. The Grep plugin actually scans for .grep files in the plug-in directory and uses each of them. Here’s the contents of SocialSecurityNumber.grep:

category = Social Security Number Found
grep = /\d{3}-\d{2}-\d{4}/

Additional parameters are also available, including:

• file_type - a comma-separated list of file extensions to apply this plug-in to
• category_link - a URL containing more information about this particular plug-in
• severity - the severity (1=critical down to 5=informative)
• description - a multi-line description of the plug-in, ending with a line containing only the string “END;”

For example, consider the a slightly modified version of the Formatting.MissingAMPM.grep pluigin:

name = Missing AM or PM in Time Format
file_type = java,jsp
grep = /hh:mm:ss\"/
category = Formatting: Missing AM/PM in Time Format
severity = 2
description =
  <p>
        When specifying time formatting in Java, the phrase "hh:mm:ss" is based on 12-hour time, so 5:00 AM and 5:00
        PM would both be rendered as "05:00:00", possibly confusing the user. Instead, use either "HH:mm:ss", which
        is based on 24-hour time, or include either AM or PM by using "hh:mm:ss a".
  </p>
  <p>
    <h4>References</h4>
     <ul>
       <li>TODO</li>
    </ul>
  </p>
END;

You can also specify multiple grep patterns, which are logically ‘ORed’ during evaluation.

Place the file you created in the plugins directory and start Yasca. The Grep plugin will automatically find all .grep files within the plugins directory and use them.

In our next tutorial, you’ll learn how to write more complex plugins.

Share/Save