plugin-loader 0.0.1

data/lib/plugin/format/command.rb

@@ -0,0 +1,35 @@
+#       command.rb
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+#
+#The command format takes '$' to be a command, executes it, and
+#returns an array of lines of standard output.
+#	{
+#		"format" => "command",
+#		"$" => "COMMAND"
+#	}
+require 'plugin/format'
+
+#Depends: libescape-ruby
+require 'escape'
+
+Plugin::Format.add 'command' do |exec, args, opts|
+	IO.popen Escape.shell_command([exec.to_s, *args]).to_s do |handle|
+		return handle.read.split("\n")
+	end
+end

data/lib/plugin/format/data.rb

@@ -0,0 +1,32 @@
+#       data.rb
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+#
+#data is a very simple plugin format that just returns the data structure
+#referred to by the '$' key in the plugin metadata file:
+#	{
+#		"format" : "data",
+#		"$" : ...
+#	}
+#The data can be any type supported by JSON, including number, string, array,
+#hash(object) and boolean.
+require 'plugin/format'
+
+Plugin::Format.add 'data' do |exec, args, opts|
+	exec
+end

data/lib/plugin/format/dbus.rb

@@ -0,0 +1,67 @@
+#       dbus.rb
+#       
+#       Defines a plugin format that works by connecting to a dbus service.
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+#
+#
+#A plugin in dbus format has a general metadata file format of:
+#	{
+#		'format' : 'dbus',
+#		'$' : [service, object, interface, method]
+#	}
+#For example:
+#	{
+#		"format" : "dbus",
+#		"$" : [
+#			"org.gnome.Rhythmbox",
+#			"/org/gnome/Rhythmbox/Player",
+#			"org.gnome.Rhythmbox.Player",
+#			"getPlayingUri"
+#		]
+#	}
+#describes a plugin that gets the current playing song in Rhythmbox.
+#
+#The dbus format uses the dbus session bus.
+#It only works with dbus services that can be introspected (which is almost all of them).
+require 'plugin/format'
+
+#Depends: libdbus-ruby
+require 'dbus'
+
+module Plugin
+	
+	Format.add 'dbus' do |exec, args, opts|
+		service = exec[0]
+		object = exec[1]
+		iface = exec[2]
+		method = exec[3]
+
+		obj = DBus::SessionBus.
+			instance.
+			service(service).
+			object(object)
+			
+		obj.introspect
+			
+		obj[iface].
+			method(method).
+			call(*args)
+	end
+
+end

data/lib/plugin/format/ruby.rb

@@ -0,0 +1,48 @@
+#       ruby.rb
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+#
+#The ruby format allows plugins to be written in ruby.
+#The '$' key refers to the ruby file that should be loaded.
+#The metadata file has the following format:
+#	{
+#		"format" : "ruby",
+#		"$" : "ruby_lib"
+#	}
+#The ruby file should look something like:
+#	Plugin.new do |*args|
+#		#some code
+#	end
+require 'plugin/format'
+
+module Plugin
+
+	_ruby_plugin = lambda do |*args|
+		args
+	end
+	
+	def self.new &b
+		_ruby_plugin = b
+	end
+
+	Format.add 'ruby' do |exec, args, opts|
+		load exec
+		_ruby_plugin.call *args
+	end
+
+end

data/lib/plugin/format/script.rb

@@ -0,0 +1,35 @@
+#       script.rb
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+#
+#The script format takes '$' to be an executable in the @script_dir folder.
+#The script is executed and an array of lines of standard output is returned.
+#	{
+#		"format" => "command",
+#		"$" => "COMMAND"
+#	}
+require 'plugin/format'
+
+#Depends: libescape-ruby
+require 'escape'
+
+Plugin::Format.add 'script' do |exec, args, opts|
+	IO.popen Escape.shell_command(["#{opts[:dir] || '/usr/bin'}/#{exec}", *args]).to_s do |handle|
+		return handle.read.split("\n")
+	end
+end

data/lib/plugin/format.rb

@@ -0,0 +1,68 @@
+#       format.rb
+#       
+#       Defines a class allowing new plugin formats to be added.
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+
+
+module Plugin
+
+	#An instance of this class represents a plugin format.
+	class Format
+		@@formats = {}
+		#To create a new annonymous plugin format:
+		#	Plugin::Format.new do |exec, args, opts|
+		#		...
+		#		return return_data
+		#	end
+		#Argument 'exec' provides the data in the '$' key of the plugin metadata file.
+		#Argument 'args' is an array of arguments passed to this format by a Plugin::Loader instance when its run method is called.
+		#Argument 'opts' is a hash of options from Plugin::Loader that may be required by a plugin format. At present opts conatins the following keys:
+		#	:plugin_dir
+		#	:data_dir
+		#	:script_dir
+		#These are the same as the options given when the Plugin::Loader was initialized.
+		#
+		#Plugin::Format.add should be used to create a new plugin format because the format is given a name. 
+		def initialize &b
+			@block = b
+		end
+		#Creates a lambda function from the exec value and opts hash.
+		#When the lambda function is called, its arguments become 'args' and
+		#the block given at initialize is executed.
+		def new exec, opts={}
+			lambda do |*args|
+				@block.call exec, args, opts
+			end
+		end
+		#Creates a named plugin format using the same rules as Plugin::Format.new:
+		#	Plugin::Format.add "name" do |exec, args, opts|
+		#		...
+		#		return return_data
+		#	end
+		def self.add name, &b
+			@@formats[name] = self.new &b
+		end
+		#Returns the format called 'name':
+		#	Plugin::Format['name']
+		def self.[] name
+			@@formats[name]
+		end
+	end
+
+end

data/lib/plugin/loader.rb

@@ -0,0 +1,130 @@
+#       loader.rb
+#       
+#       Provides a class for loading plugins into a program.
+#       
+#       Copyright 2010 David Green <david4dev@gmail.com>
+#       
+#       This program is free software; you can redistribute it and/or modify
+#       it under the terms of the GNU General Public License as published by
+#       the Free Software Foundation; either version 3 of the License, or
+#       (at your option) any later version.
+#       
+#       This program is distributed in the hope that it will be useful,
+#       but WITHOUT ANY WARRANTY; without even the implied warranty of
+#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#       GNU General Public License for more details.
+#       
+#       You should have received a copy of the GNU General Public License
+#       along with this program; if not, write to the Free Software
+#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#       MA 02110-1301, USA.
+require 'plugin/format'
+
+#Depends: libjson-ruby
+require 'json'
+
+module Plugin
+
+	#Using an instance of this class, you can control what plugins are
+	#loaded into your program.
+	class Loader
+		#OPTIONS:
+		#
+		#	:allowed_formats => [...] #optional; default is an array of all available plugin formats
+		#- Defines an array of names (strings) of formats that plugins for this instance can be written in.
+		#
+		#	:data_dir => '/usr/share/appname' #required
+		#- Defines the directory in which the data for this instance is stored in the file system.
+		#
+		#	:plugin_dir => '' #optional; default is "#{@data_dir}/plugins"
+		#- Defines the directory in which the plugin metadata files are stored
+		#
+		#	:script_dir => '' #optional; default is "#{@data_dir}/scripts"
+		#- Defines the directory in which excecutables (potentially used by plugins) are stored.
+		def initialize opts={}
+			@available_formats = $:.map do |path|
+				Dir.glob("#{path}/plugin/format/*.rb").map! do |rbfile|
+					File.basename(rbfile).sub!(/\.rb$/, '')
+				end
+			end
+			@available_formats.flatten!
+			@allowed_formats = opts[:allowed_formats] ? (opts[:allowed_formats] & available_formats) : available_formats
+			@allowed_formats.each do |fmt|
+				require "plugin/format/#{fmt}"
+			end
+			@data_dir = opts[:data_dir]
+			@plugin_dir = opts[:plugin_dir] || "#{@data_dir}/plugins"
+			@script_dir = opts[:script_dir] || "#{@data_dir}/scripts"
+			@plugins = {}
+		end
+		#Loads a plugin called 'name' of type 'type'.
+		#It does this by reading the metadata file: "#{@plugin_dir}/name.type".
+		#Plugin types should be considered namespaces for one or more plugins.
+		#Plugin names are the unique identification of a plugin within a particular type.
+		#Plugins are similar to functions - they are excecuted with arguments a value (which can be a complex data structure such as hash or array if needed).
+		#load does not excecute a plugin but it once loaded
+		#a plugin can be excecuted with the run method.
+		#
+		#The metadata files are in a JSON format:
+		#	{
+		#		"format" => "FORMAT_NAME",
+		#		"$" => ...
+		#	}
+		#The 'format' key is a string that defines the name of the format of the plugin. If load loads a plugin without the 'format' key, an exception is raised.
+		#If the format is not available or is not allowed (see: initailize), an exception is raised.
+		#See Plugin::Format for more details on plugin formats.
+		#The '$' key can be any data structure (most commonly a string) and is used by the format declaration to excecute a plugin. See the individual format declarations in plugin/format/*.rb for details of individual formats. If the '$' key is missing, an exception is raised.
+		def load name, type
+			File.open "#{@plugin_dir}/#{name}.#{type}" do |f|
+				data = JSON.parse(f.read)
+				unless data.has_key? '$'
+					raise "Plugin #{type} plugin '#{name}' has an invalid metadata file. It is missing the required '$' key!"
+				end
+				unless data.has_key? 'format'
+					raise "Plugin #{type} plugin '#{name}' has an invalid metadata file. It is missing the required 'format' key!"
+				end
+				unless @plugins.has_key? type
+					@plugins[type] = {}
+				end
+				format = Format[data['format']]
+				if format.nil?
+					raise "Plugin format #{data['format']} does not exist or is disabled!"
+				end
+				@plugins[type][name] = format.new data['$'],
+					:script_dir => @script_dir,
+					:data_dir => @data_dir,
+					:plugin_dir => @plugin_dir
+			end
+		end
+		#Unloads a plugin of name 'name' and type 'type'.
+		def unload name, type
+			@plugins[type].delete name
+		end
+		#Loads all plugins of type 'type'.
+		def load_type type
+			Dir.glob("#{@plugin_dir}/*.#{type}").each do |file|
+				self.load file
+			end
+		end
+		#Unloads all plugins of type 'type'.
+		def unload_type type
+			@plugins.delete type
+		end
+		#Loads all plugins.
+		def load_all
+			Dir.glob("#{@plugin_dir}/*").each do |file|
+				self.load file
+			end
+		end
+		#Unloads all plugins.
+		def unload_all
+			@plugins.clear
+		end
+		#Excecutes the plugin of type 'type' called 'name', passing in any other arguments.
+		#The return value of the plugin is returned.
+		def run name, type, *args
+			@plugins[type][name].call *args
+		end
+	end
+
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification 
+name: plugin-loader
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- David Green
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-25 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: dbus
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: escape
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: |-
+  plugin-loader can be used to extend a program written in ruby by using plugins. 
+  	Plugins can be written in ruby or can be external resources.
+email: david4dev@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/plugin/format/dbus.rb
+- lib/plugin/format/script.rb
+- lib/plugin/format/ruby.rb
+- lib/plugin/format/data.rb
+- lib/plugin/format/command.rb
+- lib/plugin/format.rb
+- lib/plugin/loader.rb
+has_rdoc: true
+homepage: https://launchpad.net/libplugin-loader-ruby
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.1
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Library for creating extensible ruby applications
+test_files: []
+