grunt-pepper

... a little tool that parses my coffee-script files before they get translated to javascript.

It replaces log function calls with alternative calls that receive an info object as its first argument.

The info object contains the file-path and line-number as well as class-, method- and agrument-names of the place where the log occurred.

For example, in a file ./drink/some.coffee ...

class Hello
 
  sayHello: =>
    # ... it would replace the following log: 
    log "hello", "world!"
 
    # ... with this one: 
    log {file: 'drink/some.coffee', line: 5, class: 'Hello', method: 'sayHello'},
        "hello", "world"

It can also replace special markers with values from a json file:

# ... the following: 
 
@version = '::package.json:version::'
 
# ... gets replaced by: 
 
@version = '1.2.3'

Installation

npm install grunt-pepper --save-dev

Gruntfile.coffee

module.exports = (grunt) ->
 
  grunt.initConfig
 
    pepper:
      options:
        dryrun:   false      # if true, no files are written, 
                             # just prints what would be done 
        verbose:  false      # if true, the parse result is printed to stdout 
        quiet:    false      # if true, almost no information is printed 
        join:     true       # if true, files are joined into one target file 
        outdir:   '.pepper'  # directory where the parse results are written to 
        type:     '.coffee'  # suffix of the parse result files 
        template: '::'       # replaces ::file.json:key:: with value of 
                             # property key from object in file.json 
                             # set to false to disable templating 
                             
        pepper: ['console.log']
        
                # function calls that get peppered 
                # 
                # if specified as a map: 
                #       key:   original function name that gets replaced 
                #       value: replacement function that gets called instead 
                # 
                # if specified as a list: 
                #       preserves the original function names 
                # 
                #  the replacement function receives one additional 1st argument: 
                #       an object with keys: file, line, method, type, args 
                
        paprika: ['dbg']
        
                # names of functions that get paprikaed :-) 
                # 
                # same as pepper, but variable arguments get 
                #                 prefixed with their names: 
                #   
                # dbg foo, bar 
                #  
                # gets replaced with 
                # 
                # dbg {...pepper...}, 'foo:', foo, 'bar:', bar 
 
        paprikaPrefix:  ''
        paprikaPostfix: ':'
                
    task:
      files:
        'spiced': [ file(s) ] # will parse all file(s) and write the result 
                              # to file '.pepper/spiced.coffee' if join is true 
                              # if join is false, the original file structure  
                              # will be replicated in outdir 
 
  grunt.loadNpmTasks 'grunt-pepper'

Have a look at the Gruntfile of my other pet project if you need another example.

... and salt ...

In addition to the pepper task, there is another task which is called salt.

It can add an ascii header to files which start with an empty block comment.

For example, in a file salt.coffee it would replace ...

###
###

... with the following header:

###
 
 0000000   0000000   000      000000000
000       000   000  000         000   
0000000   000000000  000         000   
     000  000   000  000         000   
0000000   000   000  0000000     000   
 
###

I think these headers give me a nicer looking minimap:

Gruntfile.coffee

    salt:
        options:
            dryrun:        false
            quiet:         false
            verbose:       true
        headers:
            options:
                headerStart : "###" # filename will be put between this ... 
                headerEnd   : "###" # ... and this marker                 
                refresh     : false # if true, it will replace all ascii headers,  
                                    # false: only empty block comments are filled 
            files:
                'asciiHeader': ['./coffee/**/*.coffee']
                
        # 'asciiText' mode replaces special comments with ascii art text  
        #                  anywhere in the specified files: 
 
        coffee: 
            textMarker  : "#!!" #   text following this comment will be transformed 
            textPrefix  : "###" #   this is put before the replacing lines 
            textFill    : ""    #   each replacing line starts with these characters 
            textPostfix : "###" #   this is put after the replacing lines 
            files:
                'asciiText': ['./coffee/**/*.coffee']
 
        # this is what I use to generate text in my stylus files: 
        
        style:
            options:
            textMarker  : "//!!" #   text following this comment will be transformed 
            textPrefix  : "/*"
            textFill    : "* "  
            textPostfix : "*/"  
            files:
                'asciiText': ['./style/*.styl']

This stuff works for me, but I won't guarantee that it works for you as well. Therefore: don't forget to backup your files before you try it out! use at your own risk!

npm grunt