Runnables

How Runnables work

Teaching Redcar about every build system in existence would take a long time. Instead, Redcar can read simple json definitions of tasks, build targets and commands. In this way, Redcar can execute any command that can be executed in a console, excluding commands that require continuous input (coming soon!).

The syntax of the command schemas looks like this:

{
  "commands":[
    {
      "name":        "gem",
      "command":     "/Users/danlucraft/Programs/jruby/bin/rake gem",
      "description": "Build the gem file redcar-0.3.8dev.gem",
      "type":        "task/ruby/rake",
      "output":      "none"
    },
    {
      "name":        "redcar/runnables",
      "command":     "/Users/danlucraft/Programs/jruby/bin/rake redcar:runnables",
      "description": "Redcar Integration: output runnable info",
      "type":        "task/ruby/rake"
    }
  ],
  "file_runners":[
    {
      "regex":   ".*_spec.rb",
      "name":    "Run as spec",
      "command": "jruby -J-XstartOnFirstThread spec __PATH__",
      "type":    "test/ruby/spec"
    },
    {
      "regex":   ".*.feature",
      "name":    "Run as feature",
      "command": "cucumber __PATH__",
      "type":    "test/ruby/feature"
    },
    {
      "regex":   ".*.feature",
      "name":    "Run as feature",
      "command": "cucumber __PATH__:__LINE__",
      "type":    "test/ruby/feature"
    },
    {
      "regex":   ".*.rb",
      "name":    "Run as ruby",
      "command": "ruby __PATH__",
      "type":    "script/ruby"
    }
  ]
}

Notes:

• output can be one of "tab" (default – opens in a new tab), "none", or "window"

Commands

Commands are predefined command line commands that Redcar will run in the default OS shell.

If you want to teach Redcar about your languages task or build system, you should write a program to emit json like this and put it into your-project-root/.redcar/runnables/whatever.json.

File Runners

File runners are mappings between file name types and command schemas, that allow you to tell Redcar to “Run a tab” and it will find the first matching file runner and execute based on it. To run the second matching file runner, use the “Alternate Run Tab” command. Two commands for running cucumber features are illustrated above

Parameters

Runnables has a predefined variable for modifying command output:

__PARAMS__ : displays a prompt for the user to input text at the current position in a command.

Similarly, file runners can use the Runnables parameter, as well as variables specific to running files:

__PATH__ : replaced with the file path in the command
__NAME__ : replaced by the name of the current file in the command
__LINE__ : replaced by the cursor line number in the current file

Custom Commands

Arbitrary commands can be executed as a Runnable by choosing “Custom Command” from the Runnables tree.

Example Usage: How to run rake tasks in Redcar

In order to run rake tasks in Redcar you have to generate the appropriate runnables json for the rake tasks.

Copy this rake task into your project’s Rakefile (which should be in the root of your project’s tree) and run rake redcar:runnables. This should generate .redcar/runnables/*.json and then your rake tasks will appear in the Runnables tree of your project.

You will need to close the Runnables tree and reopen it for Redcar to pick up the changes.

namespace :redcar do
  def hash_with_hash_default
    Hash.new {|h,k| h[k] = hash_with_hash_default }
  end

  require 'json'

  desc "Redcar Integration: output runnable info"
  task :runnables do
    mkdir_p(".redcar/runnables")
    File.open(".redcar/runnables/sync_stdout.rb", "w") do |fout|
      fout.puts <<-RUBY
        $stdout.sync = true
        $stderr.sync = true
      RUBY
    end

    tasks = Rake::Task.tasks
    runnables = []
    ruby_bin = Config::CONFIG["bindir"] + "/ruby -r#{File.dirname(__FILE__)}/.redcar/runnables/sync_stdout.rb "
    tasks.each do |task|
      name = task.name.gsub(":", "/")
      command = ruby_bin + $0 + " " + task.name
      runnables << {
        "name"        => name,
        "command"     => command,
        "description" => task.comment,
        "type"        => "task/ruby/rake"
      }
    end
    File.open(".redcar/runnables/rake.json", "w") do |f|
      data = {"commands" => runnables}
      f.puts(JSON.pretty_generate(data))
    end
    File.open(".redcar/runnables/ruby.json", "w") do |f|
      data = {"file_runners" =>
        [
          {
            "regex" =>    ".*.rb$",
            "name" =>     "Run as ruby",
            "command" =>  ruby_bin + "__PATH__",
            "type" =>     "script/ruby"
          }
        ]
      }
      f.puts(JSON.pretty_generate(data))
    end
  end
end

Links

• Blog Using Runnables in the Redcar Editor (8/2010) – an example of creating custom task and file runnables (hint: add a .json file to .redcar/runnables/)

‹‹ Back to User's Guide