From 7027149ddd5d2cafb8483e88fcfd9e5b49ed141f Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Thu, 4 Apr 2013 19:16:18 +0000 Subject: add RDoc documentation This should help developers find their way in case they are offline and unable to access the (unmaintained) website. --- .gitignore | 8 +++ doc.mk | 26 +++++++++ mahoro.c | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 209 insertions(+) create mode 100644 .gitignore create mode 100644 doc.mk diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..63dfd4f --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +*.gem +*.log +*.o +*.so +Makefile +/doc +/.ri +mahoro.txt diff --git a/doc.mk b/doc.mk new file mode 100644 index 0000000..9d9af9b --- /dev/null +++ b/doc.mk @@ -0,0 +1,26 @@ +all:: + +.ri/created.rid: mahoro.c + rdoc --ri -o $(@D) $< + +order = +order += Mahoro +order += Mahoro.new +order += Mahoro\#file +order += Mahoro\#buffer +order += Mahoro\#flags= +order += Mahoro\#valid? +order += Mahoro\#compile +order += Mahoro.compile + +mahoro.txt: .ri/created.rid + ( \ + for i in $(order); \ + do \ + ri --no-standard-docs -T -d .ri -w 80 "$$i" \ + | col -b \ + | grep -vF $(CURDIR)/.ri; \ + done \ + ) > $@ + +all:: mahoro.txt diff --git a/mahoro.c b/mahoro.c index 689ca0e..fe02cf6 100644 --- a/mahoro.c +++ b/mahoro.c @@ -1,5 +1,9 @@ /* * This file is Public Domain. + * + * Note: The current maintainer (Eric Wong) respects and preserves the + * original coding style of the original author (Shu-yu Guo) in case + * he ever chooses to return to this project. */ #include @@ -15,6 +19,7 @@ static VALUE cMahoro; static VALUE eMahoroError; +/* :nodoc: called automatically by GC */ static void mahoro_free(ptr) void *ptr; @@ -23,6 +28,7 @@ mahoro_free(ptr) magic_close((magic_t)ptr); } +/* :nodoc: called automatically on Mahoro#initialize */ static VALUE mahoro_allocate(klass) VALUE klass; @@ -30,6 +36,20 @@ mahoro_allocate(klass) return Data_Wrap_Struct(klass, 0, mahoro_free, 0); } +/* + * call-seq: + * 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. + */ static VALUE mahoro_initialize(argc, argv, self) int argc; @@ -65,6 +85,15 @@ mahoro_initialize(argc, argv, self) return self; } +/* + * call-seq: + * 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. + */ static VALUE mahoro_file(self, path) VALUE self, path; @@ -79,6 +108,16 @@ mahoro_file(self, path) return rb_str_new2(msg); } +/* + * call-seq: + * 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. + */ static VALUE mahoro_buffer(self, input) VALUE self, input; @@ -96,6 +135,39 @@ mahoro_buffer(self, input) return rb_str_new2(msg); } +/* + * call-seq: + * 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 + */ static VALUE mahoro_set_flags(self, flags) VALUE self, flags; @@ -105,6 +177,14 @@ mahoro_set_flags(self, flags) return INT2FIX(magic_setflags(cookie, FIX2INT(flags))); } +/* + * call-seq: + * 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. + */ static VALUE mahoro_check(argc, argv, self) int argc; @@ -129,6 +209,21 @@ mahoro_check(argc, argv, self) } } +/* + * call-seq: + * 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). + */ static VALUE mahoro_compile(self, path) VALUE self, path; @@ -142,6 +237,14 @@ mahoro_compile(self, path) return Qtrue; } +/* + * call-seq: + * 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. + */ static VALUE mahoro_s_compile(klass, path) VALUE klass, path; @@ -151,6 +254,24 @@ mahoro_s_compile(klass, path) return mahoro_compile(m, path); } +/* + * call-seq: + * mahoro_obj.load(path) -> mahoro_obj + * + * Used to load the the colon-separated list of database files (+path+). + * The ".mgc" suffix will be added to each filename where appropriate. + * This will raise Mahoro::Error on failure. + * + * 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. + * + * The default database file is named by the MAGIC environment variable. + * Consult your libmagic installation documentation for the location of + * your default database file name. + * + * Users of this method are likely to need Mahoro#compile (and vice-versa). + */ static VALUE mahoro_load(self, path) VALUE self, path; @@ -166,6 +287,60 @@ mahoro_load(self, path) void Init_mahoro(void) { + /* + * 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' + * + * More information about libmagic: + * https://en.wikipedia.org/wiki/Libmagic + * + * Source code is available via git: + * git clone git://bogomips.org/mahoro.git + * + * And viewable with a web browser via cgit: + * http://bogomips.org/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 mailing list: + * mahoro@librelist.org + * + * You may contact Eric privately at normalperson@yhbt.net + * + * 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. + */ cMahoro = rb_define_class("Mahoro", rb_cObject); eMahoroError = rb_define_class_under(cMahoro, "Error", rb_eStandardError); -- cgit v1.2.3-24-ge0c7