stdouttoggler

= Standard Out Toggler

Standard Out Toggler is an executable gem that comments and uncomments output lines from a variety of different file types. Out of the box, this gem handles java, javascript (in .js and .jsp files), ruby, and perl files. You can configure it to handle any file type of your choice.

== Use Case

Sometimes when debugging, developers add output statements to code, for example alert statements to javascript or System.out.println statements to java. Then they discover need temporarily to comment out the statements from some files, because they're cluttering up the console or because they get tired of crawling through javascript alerts. Later, they may need to uncomment them again.

The Standard Out Toggler gem solves this problem by automatically commenting or uncommenting output lines from a command prompt.

== Running the program

Run the executable from a directory of your choice using the toggle command. The only required option is the instruction option (-i), which tells stdouttoggler whether to comment or uncomment output lines. Add one or more files as args (relative or absolute paths), and run the program. For example:

toggle -i comment JavaFile.java C:/programs/JavaScriptFile.js

== Command Line Options

-h:: Help screen. -i <comment|uncomment>:: Tells stdouttoggler whether to comment or uncomment output lines. -b:: Saves a backup of any changed file. -f:: Tells stdouttoggler to find files for commenting or uncommenting in a file called file_names.yaml, which you put in the current directory. This can come in handy if you're changing a lot of files or using files with long paths. Note that if you use this option, you cannot put any files on the command line. -c:: Tells stdouttoggler that you're adding additional file types, using a file called additional_types.yaml in the current directory.

Here are some sample commands:

toggle -i comment JavaFile.java C:/programs/JavaScriptFile.js

• Comments out all System.out.print and System.out.println statements in the java file, and all the alert statements in the javascript file.

toggle -i uncomment JavaFile.java C:/programs/JavaScriptFile.js

• Uncomments all System.out.print and System.out.println statements in the java file, and all the alert statements in the javascript file.

toggle -i comment -b JavaFile.java

• Comments out all System.out.print and System.out.println statements in the java file and saves a backup (JavaFile.java.bak) of the original file.

toggle -i comment -f

• Comments out all output statements in the file_names.yaml file in your current directory. See the Using a File section below for an explanation of the structure of that file.

toggle -i comment -c AnotherFileType.al

• Comments out all the output statements in AnotherFileType.al in your current directory, based on configuration instructions in additional_types.yaml in your current directory. See the Configuration section below for an explanation of the structure of the YAML configuration file.

toggle -i comment -f -c

• Comments out all output statements in the file_names.yaml file in your current directory, based on configuration instructions in additional_types.yaml in your current directory.

== Using a File Instead of Command Line Arguments

In the examples folder you'll find a sample YAML file called file_names.yaml that lists files to comment/uncomment. You can use that file as a template for adding your own files, using relative or absolute paths.

Activate this file using the -f option. Note that if you use this option, you cannot put any files as arguments on the command line.

== Configuration

In the examples folder you'll find a sample YAML configuration file called additional_types.yaml that lists three (imaginary) additional languages for commenting/uncommenting. You can use this file as a template for types you wish to add.

The comment_string_escaped is the tricky one. It will be used in a regular expression, so if it contains metacharacters, they need to be escaped. Additionally, if any of the values use a character that means something special to the ruby interpreter, such as the hash sign, it must be put in quotation marks.

Activate this file using the -c option.