ISSUES @@ -1,6 +1,3 @@ -#PCD -- Using "AD" as the epoch isn't allowed... is this correct behavior? If BC isn't -# supplied, AD is assumed, but it seems to me it should at least be allowed grammar - GEDCOM-Ruby ----------- @@ -41,46 +38,50 @@ and comment out Usage ----- -To use this module in your own programs, you can either inherit from the GEDCOM::Parser class -(in which case the initialize method should call 'super' before doing anything else), or you -can instantiate the GEDCOM::Parser class directly. +To use this module in your own programs, you can either inherit from +the GEDCOM::Parser class (in which case the initialize method should +call 'super' before doing anything else), or you can instantiate the +GEDCOM::Parser class directly. + +Either way, the before() and after() methods should then be used to +register callbacks for specified contexts. A "context" is simply an +array of strings, where each element of the array specifies a GEDCOM +row type. For example: -Either way, the setPreHandler and setPostHandler methods should then be used to register -callbacks for specified contexts. A "context" is simply an array of strings, where each -element of the array specifies a GEDCOM row type. For example: + [ "INDI" ] -> this context defines a row on which an individual is + introduced. + [ "INDI", "BIRT", "DATE" ] -> this context defines the birthdate of + an individual. - [ "INDI" ] -> this context defines a row on which an individual is introduced. - [ "INDI", "BIRT", "DATE" ] -> this context defines the birthdate of an individual. +Callbacks are registered using a proc, a method name, or a block: -Callbacks are registered as follows: + before( context, proc ) + after( context, proc ) - setPreHandler( context, function [, parm] ) - setPostHandler( context, function [, parm] ) + before( context, :method ) + after( context, :method ) -The 'context' is (as was described above) an array of strings, and the function is the Method -object to invoke. The optional 'parm' method is a parameter that should be passed to the callback -when it is invoked. This can be used to allow the same callback to handle multiple different -contexts. + before( context ) do ... end + after( context ) do ... end -The 'pre' handler is called as soon as the context is recognized, before anything else is done. -The 'post' handler is called when the given context is about to expire. For example, if the context -were [ "INDI" ], the pre handler would be called as soon as a row of type 'INDI' at level 0 was -encountered, while the post handler would be called as soon as another row of level 0 was encountered, -before that row's pre handler was invoked. This allows you do perform initialization and commit -operations. +The 'before' handler is called as soon as the context is recognized, +before anything else is done. The 'after' handler is called when the +given context is about to expire. For example, if the context were +["INDI"], the before handler would be called as soon as a row of type +'INDI' at level 0 was encountered, while the after handler would be +called as soon as another row of level 0 was encountered, before that +row's before handler was invoked. This allows you do perform +initialization and commit operations. -Each callback should take three parameters: +Callbacks should take a single parameter, which will be the data portion of each row: def callbackFunction( data, cookie, parm ) ... end -The 'data' parameter is the text for the row's data (ie, the text that follows the row's type). -The 'cookie' parameter is the value that was passed to the parser's initialize method (if any), -and 'parm' is the parameter that was specified when the callback was registered. - -To parse a file, simply call the parser's 'parse' method, passing the name of the file to -parse. +To parse a file, simply call the parser's 'parse' method, passing the +name of the file to parse. The 'parse' method will take a filename, +or an IO instance. API Reference @@ -90,22 +91,31 @@ API Reference class Parser - def initialize( cookie = nil ) - :: Creates the parser, with the given 'cookie' (application defined value) which will - be passed to every callback. + def initialize( &block ) + :: Constructor. Can optionally be called with a block, which is + used to define the before and after callbacks. - def setPreHandler( context, func, parm = nil ) - :: Registers the given function (Method object) to be called as soon as the given - context is recognized. The given 'parm' value will be passed to the callback. + def before( context, proc=nil, &block ) + :: Registers the given proc or block to be called + as soon as the given context is recognized. - def setPostHandler( context, func, parm = nil ) - :: Registers the given function (Method object) to be called as soon as the given - context expires. The given 'parm' value will be passed to the callback. + def after( context, proc=nil, &block ) + :: Registers the given proc or block to be called as soon as + the given context expires. - def parse( file ) - :: Opens and parses the file with the given name, invoking callbacks as the registered - contexts are recognized. - + def auto_concat= boolean + :: Sets the auto-concatenation mode (defaults to true/on). + When auto-concatenation is enabled, any CONT tags in the input + will be appended to the previous tag, and the 'after' callback + for that tag will include all of the concatenated data. No + callbacks for CONT tags will be made in this case. When + auto-concatenation is disabled, each CONT tag will be treated + as normal, with before and after callbacks. + + def parse( file_or_io ) + :: Opens and parses the file with the given name, or an existing + IO instance, invoking callbacks as the registered contexts are + recognized. class Date README 0140069bd1b9aca60df6bcdabee46956ad3e83f2 Jeremy Slade jeremy@jkslade.net http://github.com/timshadel/gedcom-ruby/commit/b54ccd3fb5df897f11fa84463fe4ff26972c314d b54ccd3fb5df897f11fa84463fe4ff26972c314d 2008-12-11T07:34:10-08:00 2008-12-11T07:34:10-08:00 Updated docs to match new API 32960cd9f4e345a654277ac49bfdd79dce68bbc8 Jeremy Slade jeremy@jkslade.net