| Class | AutomateIt::Interpreter |
| In: |
lib/automateit/interpreter.rb
|
| Parent: | Common |
The Interpreter runs AutomateIt commands.
The TUTORIAL.txt file provides hands-on examples for using the Interpreter.
The Interpreter provides shortcut aliases for certain plugin commands.
For example, the following commands will run the same method:
shell_manager.sh "ls" sh "ls"
The full set of aliased methods:
The AutomateIt Interpreter can be embedded inside a Ruby program:
require 'rubygems'
require 'automateit'
interpreter = AutomateIt.new
# Use the interpreter as an object:
interpreter.sh "ls -la"
# Have it execute a recipe:
interpreter.invoke "myrecipe.rb"
# Or execute recipes within a block
interpreter.instance_eval do
puts superuser?
sh "ls -la"
end
See the include_in and add_method_missing_to methods for instructions on how to more easily dispatch commands from your program to the Interpreter instance.
| friendly_exceptions | [RW] |
The Interpreter throws friendly error
messages by default that make it easier to see what‘s wrong with a
recipe. These friendly messages display the cause, a snapshot of the
problematic code, shortened paths, and only the relevant stack frames.
However, if there‘s a bug in the AutomateIt internals, these friendly messages may inadvertently hide the cause, and it may be necessary to turn them off to figure out what‘s wrong. To turn off friendly exceptions: # From a recipe or the AutomateIt interactive shell: self.friendly_exceptions = false # For an embedded interpreter at instantiation: AutomateIt.new(:friendly_exceptions => false) # From the UNIX command line when invoking a recipe: automateit --trace myrecipe.rb |
| irb | [RW] | Access IRB instance from an interactive shell. |
| log | [W] | Set the QueuedLogger instance for the Interpreter. |
| params | [RW] | Hash of parameters to make available to the Interpreter. Mostly useful when needing to pass arguments to an embedded Interpreter before doing an instance_eval. |
| plugins | [RW] | Hash of plugin tokens to plugin instances for this Interpreter. |
| project | [RW] | Project path for this Interpreter. If no path is available, nil. |
Create an Interpreter with the specified opts and invoke the recipe. The opts are passed to setup for parsing.
Creates method_missing in object that dispatches calls to an Interpreter instance. If a method_missing is already present, it will be preserved as a fall-back using alias_method_chain.
For example, add method_missing to a Rake session to provide direct access to Interpreter instance‘s methods whose names don‘t conflict with the names existing variables and methods:
# Rakefile
require 'automateit'
@ai = AutomateIt.new
@ai.add_method_missing_to(self)
task :default do
puts preview? # Uses Interpreter#preview?
sh "id" # Uses FileUtils#sh, not Interpreter#sh
end
For situations where it‘s necessary to override existing methods, such as the sh call in the example, consider using include_in.
Path of this project‘s "dist" directory. If a project isn‘t available or the directory doesn‘t exist, this will throw a NotImplementedError.
Creates wrapper methods in object to dispatch calls to an Interpreter instance.
WARNING: This will overwrite all methods and variables in the target object that have the same names as the Interpreter‘s methods. You should considerer specifying the methods to limit the number of methods included to minimize surprises due to collisions. If methods is left blank, will create wrappers for all Interpreter methods.
For example, include an Interpreter instance into a Rake session, which will override the FileUtils commands with AutomateIt equivalents:
# Rakefile
require 'automateit'
@ai = AutomateIt.new
@ai.include_in(self, %w(preview? sh)) # Include #preview? and #sh methods
task :default do
puts preview? # Uses Interpreter#preview?
sh "id" # Uses Interpreter#sh, not FileUtils#sh
cp "foo", "bar" # Uses FileUtils#cp, not Interpreter#cp
end
For situations where you don‘t want to override any existing methods, consider using add_method_missing_to.
Invoke the recipe. The recipe may be expressed as a relative or fully qualified path. When invoked within a project, the recipe can also be the name of a recipe.
Example:
invoke "/tmp/recipe.rb" # Run "/tmp/recipe.rb"
invoke "recipe.rb" # Run "./recipe.rb". If not found and in a
# project, will try running "recipes/recipe.rb"
invoke "recipe" # Run "recipes/recipe.rb" in a project
Get or set the QueuedLogger instance for the Interpreter, a special wrapper around the Ruby Logger.
Set preview mode to value. See warnings in ShellManager to learn how to correctly write code for preview mode.
Preview a block of custom commands. When in preview mode, displays the message but doesn‘t execute the block. When not previewing, will execute the block and not display the message.
For example:
preview_for("FOO") do
puts "BAR"
end
In preview mode, this displays:
=> FOO
When not previewing, displays:
BAR
Set value to share throughout the Interpreter. Use this instead of globals so that different Interpreters don‘t see each other‘s variables. Creates a method that returns the value and also adds a params entry.
Example:
set :asdf, 9 # => 9 asdf # => 9
This is best used for frequently-used variables, like paths. For infrequently-used variables, use lookup and params. A good place to use the set is in the Project‘s config/automateit_env.rb file so that paths are exposed to all recipes like this:
set :helpers, project+"/helpers"
Setup the Interpreter. This method is also called from Interpreter#new.
Options for users:
Options for internal use: