= Mahoro < Object -------------------------------------------------------------------------------- Mahoro is a simple interface to libmagic. Common use cases: # initialize a Mahoro object for reading MIME types mahoro_obj = Mahoro.new(Mahoro::MIME) # get the MIME type of a file on disk # This is ideal for large files which you do not need to # read in their entirety. mahoro_obj.file('/path/to/file.c') -> 'text/x-c' # get the MIME type of a string buffer # This is only ideal if you already have the buffer in # memory or intend to process it soon str = File.read('/path/to/file.c') mahoro_obj.buffer(str) -> 'text/x-c' # switch the Mahoro object to return an ASCII description mahoro_obj.flags = Mahoro::NONE # Similar to the above example, but the Mahoro object # now returns a textual description mahoro_obj.file('/path/to/file.c') -> 'ASCII C program text' # Similar to the above example, but the Mahoro object # now returns a textual description str = File.read('/path/to/file.c') mahoro_obj.buffer(str) -> 'ASCII C program text' Mahoro is not thread-safe by default, see Mahoro::ThreadSafe for making this module thread-safe. More information about libmagic: https://en.wikipedia.org/wiki/Libmagic Source code is available via git: git clone https://yhbt.net/mahoro.git And viewable with a web browser via cgit: https://yhbt.net/mahoro.git Eric Wong is the current maintainer of Mahoro. Plain-text comments, questions, bug reports, patches and pull requests are all highly welcome on the public inbox: mahoro@public-inbox.org Please generate patches using the "git format-patch" command. Use of "git send-email" to send a patch is recommended. For reviewed patches, you may also send a pull request formatted using the "git request-pull" command. Do not expect Eric to read HTML email under any circumstances. -------------------------------------------------------------------------------- = Constants: APPLE: Return both Apple creator and type. This constant may not be defined on older systems. CHECK: Check the magic database for consistency and print warnings to stderr COMPRESS: Check inside compressed files CONTINUE: Return all matches DEBUG: print debugging messages to stderr DEVICES: Look at the contents of devices ERROR: Treat operating system errors while trying to open files and follow symlinks as real errors, instead of printing them in the magic buffer. MIME: return both MIME type and encoding MIME_ENCODING: Return a MIME encoding, instead of a textual description. This constant may not be defined on older systems. MIME_TYPE: Return only the MIME type This constant may not be defined on older systems. NONE: No special handling, the default NO_CHECK_APPTYPE: Don't check application type (EMX only). This constant may not be defined on older systems. NO_CHECK_COMPRESS: Don't check for or inside compressed files. This constant may not be defined on older systems. NO_CHECK_ELF: Don't check for ELF details. This constant may not be defined on older systems. NO_CHECK_ENCODING: Don't check for text encodings. This constant may not be defined on older systems. NO_CHECK_SOFT: Don't consult magic files. This constant may not be defined on older systems. NO_CHECK_TAR: Don't examine tar files. This constant may not be defined on older systems. NO_CHECK_TEXT: Don't check for various types of ASCII text files. This constant may not be defined on older systems. NO_CHECK_TOKENS: Don't check for known tokens inside ASCII files. This constant may not be defined on older systems. PRESERVE_ATIME: preserve access time of files analyzed RAW: Don't translate unprintable characters to a \ooo octal representation SYMLINK: Follow symlinks = Class methods: compile new = Instance methods: buffer compile file flags= load valid? = Mahoro.new -------------------------------------------------------------------------------- Mahoro.new(flags = Mahoro::NONE, path = nil) -> mahoro_obj -------------------------------------------------------------------------------- Create and initialize a new Mahoro object. flags may be one or more of any combination of the Mahoro: constants supported by Mahoro#flags=. path (if not nil) is a colon-separated list of database files, see Mahoro#load. If path is not given (or nil), the default database is used. Consult your libmagic(3) documentation for the location of that file as it varies by installation. = Mahoro#file -------------------------------------------------------------------------------- mahoro_obj.file(filename) -> String -------------------------------------------------------------------------------- Returns a textual description of the contents of the filename given. Use Mahoro#buffer instead of this method if the contents of your file is already in memory. Raises Mahoro::Error on failed lookups. = Mahoro#buffer -------------------------------------------------------------------------------- mahoro_obj.buffer(buffer) -> String -------------------------------------------------------------------------------- Returns a textual description of the contents of the buffer given. buffer should be a String object. Use Mahoro#file instead of this method if the contents is not already in memory (and possibly too large to fit into memory). Raises Mahoro::Error on failed lookups. = Mahoro#flags= -------------------------------------------------------------------------------- mahoro_obj.flags = flags -------------------------------------------------------------------------------- Change the behavior of an already-initialized Mahoro object. The behavior of a Mahoro object is specified at load time, but may be changed after-the-fact. flags is a bitwise (OR) mask of one or more of the following constants in the Mahoro namespace: * APPLE * CHECK * COMPRESS * CONTINUE * DEBUG * DEVICES * ERROR * MIME * MIME_ENCODING * MIME_TYPE * NONE * NO_CHECK_APPTYPE * NO_CHECK_COMPRESS * NO_CHECK_ELF * NO_CHECK_ENCODING * NO_CHECK_SOFT * NO_CHECK_TAR * NO_CHECK_TEXT * NO_CHECK_TOKENS * PRESERVE_ATIME * RAW * SYMLINK = Mahoro#valid? -------------------------------------------------------------------------------- mahoro_obj.check(path = nil) -> true or false -------------------------------------------------------------------------------- This is used to check the validity of entries in the colon separated database files passed in as path. If path is not passed (or nil), this will check the default database. = Mahoro#compile -------------------------------------------------------------------------------- mahoro_obj.compile(path) -> true -------------------------------------------------------------------------------- Compile the the colon separated list of database files passed in as path. It returns true on success and raises Mahoro::Error on failure. Compiled files created are named from the File.basename of each file argument with ".mgc" appended to it. There is no need to use this function if you are using the default magic(5) database on your operating system. This is only needed if you require additional magic not in the default magic database. Users of this method are likely to need Mahoro#load (and vice-versa). = Mahoro.compile -------------------------------------------------------------------------------- Mahoro.compile(path) -> true -------------------------------------------------------------------------------- This is a wrapper around the Mahoro#compile instance method, but does not require an existing Mahoro object. Use the instance method unless you only need to test the validity of a magic(5) database. -------------------------------------------------------------------------------- mahoro_obj.compile(path) -> true -------------------------------------------------------------------------------- Compile the the colon separated list of database files passed in as path. It returns true on success and raises Mahoro::Error on failure. Compiled files created are named from the File.basename of each file argument with ".mgc" appended to it. There is no need to use this function if you are using the default magic(5) database on your operating system. This is only needed if you require additional magic not in the default magic database. Users of this method are likely to need Mahoro#load (and vice-versa). = Mahoro::ThreadSafe -------------------------------------------------------------------------------- Adds thread-safety to an existing Mahoro object. magic_t cookies of libmagic are not thread-safe by default, thus Mahoro is not thread-safe by default, either. For applications using persistent thread pools, this module is NOT recommended. Instead, it is best to create thread-local instances of (non-thread-safe) Mahoro for best performance. This is only intended for applications using Mahoro which meet the following requirements: 1) uses short-lived threads 2) does not need high concurrency for Mahoro operations Usage example: require "mahoro/thread_safe" # create a Mahoro object as usual mahoro_obj = Mahoro.new(...) # enable thread-safety mahoro_obj.extend Mahoro::ThreadSafe # mahoro_obj may now be used by multiple threads with automatic # mutual exclusion (the following example is safe, but not concurrent). Thread.new { mahoro_obj.file("/path/to/some_file") } Thread.new { mahoro_obj.file("/path/to/some_other_file") } # Real concurrency must be achieved by using different Mahoro objects # in different threads. As of Mahoro v0.4, Mahoro releases the GVL # on (Matz) Ruby 1.9 and later. --------------------------------------------------------------------------------