tediparse 2.0.0

data/Rakefile

@@ -0,0 +1,33 @@
+require "pathname"
+require "fileutils"
+abspath = Pathname.new(File.dirname(__FILE__)).expand_path
+relpath = abspath.relative_path_from(Pathname.pwd)
+
+task :default => :spec
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose    = false
+  t.rspec_opts = "-w -rspec_helper"
+
+  if ENV.include?("CI")
+    t.rspec_opts += " --format progress"
+  else
+    t.rspec_opts += " --format documentation"
+  end
+end
+
+# Note options are loaded from .yardopts
+require "yard"
+YARD::Rake::YardocTask.new(:yard => :clobber_yard)
+task :clobber_yard do
+  # Call FileUtils directly rather than Rake's DSL shim: on Ruby 3.x the
+  # rake-12.3 FileUtilsExt wrapper forwards its verbose/noop flags as a
+  # positional argument, which the keyword-only FileUtils.rm_rf rejects.
+  FileUtils.rm_rf "#{relpath}/build/generated/doc"
+  FileUtils.mkdir_p "#{relpath}/build/generated/doc/images"
+end
+
+task :console do
+  exec(*%w(irb -I lib -r stupidedi))
+end

data/bin/tediparse

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "stupidedi"
+
+options = {
+  namespace: "Edi",
+  out: ".",
+  write: true
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    tediparse - generate Stupidedi grammar definitions from ASC X12 Table Data.
+
+    The X12 Table Data is licensed X12 IP that you supply; the generated grammar
+    files are a derivative you own. This tool ships no X12 content.
+
+    Usage:
+      tediparse generate --release CODE --table-data DIR [--out DIR] [options]
+      tediparse register --out DIR [--namespace NAME]
+
+    `register` rebuilds the whole-tree artifacts (stupidedi_registration.rb, and
+    the master loader if present) by scanning an existing generated tree.
+
+    Options:
+  BANNER
+
+  opts.on("-r", "--release CODE", "X12 release code (e.g. 005010)") { |v| options[:release] = v }
+  opts.on("-t", "--table-data DIR", "Directory of ASC X12 Table Data .TXT files") { |v| options[:table_data] = v }
+  opts.on("-o", "--out DIR", "Output directory (default: current dir)") { |v| options[:out] = v }
+  opts.on("-n", "--namespace NAME", "Root Ruby module for generated code (default: Edi)") { |v| options[:namespace] = v }
+  opts.on("--master-loader", "Also emit a single-require entry file (e.g. edi.rb)") { options[:master_loader] = true }
+  opts.on("--dry-run", "Preview only; write nothing") { options[:write] = false }
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit
+  end
+end
+
+command = ARGV.shift
+parser.parse!(ARGV)
+
+case command
+when "generate"
+  missing = %i[release table_data].reject { |k| options[k] }
+  unless missing.empty?
+    warn "Missing required option(s): #{missing.map { |k| "--#{k.to_s.tr('_', '-')}" }.join(', ')}"
+    warn parser.help
+    exit 1
+  end
+
+  unless Dir.exist?(options[:table_data])
+    warn "Table data directory not found: #{options[:table_data]}"
+    exit 1
+  end
+
+  begin
+    results = Stupidedi::Schema::Generation.run(
+      table_data:    options[:table_data],
+      release:       options[:release],
+      out:           options[:out],
+      namespace:     options[:namespace],
+      write:         options[:write],
+      master_loader: options.fetch(:master_loader, false),
+      logger:        ->(msg) { puts msg }
+    )
+  rescue ArgumentError => e
+    warn "Error: #{e.message}"
+    exit 1
+  end
+
+  puts "Done: #{results.size} files (#{options[:write] ? 'written' : 'preview'})."
+when "register"
+  unless options[:out] && Dir.exist?(options[:out])
+    warn "register requires --out DIR pointing at an existing generated tree"
+    exit 1
+  end
+
+  begin
+    paths = Stupidedi::Schema::Generation.register(
+      out:       options[:out],
+      namespace: options[:namespace],
+      write:     options[:write],
+      logger:    ->(msg) { puts msg }
+    )
+  rescue ArgumentError => e
+    warn "Error: #{e.message}"
+    exit 1
+  end
+
+  puts "Done: rebuilt #{paths.size} file(s)#{options[:write] ? '' : ' (preview)'}."
+when nil, "help", "-h", "--help"
+  puts parser.help
+else
+  warn "Unknown command: #{command}"
+  warn parser.help
+  exit 1
+end

data/doc/Defining.md

@@ -0,0 +1,97 @@
+> This page covers transcribing a grammar **by hand**. If you license the ASC
+> X12 Table Data flat files, tediparse can generate the whole definition tree
+> for a release instead — see
+> [Generating-Grammars.md](Generating-Grammars.md). Hand-authoring as below is
+> still the right approach for a small custom grammar or for understanding what
+> the generator emits.
+
+Be sure you start with the right documentation, which must be purchased from [ASC
+X12](http://x12.org/). Documentation from a trading partner might be usable in a
+pinch, but is often missing details or has details relevant only to that
+partner. If you are unsure, the cover page for the document should look like
+this:
+
+![](images/transcribing-cover.png)
+
+## Tables
+
+The overall structure of the grammar is given in section 2.2 of the
+documentation (be sure it is marked `IMPLEMENTATION` and not `STANDARD`). The
+top-level tables can be written as `TableDef.header`, `TableDef.detail`, and
+`TableDef.summary`.
+
+![](images/transcribing-table.png)
+
+> Note for some reason, some grammars show the `SE` segment at the end of a
+> detail table, rather than in its own summary table. The `SE` segment is the
+> end of the document, so when you code up the grammar, you should create a
+> `TableDef.summary` to contain the `SE` segment (see 837P). This is because
+> a detail table can be repeated, while a summary table cannot, and the `SE`
+> segment should only occur once in a document.
+
+## Loops
+
+Loops are groups of segments which have a particular starting segment that
+indicates the start of the group, followed by other segments. Loops may be
+nested, and each loop may be repeated a specified number of times. You can
+translate each loop in the documentation to a `LoopDef.build(name, repeat_count,
+*children)` where children are either segments or child loops.
+
+In the example above, the `"2000C PATIENT HIERARCHY"` loop has a repeat count
+of `RepeatCount.unbounded`, child segments `HL` and `PAT`, and many child loops
+beginning with `"2000CA PATIENT NAME"`. Since `HL` is the first segment in the
+loop, when the parser reads an `HL` in the right context, it will then create
+the corresponding loop in the parse tree.
+
+## Segments
+
+Segments are sort of like a `struct` in the C programming language, where the
+fields are called elements. Unlike structs, each time a segment occurs in the
+grammar, it can be given a different name, different flags to indicate which
+fields are required or optional, different set of allowed values in each field,
+and a different number of allowed repeats.
+
+One of the most commonly used segments is `NM1`, which is generally some kind of
+name. In the above example, you an `NM1 Patient Name`, but there are many others
+in the grammar for different people.
+
+![](images/transcribing-segment-detail.png)
+
+The important parts of the image above have probably already been transcribed in
+an existing `SegmentDef` (unless you find a segment that hasn't been defined), which
+are the same across all grammars (all the X12 attributes). The "loop", "usage", and
+"repeat count" were described earlier, but are again shown here.
+
+Segments can be described using `BuilderDsl.Segment(offset, id, name,
+usage, repeat_count, *elements)`. The first argument comes from the `Pos. #`
+column in the table diagram above. For instance, the `NM1 Patient Name` segment
+has an offset of 150. The usage argument is denoted in a few places: on the
+above diagrams, it is the labeled `Usage`; this indicates if the segment is
+required or optional, or if its presence depends on other conditions.
+
+## Elements
+
+Elements are (apart from composite elements), some kind of atomic data type,
+like a string, number, date, etc. Each place a segment is specified in the
+grammar, its element properties are also specified. Beware that each place that
+a segment appears can have different details about its elements, per-occurence.
+
+![](images/transcribing-segment-diagram.png)
+
+This diagram indicates some of the properties of each element, in this
+particular instance of the `NM1` segemnt. The bold border around an element
+indicates that it is `Required`, while strike-through text indicates a
+`NotUsed`. If you encounter a segment that hasn't already been defined, some of
+the other properties needed to define the segment are also included on the
+diagram, but we'll ignore those for now.
+
+![](images/transcribing-element-detail.png)
+
+The third section of each element detail gives a name to each element,
+usually in the gray section labeled `IMPLEMENTATION NAME`, and also specifies
+its usage, allowed values, and minimum and maximum lengths. The usage indicator
+is in the first column, name and allowed values in the fourth. Minimum and
+maximum length, and number of decimal places are given in the last column, but
+these rarely need to be specified as they are usually the same as the default
+declared in the `ElementDef`.
+

data/doc/Generating-Grammars.md

@@ -0,0 +1,241 @@
+Generating Grammars from X12 Table Data
+=======================================
+
+> **"Generating" means two different things in this project.** This page is
+> about *generating the grammar* — turning the ASC X12 standard into the Ruby
+> definition files the engine walks. [Generating.md](Generating.md) is about
+> *generating X12 documents* — emitting EDI with the writer once you already
+> have a grammar. If you want to produce an 837 or a 204, you want the other
+> page.
+
+There are two ways to get a grammar that the engine can use:
+
+1. **Author it by hand** — transcribe a purchased implementation guide into
+   `SegmentDef` / `LoopDef` / `TransactionSetDef` values. See
+   [Defining.md](Defining.md). This is fine for a handful of segments, but a
+   full transaction set is hundreds of definitions.
+2. **Generate it from ASC X12 Table Data** — feed the official flat-file
+   distribution to the generator and it emits the whole definition tree for a
+   release. This page covers that path.
+
+Both produce the same thing: Ruby source that builds `Stupidedi::Schema`
+objects, registered against a `Stupidedi::Config`. Generation is just
+automation over the hand-authoring you would otherwise do.
+
+The IP boundary
+---------------
+
+**The gem ships the generation *machine* only.** The X12 Table Data it reads
+is licensed X12 IP that you supply, and the grammar files it writes are a
+derivative of that IP that belong to you. Neither the input nor the output
+ships with tediparse.
+
+The committed fixture under `spec/support/generation/table_data/` is a small
+*synthetic* grammar in the same flat-file format — fabricated structure used
+to test the generator — not real X12 content.
+
+Input: the ASC X12 Table Data distribution
+-------------------------------------------
+
+To obtain the Table Data you need an **ASC X12 license**; with one in hand you
+can download the distribution from <https://ecommerce.x12.org/downloads>.
+
+The Table Data is a set of CSV-shaped `.TXT` files, one header/detail pair per
+kind of definition, plus a free-form file:
+
+| File           | Holds                                              |
+| -------------- | -------------------------------------------------- |
+| `ELEHEAD` / `ELEDETL` | simple data elements (type, lengths, code lists) |
+| `COMHEAD` / `COMDETL` | composite elements and their component uses |
+| `SEGHEAD` / `SEGDETL` | segments and their ordered element uses     |
+| `SETHEAD` / `SETDETL` | transaction sets and their table/loop/segment structure |
+| `FREEFORM`            | longer prose (segment/element notes)        |
+
+Point `--table-data` at the directory holding these files for one release.
+
+The CLI
+-------
+
+The gem ships one executable, `bin/tediparse`:
+
+```sh
+# Generate the full grammar tree for a release into ./lib
+tediparse generate --release 005010 \
+  --table-data vendor/x12/table_data/005010 \
+  --out lib
+
+# Preview without writing anything
+tediparse generate --release 005010 \
+  --table-data vendor/x12/table_data/005010 \
+  --out lib --dry-run
+
+# Emit into a custom root module (default is Edi)
+tediparse generate --release 005010 \
+  --table-data vendor/x12/table_data/005010 \
+  --out lib --namespace Acme
+
+# Also emit a single-require entry file (for non-autoloader setups)
+tediparse generate --release 005010 \
+  --table-data vendor/x12/table_data/005010 \
+  --out lib --master-loader
+
+# Rebuild the whole-tree aggregation files for an existing tree
+tediparse register --out lib
+```
+
+Supported releases: `003060`, `004010`, `004060`, `005010`, `006010`,
+`007010`, `008010`. An unsupported release code is rejected before anything
+is read.
+
+From Ruby
+---------
+
+The CLI is a thin wrapper over a facade you can call directly — useful from a
+Rake task:
+
+```ruby
+Stupidedi::Schema::Generation.run(
+  table_data:    "vendor/x12/table_data/005010",
+  release:       "005010",
+  out:           "lib",
+  namespace:     "Edi",   # root module for the emitted code (default: "Edi")
+  master_loader: false,   # also emit a single-require entry file?
+  write:         true,    # false = dry run (returns results, writes nothing)
+  logger:        ->(msg) { puts msg }
+)
+
+# Rebuild only the whole-tree artifacts (registration + master loader if present)
+Stupidedi::Schema::Generation.register(out: "lib")
+```
+
+`run` returns one `Result` per file (`path`, `relative_path`, `content`,
+`written`), so a dry run gives you the full generated source to diff or
+inspect without touching disk. The whole release is staged in a tempdir first
+and copied into `out` in one step only on success, so a failure partway
+through never leaves a half-written tree.
+
+The output tree
+---------------
+
+For `--release 005010 --namespace Edi --out lib`, the generator writes
+(`005010` → the `FiftyTen` version module → the `fifty_ten` path):
+
+```
+lib/
+  edi/
+    fifty_ten/
+      element_reqs.rb          # aliases Mandatory/Optional/Relational
+      element_types.rb         # aliases the element type primitives
+      segment_reqs.rb          # aliases the segment requirement enums
+      syntax_notes.rb          # aliases the P/R/C/E/L syntax-note builders
+      element_defs.rb          # every simple + composite element for the release
+      segment_defs.rb          # every segment, incl. ISA/IEA/GS/GE/TA1
+      functional_group_def.rb  # the GS/GE envelope
+      standards/
+        <transaction_set>.rb   # one file per transaction set
+    fifty_ten.rb               # version loader: requires this version's files
+    interchanges/
+      five_oh_one.rb           # the ISA/IEA envelope (named by ISA version code)
+    stupidedi_registration.rb  # wires every release in the tree onto a Config
+  edi.rb                       # master loader — only with --master-loader
+```
+
+- The four small `*_reqs` / `*_types` / `syntax_notes` modules just alias
+  common `Stupidedi` types into the version namespace so the bulky files can
+  use short names.
+- `element_defs.rb` and `segment_defs.rb` are the bulk of the grammar.
+- `standards/*.rb` are the transaction-set definitions — these are what you
+  register per `(version, functional id, transaction code)`.
+- `interchanges/` is **shared across releases** in the tree and named by the
+  ISA12 version code (`00501` → `five_oh_one`), not by the release module.
+- `stupidedi_registration.rb` is the entry point that builds a populated
+  `Config` for everything in the tree (see "Using the grammar" below).
+
+Loading the generated code
+---------------------------
+
+By default the tree is meant to be picked up by your application's autoloader
+(Rails / Zeitwerk): the file/constant layout follows the `edi/fifty_ten/...`
+convention, so `Edi::FiftyTen::SegmentDefs` resolves on demand.
+
+If you are **not** using an autoloader, pass `--master-loader` (or
+`master_loader: true`). That emits a single `edi.rb` (named after the
+namespace) which `require`s the whole tree in dependency order, so a plain
+`require "edi"` loads everything.
+
+Multiple releases in one tree
+-----------------------------
+
+You can keep several releases side by side under one `out`. Generating an
+additional release **preserves** the ones already present:
+`stupidedi_registration.rb` (and the master loader, if any) are whole-tree
+artifacts — every run rebuilds them to cover every release found in `out`, not
+just the one you just generated. The regenerated release's own directory is
+replaced wholesale (so a shrunk transaction-set list doesn't leave orphans),
+while other releases and the shared `interchanges/` directory are left alone.
+
+If you add or remove a release by other means and need to refresh just the
+aggregation files, run `tediparse register --out lib` (or
+`Stupidedi::Schema::Generation.register(out: "lib")`).
+
+Using the generated grammar
+----------------------------
+
+The generated `stupidedi_registration.rb` does the wiring for you: it returns
+a `Stupidedi::Config` with every release's interchange, functional group, and
+transaction sets registered. Load the tree, get the config, and hand it to the
+parser or writer exactly as you would a hand-authored one:
+
+```ruby
+require "edi"   # or rely on your autoloader
+
+config = Edi.config            # populated Stupidedi::Config from stupidedi_registration.rb
+
+parser = Stupidedi::Parser.build(config)
+# ... parse, navigate (see Navigating.md)
+
+b = Stupidedi::Parser::BuilderDsl.build(config)
+# ... generate documents (see Generating.md)
+```
+
+From here the generated grammar is indistinguishable from one you wrote by
+hand. Continue with [Generating.md](Generating.md) to emit documents and
+[Navigating.md](Navigating.md) to read and traverse them.
+
+How it works
+------------
+
+Generation is two layers with a plain-struct seam between them
+(`lib/stupidedi/schema/generation/`):
+
+- **Layer A — `flat_file_reader.rb`** parses the `.TXT` distribution into the
+  plain value objects in `models.rb` (`Release`, `Element`, `Segment`,
+  `TransactionSet`, `LoopDefinition`, …). It carries no database or Ruby-source
+  concerns — any source that builds objects with the same shape can drive the
+  next layer.
+- **Layer B — the generators** (`element_generator.rb`, `segment_generator.rb`,
+  `definition_generator.rb`, `functional_group_generator.rb`,
+  `interchange_generator.rb`, `module_loader_generator.rb`,
+  `registration_generator.rb`, `support_modules_generator.rb`) consume those
+  structs and emit the Ruby source above. `runner.rb` orchestrates a full
+  release; `bin/tediparse` is the CLI over it.
+
+`spec/lib/stupidedi/schema/generation_spec.rb` round-trips the synthetic
+fixture through the reader, the generators, and a child-process load that
+builds real engine objects — so it's also a worked example of what each layer
+produces.
+
+Fidelity notes
+--------------
+
+A few details the generator carries through from the standard that are easy to
+miss:
+
+- **Element repeat counts** come from the SEGDETL repetition column: a numeric
+  count becomes `RepeatCount.bounded(n)`, the unbounded marker (`>1`) becomes
+  `RepeatCount.unbounded`, and a non-repeating use is `bounded(1)`.
+- **The repetition separator** (ISA11 / element I65) is re-stamped in the
+  generated interchange's `replace_separators` on releases that use one, so the
+  writer round-trips it.
+- **Higher-precision numeric types** (`N3`, `N5`, `N7`, `N8`, `N9`, …) all map
+  to the engine's `Nn`, which accepts arbitrary implied-decimal precision.