gettextpo 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3ac361edc71b888a2d229cde89bb5502d51a46b3461a8d335879a5a4234141c
-  data.tar.gz: fc2308b078480e83ba35408a8b37eb2044bde4066b73390946507fba6da7d1bd
+  metadata.gz: 939f88fac034fa8ae14d06943e12163df3a34ca1797c625c7d5c6c591c18756b
+  data.tar.gz: 972a70b2e9f8c5c623e839a7e8c5d54e2b95cd62d1fe0d3f6c26fe4f3d53b429
 SHA512:
-  metadata.gz: c987dabcd215ecaa0faaf18958c62337443c838432eb45b7f154132aa1c7ebe11cb5771cc7b0e17fd9317de73e2c3c298aea28baca61c5305f5ffe4f1251d934
-  data.tar.gz: 616e8b974e467b8bfbb11f8b316d937769bcead95bdf2785c0bd84767e8589a8e13e8ed41fd6bdc8fa8e511d15491130995f739506f96bf7a0d9c0116b001566
+  metadata.gz: 9d1f6fbf4c89921e78629b4f23b2f120671fb04db1dfcb09d73db5f28c6396d37f4bf792a9f69e034ce5ab077ac5c79b3d310beb0deb7707966be306065e8a2f
+  data.tar.gz: b9bdbc78813ad3e20c783e5a2745297624c7c629fc2b97a55081a5b7f904fa3be99df556dc0b6664199e4d71e2e4e02c0d59340129f6f273ff3ae2e8607de3ad

data/.dir-locals.el

@@ -1,5 +1,6 @@
 ;;; Directory Local Variables            -*- no-byte-compile: t -*-
 ;;; For more information see (info "(emacs) Directory Variables")
 
-((nil . ((eval . (progn (add-to-list 'grep-find-ignored-directories "tmp")
+((nil . ((eval . (progn (require 'grep)
+                        (add-to-list 'grep-find-ignored-directories "tmp")
                         (add-to-list 'grep-find-ignored-directories "doc"))))))

data/.env.example

@@ -0,0 +1,2 @@
+MRUBY_SRC=/path/to/mruby
+DEVELOP_MRUBY=no

data/.envrc

@@ -1,3 +1,18 @@
+# Copyright (C) 2026  gemmaro
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
 use guix \
     clang \
     gcc-toolchain \
@@ -7,5 +22,17 @@ use guix \
     gettext \
     gdb
 
-path_add C_INCLUDE_PATH "$(ruby -e "puts RbConfig::CONFIG['rubyhdrdir']")"
-path_add C_INCLUDE_PATH "$(ruby -e "puts RbConfig::CONFIG['rubyarchhdrdir']")"
+dotenv
+
+if [ "$DEVELOP_MRUBY" != 'yes' ]
+then
+    # CRuby
+    path_add C_INCLUDE_PATH "$(ruby -e "puts RbConfig::CONFIG['rubyhdrdir']")"
+    path_add C_INCLUDE_PATH "$(ruby -e "puts RbConfig::CONFIG['rubyarchhdrdir']")"
+else
+    # mruby
+    env_vars_required MRUBY_SRC
+    path_add C_INCLUDE_PATH include
+    path_add C_INCLUDE_PATH "$MRUBY_SRC/include"
+    path_add C_INCLUDE_PATH "$MRUBY_SRC/build/host/include"
+fi

data/.rdoc_options

@@ -4,3 +4,4 @@ exclude:
   - bin
   - Rakefile
   - Gemfile
+  - vendor

data/CHANGELOG.md

@@ -1,7 +1,19 @@
 # Change log of Ruby GettextPO gem
 
-## [Unreleased]
+## Unreleased
 
-## [0.1.0] - 2026-03-07
+## CRuby version 0.1.2 and mruby version 0.1.0 - 2026-03-11
+
+- Add mruby version.
+- CRuby: Fix exception error 2 handling.
+
+## 0.1.1 - 2026-03-09
+
+- Fix dangling pointer issue.
+- Add libgettextpo version constant.
+- Add severities constants.
+- Improve API document.
+
+## 0.1.0 - 2026-03-07
 
 - Initial release

data/README.md

@@ -2,8 +2,9 @@
 
 This is a Ruby library for the GNU gettext PO files.  This is a C
 binding of the libgettextpo library, which is provided by the GNU
-gettext package.  It is designed to promote Ruby's idiomatic coding
-style while avoiding memory leaks.
+gettext package.  The API of this gem is designed to promote Ruby's
+idiomatic coding style while avoiding memory safety.  Currently this
+supports both CRuby and mruby.
 
 ## Installation
 
@@ -23,17 +24,22 @@ apt search libgettextpo
 #   process PO files - shared library
 ```
 
-Install the gem and add to the application's `Gemfile` by executing:
+For CRuby:
 
-```bash
-bundle add gettextpo
-```
+* Install the gem and add to the application's `Gemfile` by executing:
 
-If Bundler is not being used to manage dependencies, install the gem by executing:
+  ```bash
+  bundle add gettextpo
+  ```
 
-```bash
-gem install gettextpo
-```
+* If Bundler is not being used to manage dependencies, install the gem by executing:
+
+  ```bash
+  gem install gettextpo
+  ```
+
+For mruby, modify `build_config.rb` as you like, set `MRUBY_SRC` to
+mruby source repository, and run `./bin/compile` or `./bin/test`.
 
 ## Usage
 
@@ -55,15 +61,12 @@ GettextPO::File.read(po_path).message_iterator.each do |message|
 end
 ```
 
-Please refer to the API documentation and test cases for details.
-
-## Development
+Please refer to the [API documentation][api] and test cases for
+details.  The mruby version has same API.
 
-`./bin/debug` to debug when segmentation fault.
+[api]: https://gemmaro.github.io/ruby-gettextpo/
 
-References: [RubyのC APIの手引き 決定版][def], [Developers'
-documentation for Ruby][dev], [Rubyの拡張ライブラリの作り方][ext],
-[library rdoc/parser/c][parser], and [library rdoc][rdoc].
+## Development
 
 After checking out the repo, run `bin/setup` to install
 dependencies. Then, run `rake test` to run the tests. You can also run
@@ -76,16 +79,52 @@ install`.  To release a new version, update the version number in
 create a git tag for the version, push git commits and the created
 tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-[def]: https://gemmaro.github.io/emberb/
-[dev]: https://docs.ruby-lang.org/capi/en/master/index.html
-[ext]: https://docs.ruby-lang.org/en/master/extension_ja_rdoc.html
-[parser]: https://docs.ruby-lang.org/ja/latest/library/rdoc=2fparser=2fc.html
-[rdoc]: https://docs.ruby-lang.org/ja/latest/library/rdoc.html
+File structure:
+
+```text
+  bin               : script ifles
+  build_config.rb   : for mruby
+* build_config.rb.lock
+  CHANGELOG.md
+  COPYING
+* doc               : generated by RDoc from CRuby sources
+  ext               : for CRuby
+  Gemfile           : for CRuby
+  gettextpo.gemspec : for CRuby
+  include           : for mruby
+  lib               : for CRuby
+  mrbgem.rake       : for mruby
+  mrblib            : for mruby
+* pkg               : generated by RubyGem
+  Rakefile          : for CRuby
+  README.md
+- sample.rb         : for debug purpose especially with GDB
+  sig               : for CRuby
+  src               : for mruby
+  test              : common test cases for both CRuby and mruby
+  test.cruby        : CRuby specific tests
+* tmp
+- .env
+  .env.example
+  .envrc            : Direnv config
+  .clang-format
+  .dir-locals.el    : Emacs config
+  .gitignore
+
+* generated files
+- ignored by version control
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on Disroot at
-<https://git.disroot.org/gemmaro/ruby-gettextpo>.
+Bug reports and pull requests are welcome on [Disroot][disroot].
+
+Other links:
+
+* [RubyGems](https://rubygems.org/gems/gettextpo)
+* [GitHub repository](https://github.com/gemmaro/ruby-gettextpo)
+
+[disroot]: https://git.disroot.org/gemmaro/ruby-gettextpo
 
 ## License
 

data/Rakefile

@@ -19,9 +19,9 @@ require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
+  t.libs << "test.cruby"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.test_files = FileList["test.cruby/**/*_test.rb"]
 end
 
 require "rake/extensiontask"

data/build_config.rb

@@ -0,0 +1,27 @@
+# Copyright (C) 2026  gemmaro
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+MRuby::Build.new do |conf|
+  toolchain :gcc
+  conf.gem File.expand_path(File.dirname(__FILE__))
+  conf.linker.libraries << 'gettextpo'
+  conf.enable_test
+  conf.gem core: 'hal-posix-io'
+  conf.gem core: 'mruby-bin-mruby'
+  conf.gem core: 'mruby-bin-mirb'
+  conf.cc do |cc|
+    cc.flags << '-O0'
+  end
+end

data/ext/gettextpo/gettextpo.c

@@ -1,5 +1,4 @@
-/**
- * Copyright (C) 2026  gemmaro
+/* Copyright (C) 2026  gemmaro
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -15,36 +14,26 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/* FilePos, Message, and MessageIterator each hold a @file instance
+ * variable (ivar) pointing to the GettextPO::File object that owns
+ * the underlying po_file_t.  This prevents the File object from being
+ * garbage collected while any of these objects are still alive, which
+ * would otherwise cause their po_file_t pointers to become dangling.
+ * When allocating one of these objects, @file must be propagated from
+ * the parent object: File -> MessageIterator -> Message -> FilePos.
+ */
+
 #include "gettextpo.h"
-#include <gettext-po.h>
-#include <ruby/internal/anyargs.h>
-#include <ruby/internal/arithmetic/int.h>
 #include <ruby/internal/core/rdata.h>
-#include <ruby/internal/core/rstring.h>
-#include <ruby/internal/core/rtypeddata.h>
-#include <ruby/internal/eval.h>
-#include <ruby/internal/globals.h>
-#include <ruby/internal/intern/array.h>
-#include <ruby/internal/intern/hash.h>
-#include <ruby/internal/intern/object.h>
-#include <ruby/internal/intern/proc.h>
-#include <ruby/internal/intern/range.h>
-#include <ruby/internal/intern/string.h>
-#include <ruby/internal/intern/vm.h>
-#include <ruby/internal/module.h>
-#include <ruby/internal/scan_args.h>
-#include <ruby/internal/special_consts.h>
-#include <ruby/internal/symbol.h>
-#include <ruby/internal/value.h>
-#include <stdbool.h>
-#include <stddef.h>
-#include <stdlib.h>
-#include <time.h>
+#include <ruby/internal/intern/variable.h>
+
+#define ERROR                                                                 \
+  rb_const_get (rb_const_get (rb_cObject, rb_intern ("GettextPO")),           \
+                rb_intern ("Error"))
 
 VALUE rb_cMessage;
 VALUE rb_cMessageIterator;
 VALUE rb_cFilePos;
-VALUE rb_eError;
 
 /* ********** error ********** */
 
@@ -53,6 +42,7 @@ static struct
   bool error;
   VALUE *user_xerror;
   VALUE *user_xerror2;
+  VALUE *file;
 } gettextpo_xerror_context = {};
 
 static void
@@ -61,6 +51,7 @@ gettextpo_xerror_context_reset (void)
   gettextpo_xerror_context.error = false;
   gettextpo_xerror_context.user_xerror = NULL;
   gettextpo_xerror_context.user_xerror2 = NULL;
+  gettextpo_xerror_context.file = NULL;
 }
 
 static void
@@ -79,6 +70,8 @@ gettextpo_xerror (const int severity, const po_message_t message,
     {
       VALUE message_value = rb_obj_alloc (rb_cMessage);
       DATA_PTR (message_value) = message;
+      rb_ivar_set (message_value, rb_intern ("@file"),
+                   *gettextpo_xerror_context.file);
       rb_hash_aset (kwargs, ID2SYM (rb_intern ("message")), message_value);
     }
   if (filename)
@@ -120,6 +113,8 @@ gettextpo_xerror2 (const int severity, const po_message_t message1,
     {
       VALUE message_value1 = rb_obj_alloc (rb_cMessage);
       DATA_PTR (message_value1) = message1;
+      rb_ivar_set (message_value1, rb_intern ("@file"),
+                   *gettextpo_xerror_context.file);
       rb_hash_aset (kwargs, ID2SYM (rb_intern ("message1")), message_value1);
     }
   if (filename1)
@@ -138,6 +133,8 @@ gettextpo_xerror2 (const int severity, const po_message_t message1,
     {
       VALUE message_value2 = rb_obj_alloc (rb_cMessage);
       DATA_PTR (message_value2) = message2;
+      rb_ivar_set (message_value2, rb_intern ("@file"),
+                   *gettextpo_xerror_context.file);
       rb_hash_aset (kwargs, ID2SYM (rb_intern ("message2")), message_value2);
     }
   if (filename2)
@@ -154,7 +151,7 @@ gettextpo_xerror2 (const int severity, const po_message_t message1,
                   rb_str_new_cstr (message_text2));
   VALUE args = rb_ary_new ();
   rb_ary_push (args, kwargs);
-  rb_proc_call_kw (*gettextpo_xerror_context.user_xerror, args,
+  rb_proc_call_kw (*gettextpo_xerror_context.user_xerror2, args,
                    RB_PASS_KEYWORDS);
   if (severity == PO_SEVERITY_FATAL_ERROR)
     abort ();
@@ -423,7 +420,7 @@ gettextpo_po_message_m_format_set (int argc, VALUE *argv, VALUE self)
   bool opposite = !RB_UNDEF_P (kwargs_vals[0]) && RB_TEST (kwargs_vals[0]);
   bool remove = !RB_UNDEF_P (kwargs_vals[1]) && RB_TEST (kwargs_vals[1]);
   if (opposite && remove)
-    rb_raise (rb_eError, "opposite and remove cannot be set at the same time");
+    rb_raise (ERROR, "opposite and remove cannot be set at the same time");
   po_message_set_format (DATA_PTR (self), StringValueCStr (format),
                          opposite ? 0 : (remove ? -1 : 1));
   return Qnil;
@@ -470,6 +467,8 @@ gettextpo_po_message_m_filepos (VALUE self, VALUE index)
     {
       VALUE filepos = rb_obj_alloc (rb_cFilePos);
       DATA_PTR (filepos) = pos;
+      rb_ivar_set (filepos, rb_intern ("@file"),
+                   rb_ivar_get (self, rb_intern ("@file")));
       return filepos;
     }
   else
@@ -500,7 +499,7 @@ gettextpo_po_message_m_add_filepos (VALUE self, VALUE file, VALUE start_line)
 /**
  * call-seq: check_all (iterator, xerror: nil, xerror2: nil)
  *
- * See also GettextPO::File.read.
+ * See also GettextPO::File.read for exception error handlings.
  */
 VALUE
 gettextpo_po_message_m_check_all (int argc, VALUE *argv, VALUE self)
@@ -511,6 +510,8 @@ gettextpo_po_message_m_check_all (int argc, VALUE *argv, VALUE self)
   VALUE kwargs_vals[] = { Qundef, Qundef };
   rb_get_kwargs (kwargs, kwargs_ids, 0, 2, kwargs_vals);
   gettextpo_xerror_context_reset ();
+  VALUE file = rb_ivar_get (self, rb_intern ("@file"));
+  gettextpo_xerror_context.file = &file;
   if (kwargs_vals[0] != Qundef)
     gettextpo_xerror_context.user_xerror = &kwargs_vals[0];
   if (kwargs_vals[1] != Qundef)
@@ -518,14 +519,14 @@ gettextpo_po_message_m_check_all (int argc, VALUE *argv, VALUE self)
   po_message_check_all (DATA_PTR (self), DATA_PTR (iterator),
                         &gettextpo_xerror_handler);
   if (gettextpo_xerror_context.error)
-    rb_raise (rb_eError, "check all for message failed");
+    rb_raise (ERROR, "check all for message failed");
   return Qnil;
 }
 
 /**
  * call-seq: check_format (xerror: nil, xerror2: nil)
  *
- * See also GettextPO::File.read.
+ * See also GettextPO::File.read for exception error handlings.
  */
 VALUE
 gettextpo_po_message_m_check_format (int argc, VALUE *argv, VALUE self)
@@ -536,13 +537,15 @@ gettextpo_po_message_m_check_format (int argc, VALUE *argv, VALUE self)
   VALUE kwargs_vals[] = { Qundef, Qundef };
   rb_get_kwargs (kwargs, kwargs_ids, 0, 2, kwargs_vals);
   gettextpo_xerror_context_reset ();
+  VALUE file = rb_ivar_get (self, rb_intern ("@file"));
+  gettextpo_xerror_context.file = &file;
   if (kwargs_vals[0] != Qundef)
     gettextpo_xerror_context.user_xerror = &kwargs_vals[0];
   if (kwargs_vals[1] != Qundef)
     gettextpo_xerror_context.user_xerror2 = &kwargs_vals[1];
   po_message_check_format (DATA_PTR (self), &gettextpo_xerror_handler);
   if (gettextpo_xerror_context.error)
-    rb_raise (rb_eError, "check format for message failed");
+    rb_raise (ERROR, "check format for message failed");
   return Qnil;
 }
 
@@ -562,6 +565,10 @@ gettextpo_po_file_alloc (VALUE self)
   return TypedData_Wrap_Struct (self, &gettextpo_po_file_type, NULL);
 }
 
+/**
+ * See also #message_iterator and GettextPO::MessageIterator#insert
+ * methods for the further manipulations.
+ */
 VALUE
 gettextpo_po_file_m_initialize (VALUE self)
 {
@@ -577,7 +584,8 @@ gettextpo_po_file_m_initialize (VALUE self)
  * +multiline+, and +message_text+.  +xerror2+ takes keyword arguments
  * +severity+, +message1+, +filename1+, +lineno1+, +column1+,
  * +multiline1+, +message_text1+, +message2+, +filename2+, +lineno2+,
- * +column2+, +multiline2+, and +message_text2+.
+ * +column2+, +multiline2+, and +message_text2+.  See also GettextPO
+ * for general exception handlings.
  */
 VALUE
 gettextpo_po_file_m_read (int argc, VALUE *argv, VALUE klass)
@@ -588,22 +596,25 @@ gettextpo_po_file_m_read (int argc, VALUE *argv, VALUE klass)
   VALUE kwargs_vals[] = { Qundef, Qundef };
   rb_get_kwargs (kwargs, kwargs_ids, 0, 2, kwargs_vals);
   gettextpo_xerror_context_reset ();
+  VALUE self = rb_obj_alloc (klass);
+  gettextpo_xerror_context.file = &self;
   if (kwargs_vals[0] != Qundef)
     gettextpo_xerror_context.user_xerror = &kwargs_vals[0];
   if (kwargs_vals[1] != Qundef)
     gettextpo_xerror_context.user_xerror2 = &kwargs_vals[1];
-  VALUE self = rb_obj_alloc (klass);
+  /* TODO: po_file_read can return NULL when not found?  Also check
+     null at file free. */
   DATA_PTR (self)
       = po_file_read (StringValueCStr (filename), &gettextpo_xerror_handler);
   if (gettextpo_xerror_context.error)
-    rb_raise (rb_eError, "failed to read");
+    rb_raise (ERROR, "failed to read");
   return self;
 }
 
 /**
  * call-seq: write (filename, xerror: nil, xerror2: nil)
  *
- * See also ::read.
+ * See also ::read for exception error handlings.
  */
 VALUE
 gettextpo_po_file_m_write (int argc, VALUE *argv, VALUE self)
@@ -614,6 +625,7 @@ gettextpo_po_file_m_write (int argc, VALUE *argv, VALUE self)
   VALUE kwargs_vals[] = { Qundef, Qundef };
   rb_get_kwargs (kwargs, kwargs_ids, 0, 2, kwargs_vals);
   gettextpo_xerror_context_reset ();
+  gettextpo_xerror_context.file = &self;
   if (kwargs_vals[0] != Qundef)
     gettextpo_xerror_context.user_xerror = &kwargs_vals[0];
   if (kwargs_vals[1] != Qundef)
@@ -621,7 +633,7 @@ gettextpo_po_file_m_write (int argc, VALUE *argv, VALUE self)
   po_file_write (DATA_PTR (self), StringValueCStr (filename),
                  &gettextpo_xerror_handler);
   if (gettextpo_xerror_context.error)
-    rb_raise (rb_eError, "failed to write");
+    rb_raise (ERROR, "failed to write");
   return Qnil;
 }
 
@@ -646,11 +658,12 @@ gettextpo_po_file_m_message_iterator (int argc, VALUE *argv, VALUE self)
   VALUE iterator = rb_obj_alloc (rb_cMessageIterator);
   DATA_PTR (iterator) = po_message_iterator (
       DATA_PTR (self), NIL_P (domain) ? NULL : StringValueCStr (domain));
+  rb_ivar_set (iterator, rb_intern ("@file"), self);
   return iterator;
 }
 
 /**
- * call-seq: domain_header (domain)
+ * call-seq: domain_header (domain = nil)
  *
  * +domain+ can be +nil+ to use a default.  Possibly returns +nil+.
  *
@@ -669,7 +682,7 @@ gettextpo_po_file_m_domain_header (int argc, VALUE *argv, VALUE self)
 /**
  * call-seq: check_all (xerror: nil, xerror2: nil)
  *
- * See also ::read.
+ * See also ::read for exception error handlings.
  */
 VALUE
 gettextpo_po_file_m_check_all (int argc, VALUE *argv, VALUE self)
@@ -680,13 +693,14 @@ gettextpo_po_file_m_check_all (int argc, VALUE *argv, VALUE self)
   VALUE kwargs_vals[] = { Qundef, Qundef };
   rb_get_kwargs (kwargs, kwargs_ids, 0, 2, kwargs_vals);
   gettextpo_xerror_context_reset ();
+  gettextpo_xerror_context.file = &self;
   if (kwargs_vals[0] != Qundef)
     gettextpo_xerror_context.user_xerror = &kwargs_vals[0];
   if (kwargs_vals[1] != Qundef)
     gettextpo_xerror_context.user_xerror2 = &kwargs_vals[1];
   po_file_check_all (DATA_PTR (self), &gettextpo_xerror_handler);
   if (gettextpo_xerror_context.error)
-    rb_raise (rb_eError, "check all for file failed");
+    rb_raise (ERROR, "check all for file failed");
   return Qnil;
 }
 
@@ -718,6 +732,8 @@ gettextpo_po_message_iterator_m_next (VALUE self)
     {
       VALUE message_value = rb_obj_alloc (rb_cMessage);
       DATA_PTR (message_value) = message;
+      rb_ivar_set (message_value, rb_intern ("@file"),
+                   rb_ivar_get (self, rb_intern ("@file")));
       return message_value;
     }
   else
@@ -736,6 +752,8 @@ gettextpo_po_message_iterator_m_insert (VALUE self, VALUE msgid, VALUE msgstr)
   po_message_insert (DATA_PTR (self), message);
   VALUE value = rb_obj_alloc (rb_cMessage);
   DATA_PTR (value) = message;
+  rb_ivar_set (value, rb_intern ("@file"),
+               rb_ivar_get (self, rb_intern ("@file")));
   return value;
 }
 
@@ -831,6 +849,8 @@ gettextpo_po_format_list (VALUE self)
  * call-seq: format_pretty_name (format)
  *
  * Possibly returns +nil+.
+ *
+ * See also ::formats method for available format types.
  */
 VALUE
 gettextpo_po_format_pretty_name (VALUE self, VALUE format)
@@ -845,6 +865,14 @@ RUBY_FUNC_EXPORTED void
 Init_gettextpo (void)
 {
   VALUE rb_mGettextPO = rb_define_module ("GettextPO");
+  rb_define_const (rb_mGettextPO, "LIBGETTEXTPO_VERSION",
+                   INT2NUM (libgettextpo_version));
+  rb_define_const (rb_mGettextPO, "SEVERITY_WARNING",
+                   INT2NUM (PO_SEVERITY_WARNING));
+  rb_define_const (rb_mGettextPO, "SEVERITY_ERROR",
+                   INT2NUM (PO_SEVERITY_ERROR));
+  rb_define_const (rb_mGettextPO, "SEVERITY_FATAL_ERROR",
+                   INT2NUM (PO_SEVERITY_FATAL_ERROR));
   rb_define_singleton_method (rb_mGettextPO, "header_entry_value",
                               gettextpo_m_header_entry_value, 2);
   rb_define_singleton_method (rb_mGettextPO, "header_with_updated_entry_value",
@@ -940,6 +968,4 @@ Init_gettextpo (void)
   rb_define_method (rb_cFilePos, "file", gettextpo_po_filepos_m_file, 0);
   rb_define_method (rb_cFilePos, "start_line",
                     gettextpo_po_filepos_m_start_line, 0);
-  rb_eError
-      = rb_define_class_under (rb_mGettextPO, "Error", rb_eStandardError);
 }

data/ext/gettextpo/gettextpo.h

@@ -1,5 +1,4 @@
-/**
- * Copyright (C) 2026  gemmaro
+/* Copyright (C) 2026  gemmaro
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -18,6 +17,7 @@
 #ifndef GETTEXTPO_H
 #define GETTEXTPO_H 1
 
-#include "ruby.h"
+#include <gettext-po.h>
+#include <ruby.h>
 
 #endif /* GETTEXTPO_H */

data/include/mrb_gettextpo.h

@@ -0,0 +1,24 @@
+/* Copyright (C) 2026  gemmaro
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef MRB_GETTEXTPO_H
+#define MRB_GETTEXTPO_H
+
+#include <mruby.h>
+
+void mrb_gettextpo_gem_init(mrb_state *mrb);
+
+#endif

data/lib/gettextpo/version.rb

@@ -18,5 +18,6 @@
 #++
 
 module GettextPO
-  VERSION = "0.1.0"
+  # Version of this gem.
+  VERSION = "0.1.2"
 end

data/lib/gettextpo.rb

@@ -20,8 +20,25 @@ require_relative "gettextpo/gettextpo"
 
 # The main entrypoints to parse PO files are GettextPO::File.new and
 # GettextPO::File.read.
+#
+# == Error handling
+#
+# There are two kinds of errors in this gem.  The first is for
+# exception handlings of libgettextpo.  The second is regular error
+# raising from this gem.
+#
+# Some functions takes exception error handling paramters like
+# +xerror+ and +xerror2+.  These parameters expect +Proc+ object which
+# takes several parameters.  See also the description of
+# GettextPO::File.read method.  The +severity+ parameter among these
+# parameters is either SEVERITY_WARNING, SEVERITY_ERROR, or
+# SEVERITY_FATAL_ERROR.
+#
+# This gem normally raises +GettextPO::Error+ object, except for the
+# standard ones, +StopIteration+ for example.
+#
 module GettextPO
-  class Error < StandardError; end
+  class Error < StandardError; end # :nodoc:
 
   # This class doesn't provide the +new+ class method.  Refre to
   # GettextPO::MessageIterator#next or