magic 0.0.2 → 0.1.0

data/README.rdoc

@@ -1,15 +1,43 @@
 = magic
 
-Description goes here.
+Ruby FFI bindings to the "magic" library. Determines content type and
+encoding of files and strings. There are three sets of tests,
+performed in this order: filesystem tests, magic number tests, and
+language tests. The first test that succeeds causes the file type to
+be printed.
+
+== Usage
+  require "magic"
+  Magic.guess_file_mime("public/images/rails.png")
+  # => "image/png; charset=binary"
+  Magic.guess_file_mime_encoding("public/images/rails.png")
+  # => "binary"
+  Magic.guess_file_mime_type("public/images/rails.png")
+  # => "image/png"
+  Magic.guess_string_mime("Magic® File™")
+  # => "text/plain; charset=utf-8"
+  Magic.guess_string_mime_encoding("Magic® File™")
+  # => "utf-8"
+  Magic.guess_string_mime_type("Magic® File™")
+  # => "text/plain"
+
+== Links
+* gemcutter[http://gemcutter.org/gems/magic]
+* repository[http://github.com/qoobaa/magic]
+* {issue tracker}[http://github.com/qoobaa/magic/issues]
+* rdoc[http://qoobaa.github.com/magic]
 
 == Note on Patches/Pull Requests
- 
 * Fork the project.
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a future version unintentionally.
-* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Add tests for it. This is important so I don't break it in a future
+  version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want
+  to have your own version, that is fine but bump version in a commit
+  by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 == Copyright
-
-Copyright (c) 2010 Jakub Kuźma. See LICENSE for details.
+Copyright (c) 2010 Jakub Kuźma. See
+LICENSE[http://github.com/qoobaa/magic/raw/master/LICENSE] for
+details.

data/Rakefile

@@ -7,14 +7,44 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "magic"
-    gem.summary = %Q{Ruby bindings for Magic}
-    gem.description = %Q{Ruby bindings for Magic}
+    gem.summary = %Q{Determine file type and encoding using "magic" numbers}
+    gem.description = %Q{Ruby FFI bindings to libmagic}
     gem.email = "qoobaa@gmail.com"
     gem.homepage = "http://github.com/qoobaa/magic"
     gem.authors = ["Jakub Kuźma"]
     gem.add_dependency "ffi", ">= 0.5.1"
     gem.add_development_dependency "test-unit", ">= 2.0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.post_install_message = <<-EOM
++-NOTE FOR LINUX USERS----------------------------------------------+
+|                                                                   |
+| Install libmagic using your package manager, e.g.                 |
+|                                                                   |
+|   sudo apt-get install file                                       |
+|                                                                   |
++-NOTE FOR WINDOWS USERS -------------------------------------------+
+|                                                                   |
+| Install File for Windows from                                     |
+|                                                                   |
+|   http://gnuwin32.sourceforge.net/packages/file.htm               |
+|                                                                   |
++-NOTE FOR MAC OS USERS --------------------------------------------+
+|                                                                   |
+| If you don't have libmagic.1.dylib file in your system            |
+|                                                                   |
+|   find / -name libmagic.1.dylib                                   |
+|                                                                   |
+| You need to install it via port command                           |
+|                                                                   |
+|   sudo port install file                                          |
+|                                                                   |
+| Sometimes you'll also need to set your DYLD_FALLBACK_LIBRARY_PATH |
+| environment variable to the directory of the libmagic.1.dylib     |
+|                                                                   |
+|   export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib                |
+|                                                                   |
++-------------------------------------------------------------------+
+EOM
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.1.0

data/lib/magic.rb

@@ -1,6 +1,6 @@
-require "ffi"
+# encoding: utf-8
 
-ENV["DYLD_FALLBACK_LIBRARY_PATH"] ||= "/opt/local/lib" if FFI::Platform.mac?
+require "ffi"
 
 require "magic/errors"
 require "magic/api"
@@ -9,33 +9,57 @@ require "magic/database"
 
 module Magic
   class << self
+    # Guesses mime of given file
+    # ====== Example
+    #   Magic.guess_file_mime("public/images/rails.png")
+    #   # => "image/png; charset=binary"
     def guess_file_mime(file)
       guess(:file, :mime, file)
     end
 
+    # Guesses mime encoding of given file
+    # ===== Example
+    #   Magic.guess_file_mime_encoding("public/images/rails.png")
+    #   # => "binary"
     def guess_file_mime_encoding(file)
       guess(:file, :mime_encoding, file)
     end
 
+    # Guesses mime type of given file
+    # ===== Example
+    #   Magic.guess_file_mime_type("public/images/rails.png")
+    #   # => "image/png"
     def guess_file_mime_type(file)
       guess(:file, :mime_type, file)
     end
 
+    # Guesses mime type of given string
+    # ===== Example
+    #   Magic.guess_string_mime("Magic® File™")
+    #   # => "text/plain; charset=utf-8"
     def guess_string_mime(string)
       guess(:buffer, :mime, string)
     end
 
+    # Guesses mime type of given string
+    # ===== Example
+    #   Magic.guess_string_mime_encoding("Magic® File™")
+    #   # => "utf-8"
     def guess_string_mime_encoding(string)
       guess(:buffer, :mime_encoding, string)
     end
 
+    # Guesses mime type of given string
+    # ===== Example
+    #   Magic.guess_string_mime_type("Magic® File™")
+    #   # => "text/plain"
     def guess_string_mime_type(string)
       guess(:buffer, :mime_type, string)
     end
 
     protected
 
-    def guess(type, what, where)
+    def guess(type, what, where) #:nodoc:
       db = Database.new(what)
       result = db.send(type, where)
       db.close

data/lib/magic/api.rb

@@ -1,8 +1,8 @@
 module Magic
-  module Api
+  module Api #:nodoc:
     extend FFI::Library
 
-    ffi_lib "magic.1"
+    ffi_lib "libmagic.so.1", "libmagic.1.dylib", "magic1.dll"
 
     attach_function :magic_open, [:int], :pointer
     attach_function :magic_close, [:pointer], :void

data/lib/magic/constants.rb

@@ -1,29 +1,52 @@
 module Magic
-  module Constants
+  module Constants #:nodoc:
     module Flag
-      NONE              = 0x000000 # No flags
-      DEBUG             = 0x000001 # Turn on debugging
-      SYMLINK           = 0x000002 # Follow symlinks
-      COMPRESS          = 0x000004 # Check inside compressed files
-      DEVICES           = 0x000008 # Look at the contents of devices
-      MIME_TYPE         = 0x000010 # Return the MIME type
-      CONTINUE          = 0x000020 # Return all matches
-      CHECK             = 0x000040 # Print warnings to stderr
-      PRESERVE_ATIME    = 0x000080 # Restore access time on exit
-      RAW               = 0x000100 # Don't translate unprintable chars
-      ERROR             = 0x000200 # Handle ENOENT etc as real errors
-      MIME_ENCODING     = 0x000400 # Return the MIME encoding
+      # 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
+      # Return the MIME "type; charset=encoding"
       MIME              = (MIME_TYPE | MIME_ENCODING)
-      APPLE             = 0x000800 # Return the Apple creator and type
-      NO_CHECK_COMPRESS = 0x001000 # Don't check for compressed files
-      NO_CHECK_TAR      = 0x002000 # Don't check for tar files
-      NO_CHECK_SOFT     = 0x004000 # Don't check magic entries
-      NO_CHECK_APPTYPE  = 0x008000 # Don't check application type
-      NO_CHECK_ELF      = 0x010000 # Don't check for elf details
-      NO_CHECK_TEXT     = 0x020000 # Don't check for text files
-      NO_CHECK_CDF      = 0x040000 # Don't check for cdf files
-      NO_CHECK_TOKENS   = 0x100000 # Don't check tokens
-      NO_CHECK_ENCODING = 0x200000 # Don't check text encodings
+      # 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
     end
   end
 end

data/lib/magic/database.rb

@@ -1,25 +1,30 @@
 module Magic
   class Database
+    # Creates an instance of +Magic::Database+ using given flags
     def initialize(*flags)
       open(*flags)
       load
     end
 
+    # Opens magic db using given flags
     def open(*flags)
       magic_flags = flags.inject(0) { |acc, flag| acc |= Constants::Flag.const_get(flag.to_s.upcase) }
       @magic_set = Api.magic_open(magic_flags)
     end
 
+    # Closes the database
     def close
       Api.magic_close(@magic_set)
     end
 
+    # Loads given database file (or default if +nil+ given)
     def load(database = nil)
       Api.magic_load(@magic_set, database)
     end
 
-    def file(file)
-      result = Api.magic_file(@magic_set, file)
+    # Determine type of a file at given path
+    def file(filename)
+      result = Api.magic_file(@magic_set, filename.to_s)
       if result.null?
         raise Exception, error
       else
@@ -27,6 +32,7 @@ module Magic
       end
     end
 
+    # Determine type of given string
     def buffer(string)
       result = Api.magic_buffer(@magic_set, string, string.bytesize)
       if result.null?
@@ -36,6 +42,7 @@ module Magic
       end
     end
 
+    # Returns last error occured
     def error
       Api.magic_error(@magic_set)
     end

data/lib/magic/errors.rb

@@ -1,3 +1,5 @@
 module Magic
-  class Exception < StandardError; end
+  # General Exception class
+  class Exception < StandardError
+  end
 end

data/test/fixtures/magic.txt

@@ -0,0 +1 @@
+Magic® File™

data/test/helper.rb

@@ -1,10 +1,13 @@
 require 'rubygems'
-require 'test/unit'
-require 'shoulda'
+gem "test-unit"
+require "test/unit"
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'magic'
 
 class Test::Unit::TestCase
+  def fixture(filename)
+    File.join(File.dirname(__FILE__), "fixtures", filename)
+  end
 end

data/test/test_magic.rb

@@ -1,7 +1,45 @@
 require 'helper'
 
 class TestMagic < Test::Unit::TestCase
-  should "probably rename this file and start testing for real" do
-    flunk "hey buddy, you should probably rename this file and start testing for real"
+  def test_guess_magic_text_mime
+    assert_equal "text/plain; charset=utf-8", Magic.guess_file_mime(fixture("magic.txt"))
+  end
+
+  def test_guess_magic_text_mime_type
+    assert_equal "text/plain", Magic.guess_file_mime_type(fixture("magic.txt"))
+  end
+
+  def test_guess_magic_text_mime_encoding
+    assert_equal "utf-8", Magic.guess_file_mime_encoding(fixture("magic.txt"))
+  end
+
+  def test_guess_magic_logo_mime
+    assert_equal "image/jpeg; charset=binary", Magic.guess_file_mime(fixture("filelogo.jpg"))
+  end
+
+  def test_guess_magic_logo_mime_type
+    assert_equal "image/jpeg", Magic.guess_file_mime_type(fixture("filelogo.jpg"))
+  end
+
+  def test_guess_magic_logo_mime_encoding
+    assert_equal "binary", Magic.guess_file_mime_encoding(fixture("filelogo.jpg"))
+  end
+
+  def test_guess_non_existing_file_mime
+    assert_raises Magic::Exception do
+      Magic.guess_file_mime(fixture("non-existing.file"))
+    end
+  end
+
+  def test_guess_non_existing_file_mime_type
+    assert_raises Magic::Exception do
+      Magic.guess_file_mime_type(fixture("non-existing.file"))
+    end
+  end
+
+  def test_guess_non_existing_file_mime_encoding
+    assert_raises Magic::Exception do
+      Magic.guess_file_mime_encoding(fixture("non-existing.file"))
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: magic
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - "Jakub Ku\xC5\xBAma"
@@ -32,7 +32,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "2.0"
     version: 
-description: Ruby bindings for Magic
+description: Ruby FFI bindings to libmagic
 email: qoobaa@gmail.com
 executables: []
 
@@ -53,13 +53,44 @@ files:
 - lib/magic/constants.rb
 - lib/magic/database.rb
 - lib/magic/errors.rb
+- test/fixtures/filelogo.jpg
+- test/fixtures/magic.txt
 - test/helper.rb
 - test/test_magic.rb
 has_rdoc: true
 homepage: http://github.com/qoobaa/magic
 licenses: []
 
-post_install_message: 
+post_install_message: |
+  +-NOTE FOR LINUX USERS----------------------------------------------+
+  |                                                                   |
+  | Install libmagic using your package manager, e.g.                 |
+  |                                                                   |
+  |   sudo apt-get install file                                       |
+  |                                                                   |
+  +-NOTE FOR WINDOWS USERS -------------------------------------------+
+  |                                                                   |
+  | Install File for Windows from                                     |
+  |                                                                   |
+  |   http://gnuwin32.sourceforge.net/packages/file.htm               |
+  |                                                                   |
+  +-NOTE FOR MAC OS USERS --------------------------------------------+
+  |                                                                   |
+  | If you don't have libmagic.1.dylib file in your system            |
+  |                                                                   |
+  |   find / -name libmagic.1.dylib                                   |
+  |                                                                   |
+  | You need to install it via port command                           |
+  |                                                                   |
+  |   sudo port install file                                          |
+  |                                                                   |
+  | Sometimes you'll also need to set your DYLD_FALLBACK_LIBRARY_PATH |
+  | environment variable to the directory of the libmagic.1.dylib     |
+  |                                                                   |
+  |   export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib                |
+  |                                                                   |
+  +-------------------------------------------------------------------+
+
 rdoc_options: 
 - --charset=UTF-8
 require_paths: 
@@ -82,7 +113,7 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Ruby bindings for Magic
+summary: Determine file type and encoding using "magic" numbers
 test_files: 
 - test/test_magic.rb
 - test/helper.rb