libmagic_rb 0.1.2.pre.beta → 0.1.2.pre.gamma

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f249db73a864f2f290165eb9dc8d943f8016e25d202e0a592754418510f4110
-  data.tar.gz: c3026e23ac5e7ed0416b0c7e0694982baed1b7f78ec95f3845a5e616076b88b1
+  metadata.gz: 116d3dc132643a74f2a887128844a9faa5a4b0a53b7aded5e70bd296087ad005
+  data.tar.gz: 77f551eddaae7a4d1e70840608ec008cc509569d5c9153d0e07f7d710fc371e7
 SHA512:
-  metadata.gz: '065198fe056d97dd295fd472697e0b1dcdef27dee5a995eca8718035beb64bf8b2ed3ca7eff6c6fd4462efcb6892f4f05ed33d8139872a193e2d2296c2e138e1'
-  data.tar.gz: 6a85f647db0401541b18cebdb2020518a3d8421c4e15452f0d47bab17808f8ad950aba613e3d7188b610034f3f3e58ca86b0e53d45939ed7709942630e2f4523
+  metadata.gz: 804a95966aeca5e305ff5b6d18a733528dcbf179617cefb461bd779c0dbbb8aa044d6edeca9a55b2b04b62c8c6b8c69b82f8d0a4c7663eba43e6798b8ab51a31
+  data.tar.gz: fefe9f019f2decd1e85f7836eacbac01bc6c5e9f22beb22d5e271b903eed83d7b6e25d942e3460be4a2f92d9312faa4eaac477775b6c75c36e23d68035634813

data/README.md

@@ -1,4 +1,5 @@
-# LibmagicRb
+# LibmagicRb [![Gem Version](https://badge.fury.io/rb/libmagic_rb.svg)](https://rubygems.org/gems/libmagic_rb) ![Workflow Status](https://github.com/cybergizer-hq/libmagicrb/workflows/LibmagicRb%20Test/badge.svg)
+
 Adds ability to check mime-type of a file using the libmagic ([magic(4)](https://man7.org/linux/man-pages/man4/magic.4.html)).
 It uses native extensions and it's quite performant.
 

data/ext/libmagic/func.h

@@ -1,3 +1,15 @@
+/*
+	Closes a magic cookie. For example:
+
+		> cookie = LibmagicRb.new(file: '/usr/share/dict/words')
+		# => #<LibmagicRb:0x00005581019fa7e0 @closed=false, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+		> cookie.close
+		# => #<LibmagicRb:0x00005581019fa7e0 @closed=true, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+	Returns self.
+*/
+
 VALUE _closeGlobal_(volatile VALUE self) {
 	RB_UNWRAP(cookie) ;
 
@@ -7,6 +19,23 @@ VALUE _closeGlobal_(volatile VALUE self) {
 	return self ;
 }
 
+/*
+	Changes the database path. For example:
+		> cookie = LibmagicRb.new(file: '/usr/share/dict/words')
+		# => #<LibmagicRb:0x00005581019181b0 @closed=false, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+		> cookie.db = '/usr/share/file/misc/magic.mgc'
+		# => "/usr/share/file/misc/magic.mgc"
+
+		> cookie.check
+		# => "text/plain; charset=utf-8"
+
+		> cookie.close
+		# => #<LibmagicRb:0x00005581019181b0 @closed=true, @db="/usr/share/file/misc/magic.mgc", @file="/usr/share/dict/words", @mode=1106>
+
+	Returns self.
+*/
+
 VALUE _loadGlobal_(volatile VALUE self, volatile VALUE dbPath) {
 	char *databasePath = NULL ;
 
@@ -27,6 +56,20 @@ VALUE _loadGlobal_(volatile VALUE self, volatile VALUE dbPath) {
 	return self ;
 }
 
+/*
+	Check a file with the magic database. For example:
+		> cookie = LibmagicRb.new(file: '/usr/share/dict/words')
+		# => #<LibmagicRb:0x00005581019181b0 @closed=false, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+		> cookie.check
+		# => "text/plain; charset=utf-8"
+
+		> cookie.close
+		# => #<LibmagicRb:0x00005581019181b0 @closed=true, @db="/usr/share/file/misc/magic.mgc", @file="/usr/share/dict/words", @mode=1106>
+
+		Returns String or nil.
+*/
+
 VALUE _checkGlobal_(volatile VALUE self) {
 	RB_UNWRAP(cookie) ;
 
@@ -51,6 +94,18 @@ VALUE _checkGlobal_(volatile VALUE self) {
 	return mt ? rb_str_new_cstr(mt) : Qnil ;
 }
 
+/*
+	Get parameters for a cookie. For example:
+		cookie = LibmagicRb.new(file: '/usr/share/dict/words')
+		# => #<LibmagicRb:0x00005581018f35e0 @closed=false, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+		> cookie.getparam(LibmagicRb::MAGIC_PARAM_NAME_MAX)
+		# => 50
+
+		> cookie.close
+		# => #<LibmagicRb:0x00005581018f35e0 @closed=true, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+*/
+
 VALUE _getParamGlobal_(volatile VALUE self, volatile VALUE param) {
 	#if MAGIC_VERSION > 525
 		RB_UNWRAP(cookie) ;
@@ -66,6 +121,27 @@ VALUE _getParamGlobal_(volatile VALUE self, volatile VALUE param) {
 	#endif
 }
 
+/*
+	Sets parameter for a cookie. For example:
+
+		> cookie = LibmagicRb.new(file: '/usr/share/dict/words')
+		# => #<LibmagicRb:0x00005581019f9840 @closed=false, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+		> cookie.getparam(LibmagicRb::MAGIC_PARAM_NAME_MAX)
+		=> 50
+
+		> cookie.setparam(LibmagicRb::MAGIC_PARAM_NAME_MAX, 101)
+		# => 101
+
+		> cookie.getparam(LibmagicRb::MAGIC_PARAM_NAME_MAX)
+		# => 101
+
+		> cookie.close
+		# => #<LibmagicRb:0x00005581019f9840 @closed=true, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+	Returns Integer or nil on failure.
+*/
+
 VALUE _setParamGlobal_(volatile VALUE self, volatile VALUE param, volatile VALUE paramVal) {
 	#if MAGIC_VERSION > 525
 		unsigned int _param = NUM2UINT(param) ;
@@ -85,25 +161,121 @@ VALUE _setParamGlobal_(volatile VALUE self, volatile VALUE param, volatile VALUE
 	#endif
 }
 
+/*
+	Returns a textual description of the contents of the buffer argument with length bytes size.
+
+	For example:
+
+		> cookie = LibmagicRb.new(file: '.')
+		# => #<LibmagicRb:0x00005582de0d1bf8 @closed=false, @db=nil, @file=".", @mode=1106>
+
+		> cookie.magic_buffer("%PDF-1.3\r\n")
+		# => "application/pdf; charset=us-ascii"
+
+		> cookie.close
+		# => #<LibmagicRb:0x00005582de0d1bf8 @closed=true, @db=nil, @file=".", @mode=1106>
+
+	Note that it automatically loads the database.
+
+	Returns either String or nil.
+*/
+
 VALUE _bufferGlobal_(volatile VALUE self, volatile VALUE string) {
 	RB_UNWRAP(cookie) ;
 
+	VALUE db = rb_iv_get(self, "@db") ;
+
+	char *database = NULL ;
+	if(RB_TYPE_P(db, T_STRING)) {
+		database = StringValuePtr(db) ;
+	}
+
+	if(database) magic_validate_db(*cookie, database) ;
+	magic_load(*cookie, database) ;
+
 	char *buffer = StringValuePtr(string) ;
-	const char *buf = magic_buffer(*cookie, buffer, sizeof(buffer)) ;
+	const char *buf = magic_buffer(*cookie, buffer, strlen(buffer)) ;
 
-	return rb_str_new_cstr(buf) ;
+	return buf ? rb_str_new_cstr(buf) : Qnil ;
 }
 
+/*
+	Dumps all magic entries in a human
+	readable format, dumping first the entries that are matched against
+	binary files and then the ones that match text files.
+
+	For example:
+
+
+		> cookie = LibmagicRb.new(file: '.')
+		# => #<LibmagicRb:0x000055cf280a9b30 @closed=false, @db=nil, @file=".", @mode=1106>
+
+		> cookie.magic_list
+		Set 0:
+		Binary patterns:
+		Strength = 500@47: Biosig/Brainvision Marker file [biosig/brainvision]
+		Strength = 490@122: Biosig/TMSiLOG [biosig/tmsilog]
+		Strength = 461@127: Biosig/SYNERGY [biosig/synergy]
+		Strength = 460@46: Biosig/Brainvision V-Amp file []
+		Strength = 410@45: Biosig/Brainvision data file []
+		Strength = 380@6: OpenSSH private key []
+		Strength = 370@1266: Novell message librarian data []
+		.
+		.
+		.
+		# => 0
+
+		> cookie.close
+		=> #<LibmagicRb:0x000055cf280a9b30 @closed=true, @db=nil, @file=".", @mode=1106>
+*/
+
 VALUE _listGlobal_(volatile VALUE self) {
 	RB_UNWRAP(cookie) ;
 
 	VALUE db = rb_iv_get(self, "@db") ;
-	char *database = StringValuePtr(db) ;
 
+	char *database = NULL ;
+	if (RB_TYPE_P(db, T_STRING)) {
+		database = StringValuePtr(db) ;
+	}
+
+	if(database) magic_validate_db(*cookie, database) ;
 	int status = magic_list(*cookie, database) ;
+
 	return INT2FIX(status) ;
 }
 
+/*
+	Set flags/modes for a cookie (not to be confused with params).
+	It's same setting mode through the setter cookie.mode = mode.
+
+	For example:
+
+		> cookie = LibmagicRb.new(file: '.')
+		# => #<LibmagicRb:0x00005583732e1070 @closed=false, @db=nil, @file=".", @mode=1106>
+
+		> cookie.check
+		# => "inode/directory; charset=binary"
+
+		> cookie.setflags(LibmagicRb::MAGIC_RAW)
+		# => 256
+
+		> cookie.check
+		# => "directory"
+
+		#### Similarly you can also do this ####
+
+		> cookie.mode = LibmagicRb::MAGIC_MIME
+		# => 1040
+
+		> cookie.check
+		# => "inode/directory; charset=binary"
+
+		#### Close the cookie when done ####
+		> cookie.close
+		# => #<LibmagicRb:0x00005583732e1070 @closed=true, @db=nil, @file=".", @mode=256>
+*/
+
 VALUE _setflagsGlobal_(volatile VALUE self, volatile VALUE flags) {
 	unsigned int flag = NUM2UINT(flags) ;
 

data/ext/libmagic/magic.c

@@ -53,7 +53,21 @@ static rb_data_type_t fileType = {
 #include "validations.h"
 #include "func.h"
 
-VALUE _check_(volatile VALUE obj, volatile VALUE args) {
+/*
+	Directly check a file with LibmagicRb, without creating any sort of cookies:
+
+		LibmagicRb.check(file: '/tmp/', db: '/usr/share/file/misc/magic.mgc', mode: LibmagicRb::MAGIC_CHECK) # => "sticky, directory"
+
+	[file] The key `file:` is the filename to check. Should be a string
+
+	[db] The key `db:` can be left as nil. Or you can give it the path of the current magic database.
+
+	[mode] The key `mode` can be any of the LibmagicRb.lsmodes().
+	To combine modes you can use `|`. For example:
+	`mode: LibmagicRb::MAGIC_CHECK | LibmagicRb::MAGIC_SYMLINK | Libmagic_MAGIC_MIME`
+	If `mode` key is nil, it will default to `MAGIC_MIME | MAGIC_CHECK | MAGIC_SYMLINK`
+*/
+static VALUE _check_(volatile VALUE obj, volatile VALUE args) {
 	if(!RB_TYPE_P(args, T_HASH)) {
 		rb_raise(rb_eArgError, "Expected hash as argument.") ;
 	}
@@ -111,6 +125,43 @@ VALUE _check_(volatile VALUE obj, volatile VALUE args) {
 	return retVal ;
 }
 
+/*
+	Intializes a magic cookie that can be used multiple times.
+	The benefit of this is to assgign various cookies and change flags of each cookie.
+
+	For example:
+
+		> cookie = LibmagicRb.new(file: '/tmp')
+		# => #<LibmagicRb:0x000055810139f738 @closed=false, @db=nil, @file="/tmp", @mode=1106>
+
+		> cookie.check
+		# => "inode/directory; charset=binary"
+
+		> cookie.setflags(LibmagicRb::MAGIC_RAW)
+		# => 256
+
+		> cookie.check
+		# => "sticky, directory"
+
+		> cookie2 = LibmagicRb.new(file: '/usr/share/dict/words')
+		# => #<LibmagicRb:0x000055810190a060 @closed=false, @db=nil, @file="/usr/share/dict/words", @mode=1106>
+
+		> cookie2.check
+		# => "text/plain; charset=utf-8"
+
+		> cookie.close
+		# => #<LibmagicRb:0x000055810139f738 @closed=true, @db=nil, @file="/tmp", @mode=256>
+
+		> cookie.closed?
+		# => true
+
+		> cookie2.closed?
+		# => false
+
+	Here in this example, we can't use cookie, but cookie2 is a different magic_t wrapper, so we can continue using that.
+	Flags/modes applied to cookie, will not affect cookie2 as well. Think of them as totally different containers.
+	Of course, you must close cookies when you don't need them. Otherwise it can use memories unless GC is triggered.
+*/
 VALUE rb_libmagicRb_initialize(volatile VALUE self, volatile VALUE args) {
 	// Database Path
 	if(!RB_TYPE_P(args, T_HASH)) {
@@ -174,6 +225,10 @@ void Init_main() {
 	/*
 	* Libmagic Errors
 	*/
+
+	/*
+		Adds ability to check mime-type of a file using the libmagic (magic(4)). It uses native extensions and it's quite performant.
+	*/
 	VALUE cLibmagicRb = rb_define_class("LibmagicRb", rb_cObject) ;
 
 	rb_eFileNotFoundError = rb_define_class_under(cLibmagicRb, "FileNotFound", rb_eRuntimeError) ;
@@ -188,9 +243,15 @@ void Init_main() {
 	modes(cLibmagicRb) ;
 	params(cLibmagicRb) ;
 
+
 	#if MAGIC_VERSION > 525
 		char version[6] ;
 		sprintf(version, "%0.2f", magic_version() / 100.0) ;
+
+		/*
+			LibmagicRb::MAGIC_VERSION returns the magic version of the library.
+			For older libmagic version, this can be undefined, so this method will return "0" instead.
+		*/
 		rb_define_const(cLibmagicRb, "MAGIC_VERSION", rb_str_new_cstr(version)) ;
 	#else
 		rb_define_const(cLibmagicRb, "MAGIC_VERSION", rb_str_new_cstr("0")) ;

data/lib/libmagic_rb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class LibmagicRb
-	VERSION = "0.1.2-beta"
+	VERSION = "0.1.2-gamma"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libmagic_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.2.pre.beta
+  version: 0.1.2.pre.gamma
 platform: ruby
 authors:
 - Cybergizer
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-05 00:00:00.000000000 Z
+date: 2021-09-06 00:00:00.000000000 Z
 dependencies: []
 description: Check filetype with libmagic
 email: