launchdr 3

data/.manifest

@@ -0,0 +1,7 @@
+lib/launchdr/launchd.rb
+lib/launchdr/property_list.rb
+lib/launchdr/task.rb
+lib/launchdr.rb
+Rakefile.rb
+README.markdown
+.manifest

data/README.markdown

@@ -0,0 +1,66 @@
+LaunchDoctor
+============
+I've got a PhD in [launchd][], and I'm not afraid to use it!
+
+  [launchd]: <http://en.wikipedia.org/wiki/Launchd> "launchd on Wikipedia"
+
+Usage
+-----
+LaunchDoctor is really simple. It is essentially an easy interface to
+[launchd][]'s [property list][plist] files.
+
+There are three ways to use LaunchDoctor - the simplest being directly
+creating property lists and treating them as hashes:
+    
+    require 'launchdr'
+    plist = LaunchDr::Launchd.new "name.elliottcable.launchdr.test"
+    plist[:program_arguments] = ['/Applications/Calculator.app/Contents/MacOS/Calculator']
+    plist.dump LaunchDr::Launchd::Paths[:user_agent]
+    
+The second is to use the common block idiom, provided by the `LaunchDr()`
+method:
+    
+    require 'launchdr'
+    LaunchDr "name.elliottcable.launchdr.test" do |plist|
+      plist[:program_arguments] = ['/Applications/Calculator.app/Contents/MacOS/Calculator']
+    end
+    
+LaunchDoctor will automatically add the property list to `launchctl`, and then
+start it running. Once you run the above snippet, the target will immediately
+be launched for the first time.
+
+LaunchDoctor can write (`dump`) the property lists to any place on your disk,
+but the idiom method assumes you're going to want to use one of the
+directories that launchd checks for property lists. These are stored in the
+`Launchd::Paths` array. The default is to place it in the user-owned agents
+directory at `~/Library/LaunchAgents`.
+
+LaunchDoctor also preforms some 'prettification' on the keys provided by
+launchd's property list structure. All of the keys on the
+[`launchd.plist` manpage][manpage] are available, but they can also be used as
+true 'Ruby-ish' symbol keys. All of the following are legal:
+    
+    plist["UserName"] = "elliottcable"
+    plist[:UserName] = "elliottcable"
+    plist[:user_name] = "elliottcable"
+    
+Finally, you can use the Rake task interface to the last method. It simply
+wraps the last method inside a rake task. This method is really great if you
+want to provide a way to let users make your gem's binary run all the time:
+    
+    require 'launchdr/task'
+    LaunchDr::Task.new :launchd, :bin => 'jello', :arguments => ['-D', 'shortener', 'grabup']
+    
+This isn't very flexible, but it's not very complicated either. If you need
+more control over the plist, just use the second method inside a `task` block.
+This method defaults to making your gem's binary `run_at_load` and be
+`keep_alive` as well, so it won't die.
+
+  [plist]: <http://en.wikipedia.org/wiki/Property_list> "Property list on Wikipedia"
+  [manpage]: <http://developer.apple.com/DOCUMENTATION/DARWIN/Reference/ManPages/man5/launchd.plist.5.html> "Mac OS X Manual Page for launchd.plist(5)"
+  [rake]: <http://rake.rubyforge.org/> "Rake's RDocs"
+
+Requirements
+------------
+- Plist - `gem install plist`
+- Ruby Facets - `gem install facets`

data/Rakefile.rb

@@ -0,0 +1,40 @@
+($:.unshift File.expand_path(File.join( File.dirname(__FILE__), 'lib' ))).uniq!
+require 'launchdr'
+
+# =======================
+# = Gem packaging tasks =
+# =======================
+begin
+  require 'echoe'
+  
+  task :package => :'package:package'
+  task :install => :'package:install'
+  task :manifest => :'package:manifest'
+  task :clobber => :'package:clobber'
+  namespace :package do
+    Echoe.new('launchdr', LaunchDr::Version) do |g|
+      g.author = ['elliottcable']
+      g.email = ['launchdr@elliottcable.com']
+      g.summary = "One stop shop for launchd property list creation. The doctor is *in*!"
+      g.url = 'http://github.com/elliottcable/launchdr'
+      g.dependencies = ['plist', 'facets', 'uuid']
+      g.development_dependencies = ['echoe >= 3.0.2']
+      g.manifest_name = '.manifest' # I don't want this showing up <,<
+      g.retain_gemspec = true # perfect for GitHub
+      g.rakefile_name = 'Rakefile.rb' # It's a Ruby file, why not have .rb?
+      g.ignore_pattern = /^\.git\/|\.gemspec/
+    end
+  
+    desc 'tests packaged files to ensure they are all present'
+    task :verify => :package do
+      # An error message will be displayed if files are missing
+      if system %(ruby -e "require 'rubygems'; require 'pkg/launchdr-#{LaunchDr::Version}/lib/launchdr'")
+        puts "\nThe library files are present"
+      end
+    end
+  end
+  
+rescue LoadError
+  desc 'You need the `echoe` gem to package LaunchDr'
+  task :package
+end

data/launchdr.gemspec

@@ -0,0 +1,43 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{launchdr}
+  s.version = "3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["elliottcable"]
+  s.date = %q{2009-02-11}
+  s.description = %q{One stop shop for launchd property list creation. The doctor is *in*!}
+  s.email = ["launchdr@elliottcable.com"]
+  s.extra_rdoc_files = ["lib/launchdr/launchd.rb", "lib/launchdr/property_list.rb", "lib/launchdr/task.rb", "lib/launchdr.rb", "README.markdown"]
+  s.files = ["lib/launchdr/launchd.rb", "lib/launchdr/property_list.rb", "lib/launchdr/task.rb", "lib/launchdr.rb", "Rakefile.rb", "README.markdown", ".manifest", "launchdr.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/elliottcable/launchdr}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Launchdr", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{launchdr}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{One stop shop for launchd property list creation. The doctor is *in*!}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<plist>, [">= 0"])
+      s.add_runtime_dependency(%q<facets>, [">= 0"])
+      s.add_runtime_dependency(%q<uuid>, [">= 0"])
+      s.add_development_dependency(%q<echoe>, [">= 0", "= 3.0.2"])
+    else
+      s.add_dependency(%q<plist>, [">= 0"])
+      s.add_dependency(%q<facets>, [">= 0"])
+      s.add_dependency(%q<uuid>, [">= 0"])
+      s.add_dependency(%q<echoe>, [">= 0", "= 3.0.2"])
+    end
+  else
+    s.add_dependency(%q<plist>, [">= 0"])
+    s.add_dependency(%q<facets>, [">= 0"])
+    s.add_dependency(%q<uuid>, [">= 0"])
+    s.add_dependency(%q<echoe>, [">= 0", "= 3.0.2"])
+  end
+end

data/lib/launchdr.rb

@@ -0,0 +1,36 @@
+require 'launchdr/property_list'
+require 'launchdr/launchd'
+
+
+def LaunchDr label, opts = {}
+  LaunchDr.create label, opts, &Proc.new
+end
+module LaunchDr
+  Version = 3
+  Options = Hash.new
+  
+  def self.create label, opts = {}
+    plist = Launchd.new label
+    
+    yield plist if block_given?
+    
+    raise "You must run as a root user and allow_system_agents! if you wish to preform the dangerous act of writing to #{Launchd::Paths[:system_agent]}!" unless !(opts[:type] == :system_agent) or Options[:system_agents_allowed]
+    raise "You must run as a root user, allow_system_agents!, *and* allow_system_daemons! if you wish to preform the very dangerous act of writing to #{Launchd::Paths[:system_daemon]}!" unless !(opts[:type] == :system_daemon) or Options[:system_daemon_allowed]
+    path = Launchd::Paths[opts[:type] || :user_agent]
+    raise "Type error! Must be one of #{Launchd::Paths.keys.join(", ")}" unless path
+    
+    plist.dump File.expand_path(path)
+    plist.load!
+  end
+  
+  def self.allow_system_agents!
+    Options[:system_agents_allowed] = true
+  end
+  
+  def self.allow_system_daemons!
+    raise "You must allow System-owned agents to allow System-owned daemons!" unless Options[:system_agents_allowed]
+    Options[:system_daemon_allowed] = true
+  end
+  
+  
+end

data/lib/launchdr/launchd.rb

@@ -0,0 +1,43 @@
+require 'facets/string'
+
+module LaunchDr
+  
+  class Launchd < PropertyList
+    Paths = {
+      :user_agent => "~/Library/LaunchAgents",
+      :agent => "/Library/LaunchAgents",
+      :daemon => "/Library/LaunchDaemons", 
+      :system_agent => "/System/Library/LaunchAgents",
+      :system_daemon => "/System/Library/LaunchDaemons"
+    }
+    
+    def [] key
+      super(key.to_s.titlecase.camelcase)
+    end
+    
+    def []= key, value
+      super(key.to_s.titlecase.camelcase, value)
+    end
+    
+    # Adds the property list to `launchctl`'s indexes, and starts it (unless
+    # disabled).
+    def load!
+      system "launchctl load #{file}"
+    end
+    
+    # Removes the propertly list from `launchctl`'s indexes.
+    def unload!
+      system "launchctl unload #{file}"
+    end
+    
+    # Finds the plist file, if it's been created
+    def file
+      Paths.values.each do |dir|
+        file = File.expand_path(File.join(dir, self[:label] + '.plist'))
+        return file if File.file? file
+      end
+      raise "#{self[:label]} doesn't exist in any of the default locations. Did you #dump it?"
+    end
+  end
+  
+end

data/lib/launchdr/property_list.rb

@@ -0,0 +1,38 @@
+require 'plist'
+require 'uuid'
+
+module LaunchDr
+  
+  class PropertyList
+    attr_reader :elements
+  
+    def initialize label = nil, elements = {}
+      @elements = elements
+      @elements['Label'] = label || "rb.launchdr.#{UUID.new.generate}"
+    end
+  
+    def [] key
+      @elements[key.to_s]
+    end
+  
+    def []= key, value
+      @elements[key] = value
+    end
+  
+    def to_plist
+      @elements.to_plist
+    end
+  
+    def dump path
+      out = File.new(File.expand_path(File.join(path, @elements['Label'] + '.plist')), 'w+')
+      out.puts Plist::Emit.dump @elements
+      out.close
+    end
+  
+    def self.load filename
+      elements = Plist::parse_xml File.new(File.expand_path filename, 'r')
+      new elements[:label], elements
+    end
+  end
+  
+end

data/lib/launchdr/task.rb

@@ -0,0 +1,33 @@
+require 'launchdr'
+
+module LaunchDr
+  
+  module Task
+    def self.new name = :launchd, opts = {}
+      raise "`LaunchDr.task`'s options must include the name of the binary for your gem!" unless opts[:bin]
+      opts = {:desc => 'Creates a launchd property list for this gem', :arguments => []}.merge opts
+
+      desc opts[:desc] unless opts[:no_desc]
+      task name do
+        path = File.expand_path File.join('', opts[:bin])
+        unless File.file? path
+          path = File.expand_path File.join(Gem::default_bindir, opts[:bin])
+          unless File.file? path
+            path = File.expand_path %x[which "#{opts[:bin]}"].chomp
+          end
+        end
+        unless File.file? path
+          raise "** Unable to locate binary #{opts[:bin]}"
+        end
+        LaunchDr "rb.launchdr.#{opts[:bin]}" do |plist|
+          plist[:program_arguments] = [path, opts[:arguments]].flatten
+          plist[:keep_alive] = true
+          plist[:run_at_load] = true
+        end
+        puts "** `#{[path, opts[:arguments]].flatten.join(' ')}` will now be run on startup!"
+      end
+
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification 
+name: launchdr
+version: !ruby/object:Gem::Version 
+  hash: -124656629444251359
+  prerelease: false
+  segments: 
+  - 3
+  version: "3"
+platform: ruby
+authors: 
+- elliottcable
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-11 00:00:00 -09:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: plist
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 134023568094289244
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: facets
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 134023568094289244
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: uuid
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 134023568094289244
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: echoe
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 134023568094289244
+        segments: 
+        - 0
+        version: "0"
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 1556383981505405372
+        segments: 
+        - 3
+        - 0
+        - 2
+        version: 3.0.2
+  type: :development
+  version_requirements: *id004
+description: One stop shop for launchd property list creation. The doctor is *in*!
+email: 
+- launchdr@elliottcable.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- lib/launchdr/launchd.rb
+- lib/launchdr/property_list.rb
+- lib/launchdr/task.rb
+- lib/launchdr.rb
+- README.markdown
+files: 
+- lib/launchdr/launchd.rb
+- lib/launchdr/property_list.rb
+- lib/launchdr/task.rb
+- lib/launchdr.rb
+- Rakefile.rb
+- README.markdown
+- .manifest
+- launchdr.gemspec
+has_rdoc: true
+homepage: http://github.com/elliottcable/launchdr
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Launchdr
+- --main
+- README.markdown
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 134023568094289244
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 1922007725579590311
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: launchdr
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 2
+summary: One stop shop for launchd property list creation. The doctor is *in*!
+test_files: []
+