magikku 0.1.0

data/lib/magikku_ffi.rb

@@ -0,0 +1,278 @@
+require 'ffi'
+require 'ffi/libmagic'
+
+require 'magikku/convenience'
+
+# Note the implementation of this class may either be via FFI
+# or via native C bindings depending on your installation and
+# what version of ruby you are using.
+class MagikkuFFI
+  extend MagikkuHelpers
+
+  # Defines various flags that can be passed when creating a magic scan object
+  # using Magikku.new or afterwards using Magikku.flags=
+  module Flags
+    # No flags
+    NONE              = 0x000000
+
+    # Turn on debugging
+    DEBUG             = 0x000001
+
+    # Follow symlinks
+    SYMLINK           = 0x000002
+
+    # Check inside compressed files
+    COMPRESS          = 0x000004
+
+    # Look at the contents of devices
+    DEVICES           = 0x000008
+
+    # Return the MIME type
+    MIME_TYPE         = 0x000010
+
+    # Return all matches
+    CONTINUE          = 0x000020
+
+    # Print warnings to stderr
+    CHECK             = 0x000040
+
+    # Restore access time on exit
+    PRESERVE_ATIME    = 0x000080
+
+    # Don't translate unprintable chars
+    RAW               = 0x000100
+
+    # Handle ENOENT etc as real errors
+    ERROR             = 0x000200
+
+    # Return the MIME encoding
+    MIME_ENCODING     = 0x000400
+
+    # alias for (MAGIC_MIME_TYPE|MAGIC_MIME_ENCODING)
+    MIME              = (MIME_TYPE|MIME_ENCODING)
+
+    # Return the Apple creator and type
+    APPLE             = 0x000800
+
+    # Don't check for compressed files
+    NO_CHECK_COMPRESS = 0x001000
+
+    # Don't check for tar files
+    NO_CHECK_TAR      = 0x002000
+
+    # Don't check magic entries
+    NO_CHECK_SOFT     = 0x004000
+
+    # Don't check application type
+    NO_CHECK_APPTYPE  = 0x008000
+
+    # Don't check for elf details
+    NO_CHECK_ELF      = 0x010000
+
+    # Don't check for text files
+    NO_CHECK_TEXT     = 0x020000
+
+    # Don't check for cdf files
+    NO_CHECK_CDF      = 0x040000
+
+    # Don't check tokens
+    NO_CHECK_TOKENS   = 0x100000
+
+    # Don't check text encodings
+    NO_CHECK_ENCODING = 0x200000 
+
+    # alias for NO_CHECK_TEXT
+    NO_CHECK_ASCII   = NO_CHECK_TEXT 
+  end
+
+  # Returns the default magic database path.
+  def self.path
+    FFI::Libmagic.magic_getpath(nil, 0)
+  end
+
+  # A base class for other Magikku error types
+  class MagikkuError < StandardError
+  end
+
+  # Raised when an error occurs during loading of a magic database.
+  class DbLoadError < MagikkuError
+  end
+
+  # Raised when an unexpected fatal error occurs initializing libmagic
+  class InitFatal < MagikkuError
+  end
+
+  # Raised when an error occurs during compiling of a magic database.
+  class CompileError < MagikkuError
+  end
+
+  # Raised when an error occurs when setting flags on a Magikku object.
+  class FlagError < MagikkuError
+  end
+
+  # Raised when an error occurs when setting flags on a Magikku object.
+  class ClosedError < MagikkuError
+  end
+
+  # Initializes a new libmagic data scanner
+  #
+  # @param [Hash,nil] params
+  #   A hash of parameters or nil for defaults.
+  #
+  # @option params [Fixnum,nil] :flags
+  #   Optional flags to magic (see MagikkuFFI::Flags). 
+  #   The flag values should be 'or'ed to gether with '|'. 
+  #   Default: NONE
+  #
+  # @option params [String, nil] :db
+  #   Optional magicfile databases or un-compiled magic files.
+  #   Default: the default system magic.mgc file.
+  #
+  # @see See MagikkuFFI::Flags and libmagic(3) manpage
+  # @see dbload()
+  def initialize(param = nil)
+    param ||= {}
+    raise(TypeError, "Invalid Type for params") if not param.is_a?(Hash)
+
+    flags = param[:flags] || Flags::NONE
+    raise(TypeError, "flags must be a Fixnum") if not flags.is_a?(Fixnum)
+
+    db = param[:db]
+    raise(TypeError, "db must be nil or a String") if db and not db.is_a?(String)
+
+    @_cookie = FFI::Libmagic.magic_open(flags)
+    if @_cookie.null?
+      raise(InitFatal, "magic_open(#{flags}) returned a null pointer")
+    end
+
+    if FFI::Libmagic.magic_load(_cookie, db) != 0
+      err = lasterror()
+      FFI::Libmagic.magic_close(_cookie)
+      raise(DbLoadError, "Error loading db: #{db.inspect} " << err)
+    end
+  end
+
+  # Close the libmagic data scanner handle when you are finished with it
+  def close
+    FFI::Libmagic.magic_close(_cookie) unless @closed
+
+    @closed = true
+    return nil
+  end
+
+  def closed?
+    (@closed == true)
+  end
+
+  # Analyzes file contents against the magicfile database
+  #
+  # @param filename 
+  #   The path to a file to inspect
+  # @return [String] 
+  #   A textual description of the contents of the file
+  def file(filename)
+    File.stat(filename)
+    raise(TypeError, "filename must not be nil") if filename.nil?
+    FFI::Libmagic.magic_file(_cookie, filename)
+  end
+
+  # Analyzes a string buffer against the magicfile database
+  #
+  # @param filename 
+  #   The string buffer to inspect
+  # @return [String] 
+  #   A textual description of the contents the string
+  def string(str)
+    raise(TypeError, "wrong argument type #{str.class} (expected String)") unless str.is_a?(String)
+    p = FFI::MemoryPointer.new(str.size)
+    p.write_string_length(str, str.size)
+    FFI::Libmagic.magic_buffer(_cookie, p, str.size)
+  end
+
+  # Used to load one or more magic databases.
+  # 
+  # @param magicfiles
+  #   One or more filenames seperated by colons. If nil, the default database
+  #   is loaded.
+  #   If uncompiled magic files are specified, they are compiled on the fly
+  #   but they do not generate new .mgc files as with the compile method.
+  #   Multiple files be specified by seperating them with colons.
+  #
+  # @raise [DbLoadError] if an error occurred loading the database(s)
+  def dbload(magicfiles)
+    if FFI::Libmagic.magic_load(_cookie, magicfiles) != 0
+      raise(DbLoadError, "Error loading db: #{magicfiles.inspect} " << lasterror())
+    else
+      return true
+    end
+  end
+
+  # Sets flags for the magic analyzer handle.
+  #
+  # @param flags
+  #   Flags to to set for magic. See MagikkuFFI::Flags and libmagic(3) manpage. 
+  #   The flag values should be 'or'ed together with '|'. 
+  #   Using 0 will clear all flags.
+  def flags=(flags)
+    if FFI::Libmagic.magic_setflags(_cookie, flags) < 0
+      raise(FlagError, lasterror())
+    end
+  end
+
+  # Can be used to compile magic files. This does not load files, however. You must
+  # use dbload for that.
+  #
+  # Note: Errors and warnings may be displayed on stderr.
+  #
+  # @param [String,nil] filename
+  #   A colon seperated list of filenames or a single filename. 
+  #   The compiled files created are generated in the current directory using 
+  #   the basename(1) of each file argument with ".mgc" appended to it.
+  #   Directory names can be compiled, in which case the contents of the directory
+  #   will be compiled together as a single .mgc file.
+  #   nil compiles the default database.
+  #
+  # @return [true] if everything went well.
+  #
+  # @raise [CompileError] if an error occurred.
+  def compile(filenames)
+    if FFI::Libmagic.magic_compile(_cookie, filenames) != 0
+      raise(CompileError, "Error compiling #{filenames.inspect}: " << lasterror())
+    else
+      return true
+    end
+  end
+
+  # Can be used to check the validity of magic files before compiling them.
+  # This is basically a dry-run that can be used before compiling magicfile 
+  # databases.
+  #
+  # Note: Errors and warnings may be displayed on stderr.
+  #
+  # @param [String,nil] filename
+  #   A colon seperated list of filenames or a single file. nil checks the
+  #   default database.
+  #
+  # @return [true,false] Indicates whether the check was successful.
+  def check_syntax(filenames=nil)
+    return (FFI::Libmagic.magic_check(_cookie, filenames) == 0)
+  end
+
+  private
+    def _cookie
+      if @closed
+        raise(ClosedError, "This magic cookie is closed and can no longer be used")
+      else
+        @_cookie
+      end
+    end
+
+    def lasterror
+      FFI::Libmagic.magic_error(_cookie)
+    end
+
+    def lasterrno
+      FFI::Libmagic.magic_errno(_cookie)
+    end
+
+end

data/spec/magikku_behaviors.rb

@@ -0,0 +1,288 @@
+require 'tmpdir'
+
+shared_examples_for "Magikku compiling interface" do
+
+  context "Initializing" do
+    it "should initialize cleanly without arguments" do
+      c=nil
+      lambda { c=@klass.new }.should_not raise_error
+      c.close if c
+    end
+
+    it "should initialize cleanly when a flag argument is given" do
+      c=nil
+      lambda { c=@klass.new(:flags => @klass::Flags::NONE) }.should_not raise_error
+      c.close if c
+    end
+
+    it "should initialize cleanly when a magicfile argument is given" do
+      c=nil
+      lambda { c=@klass.new(:db => @testrule) }.should_not raise_error
+      c.close
+    end
+
+    it "should initialize cleanly when both arguments are given" do
+      c=nil
+      lambda { 
+        c=@klass.new(:flags => @klass::Flags::NONE, :db => @testrule) 
+      }.should_not raise_error  
+      c.close if c
+    end
+
+
+    it "should raise an error when incorrect argument types are given" do
+      c=nil
+      lambda { c=@klass.new(nil) }.should_not raise_error()
+      c.close if c
+      c=nil
+      lambda { c=@klass.new(Object.new) }.should raise_error(TypeError)
+      c.close if c
+    end
+
+
+    it "should raise an error when the wrong argument count is given" do
+      c=nil
+      lambda { c=@klass.new(Hash.new,Object.new) }.should raise_error(ArgumentError)
+      c.close if c
+    end
+
+    it "should raise an error when a nonexistant magic file is given" do
+      c=nil
+      lambda { 
+        c=@klass.new(:db => sample_file('totallybogus')) 
+      }.should raise_error(@klass::DbLoadError)
+      c.close if c
+    end
+
+    it "should raise an error when a magic file format error occurs" do
+      c=nil
+      lambda { 
+        c=@klass.new(:db => sample_file('fail_magicrules')) 
+      }.should raise_error(@klass::DbLoadError)
+      c.close if c
+    end
+  end
+
+  context "An Instantiated Object" do
+    before :each do
+      @magic=@klass.new()
+    end
+
+    after :each do
+      @magic.close if not @magic.closed?
+    end
+
+    it "should be able to identify file buffers" do
+      @magic.file(sample_file("test.txt")).should == "ASCII text"
+      @magic.file(sample_file("test.c")).should == "ASCII C program text"
+    end
+
+    it "should be able to identify string buffers" do
+      @magic.string(File.read(sample_file("test.txt"))).should == "ASCII text"
+      @magic.string(File.read(sample_file("test.c"))).should == "ASCII C program text"
+      @magic.string("\x01\x02\x03\x04").should == "data"
+    end
+
+    it "should be able to use flag options" do
+      @magic.flags = @klass::Flags::MIME
+      @magic.string(File.read(sample_file("test.txt"))).should == "text/plain; charset=us-ascii"
+      @magic.string(File.read(sample_file("test.c"))).should == "text/x-c; charset=us-ascii"
+      @magic.string("\x01\x02\x03\x04").should == "application/octet-stream; charset=binary"
+    end
+
+    it "should raise an error if a nonexistant file is specified to inspect" do
+      lambda{
+        @magic.file(sample_file('totallybogusfile'))
+      }.should raise_error(Errno::ENOENT)
+    end
+
+    it "should raise an error when an incorrect object is passed to file()" do
+      lambda{ @magic.file(Object.new) }.should raise_error(TypeError)
+      lambda{ @magic.file(nil) }.should raise_error(TypeError)
+    end
+
+    it "should raise an error when an incorrect object is passed to file()" do
+      lambda{ @magic.string(Object.new) }.should raise_error(TypeError)
+      lambda{ @magic.string(nil) }.should raise_error(TypeError)
+    end
+
+    it "should be able to load magicrules databases" do
+      test_str="THISISARUBYMAGICTEST blah blah\nblah\x01\x02"
+      @magic.string(test_str).should_not == "RUBYMAGICTESTHIT"
+      @magic.dbload(sample_file('test_magicrule'))
+      @magic.string(test_str).should == "RUBYMAGICTESTHIT"
+    end
+
+    it "should load the default magicrules database when nil is loaded" do
+      test_str="THISISARUBYMAGICTEST blah blah\nblah\x01\x02"
+      @magic.string(test_str).should_not == "RUBYMAGICTESTHIT"
+      @magic.string(test_str).should == "data"
+      @magic.dbload(nil)
+      @magic.string(test_str).should_not == "RUBYMAGICTESTHIT"
+      @magic.string(test_str).should == "data"
+    end
+
+    it "should raise an error when loading an invalid filename" do
+      lambda{ 
+        @magic.dbload(sample_file('totallybogusfile')) 
+      }.should raise_error(@klass::DbLoadError)
+    end
+
+    it "should raise an error when an incorrect object is passed to dbload()" do
+      lambda{ 
+        @magic.dbload(Object.new)
+      }.should raise_error(@argerror)
+    end
+
+    it "should be able to be closed" do
+      lambda { @magic.close }.should_not raise_error
+      @magic.should be_closed
+    end
+
+    it "should correctly indicate whether it is already closed" do
+      @magic.should_not be_closed
+      @magic.close
+      @magic.should be_closed
+      lambda { @magic.close }.should_not raise_error
+    end
+
+    it "should not be usable after it is closed" do
+      @magic.close
+      lambda{
+        @magic.file(File.expand_path(__FILE__))
+      }.should raise_error(@klass::ClosedError)
+
+      lambda{
+        @magic.string("foo")
+      }.should raise_error(@klass::ClosedError)
+
+      lambda{
+        @magic.check_syntax(sample_file('fail_magicrules')) 
+      }.should raise_error(@klass::ClosedError)
+
+      lambda{ 
+        @magic.compile(sample_file('fail_magicrules')) 
+      }.should raise_error(@klass::ClosedError)
+
+      lambda{ 
+        @magic.check_syntax(sample_file('ruby_magicrules')) 
+      }.should raise_error(@klass::ClosedError)
+
+      lambda{ 
+        @magic.compile(sample_file('ruby_magicrules')) 
+      }.should raise_error(@klass::ClosedError)
+
+    end
+  end
+
+  context "Compiling And Convenience Methods" do
+    before :all do
+      @tmpdir = Dir.mktmpdir
+    end
+
+    before :each do
+      @origdir =Dir.pwd
+      Dir.chdir @tmpdir
+
+      @testrule = sample_file("ruby_magicrules")
+      @expect_mgc = "#{File.basename(@testrule)}.mgc"
+
+      File.should_not be_file(@expect_mgc)
+    end
+
+    after :each do
+      File.delete @expect_mgc if File.exists?(@expect_mgc)
+      Dir.chdir @origdir
+    end
+
+    it "should work using the compile convenience class method" do
+      @klass.compile(@testrule).should == true
+    end
+
+    it "should work using an instantiated object" do
+      m=@klass.new
+      m.compile(@testrule).should == true
+      m.close
+    end
+
+    it "should raise an error when compiling an invalid filename" do
+      lambda{ 
+        @klass.compile(sample_file('totallnonexistantfile'))
+      }.should raise_error(@klass::CompileError)
+    end
+
+    it "should raise an error when compiling an syntactically incorrect filename" do
+      lambda{ 
+        @klass.compile(sample_file('fail_magicrules'))
+      }.should raise_error(@klass::CompileError)
+    end
+
+    it "should work using the check_syntax convenience class method" do
+      @klass.check_syntax(@testrule).should == true
+      File.should_not be_file(@expect_mgc)
+      @klass.check_syntax(@testrule).should == true
+      @klass.check_syntax(sample_file('fail_magicrules')).should == false
+    end
+
+    it "should work when checking syntax using an instantiated object" do
+      m=@klass.new
+      m.check_syntax(@testrule).should == true
+      File.should_not be_file(@expect_mgc)
+      m.check_syntax(sample_file('fail_magicrules')).should == false
+      m.close
+    end
+
+    it "should return false when checking an invalid filename" do
+      @klass.check_syntax(sample_file('totallnonexistantfile')).should == false
+      m=@klass.new
+      m.check_syntax(sample_file('totallnonexistantfile')).should == false
+      m.close
+    end
+
+    it "should check the default database when given a nil filename" do
+      @klass.check_syntax(nil).should == true
+      m=@klass.new
+      m.check_syntax(nil).should == true
+      m.close
+    end
+
+    it "should return the default magic database with path()" do
+      @klass.path.should be_kind_of(String)
+      @klass.path.should_not be_empty
+    end
+
+    it "should scan a file using the #{@klass}.file singleton method" do
+      @klass.file(sample_file('test.txt')).should == "ASCII text"
+      @klass.file(sample_file('test.c')).should == "ASCII C program text"
+    end
+
+    it "should take initialization params as extra args to .file()" do
+      @klass.file(sample_file('test.txt'), 
+                  :flags => @klass::Flags::MIME).should == "text/plain; charset=us-ascii"
+
+      @klass.file(sample_file('rawtestdat.raw'), :db => nil).should == "data"
+
+      @klass.file(sample_file('rawtestdat.raw'), :db => sample_file('test_magicrule')).should == "RUBYMAGICTESTHIT"
+
+    end
+
+    it "should scan a file using the #{@klass}.string singleton method" do
+      @klass.string(File.read(sample_file('test.txt'))).should == "ASCII text"
+      @klass.string(File.read(sample_file('test.c'))).should == "ASCII C program text"
+    end
+
+    it "should take initialization params as extra args to .string()" do
+
+      @klass.string(File.read(sample_file('test.txt')), 
+                  :flags => @klass::Flags::MIME).should == "text/plain; charset=us-ascii"
+      test_str="THISISARUBYMAGICTEST blah blah\nblah\x01\x02"
+      @klass.string(test_str).should_not == "RUBYMAGICTESTHIT"
+
+      @klass.string(test_str, :db => sample_file('test_magicrule')).should == "RUBYMAGICTESTHIT"
+
+     end
+
+
+  end
+
+end

data/spec/magikku_ffi_spec.rb

@@ -0,0 +1,30 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'magikku_ffi'
+
+if Magikku != MagikkuFFI
+
+  describe MagikkuFFI do
+    before :all do 
+      @klass = MagikkuFFI
+      @argerror = ArgumentError
+    end
+
+    it_should_behave_like "Magikku compiling interface"
+  end
+
+  describe MagikkuFFI::Flags do
+    context "Checking Values" do
+      Magikku::Flags.constants.each do |const|
+        it "should have the correct value for #{const}" do
+          Magikku::Flags.const_get(const).should == MagikkuFFI::Flags.const_get(const)
+        end
+      end
+    end
+  end
+else
+  describe "C Binding" do
+    it "was not compiled" do
+      pending "unable to test C bindings"
+    end
+  end
+end

data/spec/magikku_spec.rb

@@ -0,0 +1,10 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Magikku do
+  before :all do 
+    @klass = Magikku
+    @argerror = TypeError
+  end
+
+  it_should_behave_like "Magikku compiling interface"
+end

data/spec/sample/fail_magicrules

@@ -0,0 +1 @@
+bogus

data/spec/sample/rawtestdat.raw

@@ -0,0 +1,2 @@
+THISISARUBYMAGICTEST blah blah
+blah


data/spec/sample/ruby_magicrules

@@ -0,0 +1,16 @@
+
+#------------------------------------------------------------------------------
+# $File: ruby,v 1.3 2009/09/19 16:28:12 christos Exp $
+# ruby:  file(1) magic for Ruby scripting language
+# URL:  http://www.ruby-lang.org/
+# From: Reuben Thomas <rrt@sc3d.org>
+
+# Ruby scripts
+0	search/1/w	#!\ /usr/bin/ruby	Ruby script text executable
+!:mime text/x-ruby
+0	search/1/w	#!\ /usr/local/bin/ruby	Ruby script text executable
+!:mime text/x-ruby
+0	search/1	#!/usr/bin/env\ ruby	Ruby script text executable
+!:mime text/x-ruby
+0	search/1	#!\ /usr/bin/env\ ruby	Ruby script text executable
+!:mime text/x-ruby

data/spec/sample/test.c

@@ -0,0 +1,6 @@
+
+/* this is a sample C program for testing libmagic */
+int
+main(int argc, char *argv) {
+  return 0;
+}

data/spec/sample/test.txt

@@ -0,0 +1,3 @@
+
+This is a sample text file for testing libmagic.
+

data/spec/sample/test_magicrule

@@ -0,0 +1 @@
+0	string	THISISARUBYMAGICTEST	RUBYMAGICTESTHIT

data/spec/spec.opts

@@ -0,0 +1,3 @@
+--color
+--format nested
+-b

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'magikku'
+require 'spec'
+require 'spec/autorun'
+
+require 'magikku_behaviors'
+
+def sample_file(filename)
+  return File.expand_path(File.join(File.dirname(__FILE__), "sample", filename))
+end
+
+Spec::Runner.configure do |config|
+  
+end