X12 0.0.5

data/README

@@ -0,0 +1,309 @@
+= X12Parser - a library to manipulate X12 structures using native Ruby syntax
+
+$Id: README 40 2008-11-13 19:51:31Z ikk $
+
+*WARNING* <tt>The project is in development. Contributors are welcome.</tt>
+
+Project home is at http://rubyforge.org/projects/x12parser/. Please
+note, this is a different project from {Chris Parker's port}[http://rubyforge.org/projects/x12-parser/] of
+{X12::Parser Perl module}[http://search.cpan.org/~prasad/X12-0.09/lib/X12/Parser.pm].
+
+== The goal
+
+The idea is to access X12 messages directly from Ruby, i.e., using a
+syntax like
+
+  message.L1000.L1010[1].AK4.DataElementReferenceNumber
+
+This syntax can be used to get and set any field of an X12 message and
+it makes X12 parsing much more straightforward and self-documenting.
+
+== The problem
+
+X12 is a set of "standards" possessing all the elegance of an elephant
+designed by committee, and quite literally so, see http://www.x12.org.
+X12 defines rough syntax for specifying text messages, but each of
+more than 300 specifications defines its own message structure. While
+messages themselves are easy to parse with a simple tokenizer, their
+semantics is heavily dependent on the domain. For example, this is
+X12/997 message conveying "Functional Acknowledgment":
+
+  ST*997*2878~AK1*HS*293328532~AK2*270*307272179~AK3*NM1*8*L1010_0*8~
+  AK4*0:0*66*1~AK4*0:1*66*1~AK4*0:2*66*1~AK3*NM1*8*L1010_1*8~AK4*1:0*
+  66*1~AK4*1:1*66*1~AK3*NM1*8*L1010_2*8~AK4*2:0*66*1~AK5*R*5~AK9*R*1*
+  1*0~SE*8*2878~
+
+I.e., X12 defines an alphabet and somewhat of a dictionary - not a
+grammar or semantics for each particular data interchange
+conversation. Because of many entrenched implementations and
+government mandates, the X12 is not going to die anytime soon,
+unfortunately.
+
+The message above can be easily represented in Ruby as a nested array:
+
+ m = [
+      ['ST', '997', '2878'],
+      ['AK1', 'HS', '293328532'],
+      ['AK2', '270', '307272179'],
+      ['AK3', 'NM1', '8', 'L1010_0', '8'],
+      ['AK4', '0:0', '66', '1'],
+      ['AK4', '0:1', '66', '1'],
+      ['AK4', '0:2', '66', '1'],
+      ['AK3', 'NM1', '8', 'L1010_1', '8'],
+      ['AK4', '1:0', '66', '1'],
+      ['AK4', '1:1', '66', '1'],
+      ['AK3', 'NM1', '8', 'L1010_2', '8'],
+      ['AK4', '2:0', '66', '1'],
+      ['AK5', 'R', '5'],
+      ['AK9', 'R', '1', '1', '0'],
+      ['SE', '8', '2878'],
+     ]
+
+but it will not help any since, say, segment 'AK4' is ambiguously
+defined and its meaning not at all obvious until the message's
+structure is interpreted and correct 'AK4' segment is found.
+
+== The solution
+
+=== Message structure
+
+Each participant in EDI has to know the structure of the data coming
+across the wire - X12 or no X12. The X12 structures are defined in
+so-called Implementation Guides - thick books with all the data pieces
+spelled out. There is no other choice, but to invent a
+computer-readable definition language that will codify these
+books. For example, the X12/997 message can be defined as
+
+  loop 997 1:1
+  {
+    segment ST  1:1
+    segment AK1 1:1
+    loop L1000 0:999999
+    {
+      segment AK2 0:1
+      loop L1010 0:999999
+      {
+        segment AK3 0:1
+        segment AK4 0:99
+      } # L1010
+      segment AK5 1:1
+    } # L1000
+    segment AK9 1:1
+    segment SE  1:1
+  } # 997
+
+Namely, the 997 is a 'loop' containing segments ST (only one - '1:1'),
+AK1 (also only one), another loop L1000 (zero or many repeats),
+segments AK9 and SE. The loop L1000 can contain a segment AK2
+(optional - '0:1') and another loop L1010 (zero or many), and so on.
+
+The segments' structure can be further defined as, for example,
+
+  segment AK2 {
+    TransactionSetIdentifierCode  S R 3-3 Tbl143
+    TransactionSetControlNumber   S R 4-9
+  } # AK2
+
+wihch defines a segment AK2 as having to fields:
+TransactionSetIdentifierCode and TransactionSetControlNumber. The
+field TransactionSetIdentifierCode is defined as having a type of
+string ('S'), begin required ('R'), having length of minimum 3 and
+maximum 3 characters ('3-3'), and being validated against a table
+Tbl143. The validation table is defined as
+
+  table Tbl143 {
+    100 Insurance Plan Description
+    101 Name and Address Lists
+    ...
+    997 Functional Acknowledgment
+    998 Set Cancellation
+  } # Tbl143
+
+where required values are first tokens on each line, i.e., 100, 101,
+..., 997, 998.
+
+This message is fully flashed out in an example 'misc/997.d12' file,
+copied from the ASC X12N 276/277 (004010X093) "Health Care
+Claim Status Request and Response" National Electronic Data
+Interchange Transaction Set Implementation Guide.
+
+Now expressions like 
+
+  message.L1000.L1010[1].AK4.DataElementReferenceNumber
+
+start making sense of sorts, overall X12's idiocy notwithstanding - it's
+a field called 'DataElementReferenceNumber' of a first of possibly
+many segments 'AK4' found in the second repeat of the loop 'L1010'
+inside the enclosing loop 'L1000'. The meaning of the value '66' found
+in this field is still in the eye of the beholder, but, at least its
+location is clearly identified in the message.
+
+
+=== X12 Structure Definition Language (d12)
+
+The syntax of the X12 structure definition language should be apparent
+from the '997.d12' file enclosed with the package. The strict definition
+is formalized in 'lib/X12/x12syntax.treetop' file.
+
+=== Parsing
+
+Here is how to parse an X12/997 message (the source is in
+example/parse.rb):
+
+  require 'x12'
+
+  # Read message definition and create an actual parser
+  # by compiling .d12 file
+  parser = X12::Parser.new('misc/997.d12')
+
+  # Define a test message to parse
+  m997='ST*997*2878~AK1*HS*293328532~AK2*270*307272179~'\
+  'AK3*NM1*8*L1010_0*8~AK4*0:0*66*1~AK4*0:1*66*1~AK4*0:2*'\
+  '66*1~AK3*NM1*8*L1010_1*8~AK4*1:0*66*1~AK4*1:1*66*1~AK3*'\
+  'NM1*8*L1010_2*8~AK4*2:0*66*1~AK5*R*5~AK9*R*1*1*0~SE*8*2878~'
+
+  # Parse the message
+  r = parser.parse('997', m997)
+
+  # Access components of the message as desired
+
+  # Whole ST segment: -> ST*997*2878~
+  puts r.ST
+
+  # One filed, Group Control Number of AK1 -> 293328532
+  puts r.AK1.GroupControlNumber
+
+  # Individual loop, namely, third L1010 sub-loop of
+  # L1000 loop: -> AK3*NM1*8*L1010_2*8~AK4*2:0*66*1~
+  puts r.L1000.L1010[2]
+
+  # First encounter of Data Element Reference Number of the 
+  # first L1010 sub-loop of L1000 loop -> 66
+  puts r.L1000.L1010.AK4.DataElementReferenceNumber
+
+  # Number of L1010 sub-loops in L1000 loop -> 3
+  puts r.L1000.L1010.size
+
+=== Generating
+
+Here is how to perform a reverse operation and generate a well-formed
+997 message (the source is in example/factory.rb):
+
+  require 'x12'
+
+  # Read message definition and create an actual parser
+  # by compiling .d12 file
+  parser = X12::Parser.new('misc/997.d12')
+
+  # Make a new 997 message 
+  r = parser.factory('997')
+
+  #
+  # Set various fields as desired
+  #
+
+  # Set fields directly
+  r.ST.TransactionSetIdentifierCode = 997
+  r.ST.TransactionSetControlNumber  = '2878'
+
+  # Set fields inside a segment (AK1 in this case)
+  r.AK1 { |ak1|
+    ak1.FunctionalIdentifierCode = 'HS'
+    ak1.GroupControlNumber       = 293328532
+  }
+
+  # Set fields deeply inside a segment inside 
+  # nested loops (L1000/L1010/AK4 in this case)
+  r.L1000.L1010.AK4.DataElementSyntaxErrorCode = 55
+  r.L1000.AK2.TransactionSetIdentifierCode     = 270
+
+  # Set nested loops
+  r.L1000.L1010 {|l|
+    l.AK3 {|s|
+      s.SegmentIdCode      = 'NM1'
+      s.LoopIdentifierCode = 'L1000D'
+    }
+    l.AK4 {|s|
+      s.CopyOfBadDataElement = 'Bad element'
+    }
+  }
+
+  # Add loop repeats
+  r.L1000.repeat {|l1000|
+    (0..1).each {|loop_repeat| # Two repeats of the loop L1010
+      l1000.L1010.repeat {|l1010|
+        l1010.AK3 {|s|
+          s.SegmentIdCode                   = 'DMG'
+          s.SegmentPositionInTransactionSet = 0
+          s.LoopIdentifierCode              = 'L1010'
+          s.SegmentSyntaxErrorCode          = 22
+        } if loop_repeat == 0 # AK3 only in the first repeat of L1010
+        (0..1).each {|ak4_repeat| # Two repeats of the segment AK4
+          l1010.AK4.repeat {|s|
+            s.PositionInSegment          = loop_repeat
+            s.DataElementSyntaxErrorCode = ak4_repeat
+          } # s
+        } # ak4_repeat
+      } # l1010
+    } # loop_repeat
+
+    l1000.AK5{|a|
+      a.TransactionSetAcknowledgmentCode = 666
+      a.TransactionSetSyntaxErrorCode4   = 999
+    } # a
+  } # l1000
+
+  # Print the message as a string -> ST*997*2878~AK1*HS*293328532~
+  # AK2*270*~AK3*NM1**L1000D~AK4***55*Bad element~AK5*~AK3*DMG*0*
+  # L1010*22~AK4*0**0~AK4*0**1~AK4*1**0~AK4*1**1~AK5*666****999~
+  # AK9****~SE**~
+  puts r.render
+
+== Download
+
+The latest X12 library version can be downloaded from
+http://rubyforge.org/frs/?group_id=7297
+
+== Installation
+
+You can install X12 library with the following command.
+
+  % gem install X12
+
+If you install directly from the X12*.gem file, it requires these
+packages to be installed first:
+* {Treetop}[http://rubyforge.org/projects/treetop/]
+* {Polyglot}[http://rubyforge.org/projects/polyglot/]
+
+== License
+
+X12 library is released under the Lesser GPL license, see
+http://www.gnu.org/licenses/lgpl.txt
+
+== Major deficiencies
+
+* Validation is not implemented.
+* Field types and sizes are ignored.
+* No access methods for composites' fields.
+
+== Wish list
+
+* .d12 files should have an 'include' facility, so data definitions can be reused for different messages.
+
+* It would be nice to codify all popular X12 messages in .d12 format.
+
+== Support
+
+Please use the following:
+
+* forums on Rubyforge for general discussions, http://rubyforge.org/forum/?group_id=7297
+* trackers to submit bugs or feature requests, http://rubyforge.org/tracker/?group_id=7297
+* to contact the author, send mail to prelude rubyforge org
+
+== Acknowledgments
+
+The authors of the project were inspired by the following works:
+
+1. The Perl X12 parser by Prasad Poruporuthan, http://search.cpan.org/~prasad/X12-0.09/lib/X12/Parser.pm
+2. The Ruby port of the above by Chris Parker, http://rubyforge.org/projects/x12-parser/
+3. Treetop Ruby parser, http://treetop.rubyforge.org

data/Rakefile

@@ -0,0 +1,157 @@
+#--
+#     This file is part of the X12Parser library that provides tools to
+#     manipulate X12 messages using Ruby native syntax.
+#
+#     http://x12parser.rubyforge.org 
+#     
+#     Copyright (C) 2008 APP Design, Inc.
+#
+#     This library is free software; you can redistribute it and/or
+#     modify it under the terms of the GNU Lesser General Public
+#     License as published by the Free Software Foundation; either
+#     version 2.1 of the License, or (at your option) any later version.
+#
+#     This library 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
+#     Lesser General Public License for more details.
+#
+#     You should have received a copy of the GNU Lesser General Public
+#     License along with this library; if not, write to the Free Software
+#     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+#
+# $Id: Rakefile 39 2008-11-13 19:43:55Z ikk $
+#++
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'pp'
+
+require File.join(File.dirname(__FILE__), 'lib', 'X12')
+
+PKG_NAME        = 'X12'
+PKG_VERSION     = X12::VERSION
+PKG_FILE_NAME   = "#{PKG_NAME}-#{PKG_VERSION}"
+PKG_DESTINATION = "../#{PKG_NAME}"
+
+RAKE            = $0
+RUBY_DIR        = File.expand_path(File.dirname(RAKE)+'../..')
+RUBY            = "#{RUBY_DIR}/bin/ruby.exe"
+
+CLEAN.include(
+              '**/*.log',
+              'doc/**/*',
+              '**/*.tmp',
+              'lib/X12/X12syntax.rb'
+              )
+CLEAN.exclude(
+              )
+
+
+#puts "Files to clobber: #{CLOBBER}"
+#puts "Files to clean: #{CLEAN}"
+
+desc "Default Task"
+task :default => [ :example, :test ]
+
+# Run examples
+task :example do |x|
+  Dir['example/*.rb'].each {|f|
+    puts "Running #{f}"
+    sh(RUBY, '-I', 'lib', f) do |ok, res|
+      fail "Command failed (status = #{res.exitstatus})" unless ok
+    end
+  }
+end
+
+task :test do |x|
+  Rake::TestTask.new { |t|
+    t.libs << "test"
+    t.test_files = Dir['test/ts_*.rb']
+    t.verbose = true
+  }
+end # :test
+
+file 'doc/index.html' => ['misc/rdoc_template.rb' ]
+task :rdoc => ['doc/index.html']
+
+# Generate the RDoc documentation
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "X12 -- an X12 parsing library"
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README' 
+  rdoc.template = 'misc/rdoc_template.rb'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('CHANGELOG')
+  rdoc.rdoc_files.include('TODO')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+}
+
+
+# Create compressed packages by running 'rake gem'
+
+desc "gem task"
+task :gem => [ :clobber, :rdoc ]
+
+# Here's how to look inside the gem package:
+# ~..>tar xvf package.gem; gunzip data.tar.gz metadata.gz; tar xvf data.tar; cat metadata
+spec = Gem::Specification.new do |s|
+  s.platform          = Gem::Platform::RUBY
+  s.name              = PKG_NAME
+  s.version           = PKG_VERSION
+  s.summary           = 'X12 parsing and generation library'
+  s.description       = 'Library to parse X12 messages and manipulate their loops, segments, fields, composites, and validation tables.'
+  s.author            = 'APP Design, Inc.'
+  s.email             = 'info@appdesign.com'
+  s.rubyforge_project = PKG_NAME
+  s.homepage          = "http://www.appdesign.com"
+
+  s.has_rdoc = true
+  s.requirements << 'none'
+  s.require_path = 'lib'
+  s.autorequire = 'x12'
+  s.add_dependency "treetop"
+
+  [ 
+   "Rakefile", 
+   "README", 
+   "TODO",
+   "CHANGELOG",
+   "COPYING",
+   "doc/**/*",
+   "lib/**/*",
+   "test/**/*",
+   "example/**/*",
+   "misc/**/*"
+  ].each do |i|
+    s.files += Dir.glob(i).delete_if do
+      |x| x =~ /.*~/
+    end
+  end
+  puts "Files included into the GEM:" if $VERBOSE
+  pp s.files if $VERBOSE
+
+  s.test_files = Dir.glob( "test/**/ts_*rb" )
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+# Compile treetop definition into Ruby code. Like this:
+# >rake lib/X12/X12syntax.rb
+# It's needed only for debugging Treetop's internals.
+rule '.rb' => ['.treetop'] do |t|
+  require 'treetop'
+  compiler = Treetop::Compiler::GrammarCompiler.new
+  puts "Compiling [#{t.source}]"
+  compiler.compile(t.source)
+end