stupidedi 1.1.0

data/doc/Generating.md

@@ -0,0 +1,321 @@
+Generating X12
+==============
+
+Stupidedi has a simple interface for generating X12 documents. Once you have
+defined a transaction set or implementation guide (see {file:Defining.md Defining}),
+you can generate well-formed documents using [`BuilderDsl`][1].
+
+  [1]: Stupidedi/Builder/BuilderDsl.html
+
+Configuration
+-------------
+
+Minimal configuration is needed so Stupidedi can load the correct definitions
+and ensure well-formedness. The configuration below links interchange version
+00501 to an instance of [`InterchangeDef`][2], the functional group version
+005010 to an instance of [`FunctionalGroupDef`][3] and links the transaction set
+(identified by three elements) to an instance of [`TransactionSetDef`][4].
+
+  [2]: Stupidedi/Envelope/InterchangeDef.html
+  [3]: Stupidedi/Envelope/FunctionalGroupDef.html
+  [4]: Stupidedi/Envelope/TransactionSetDef.html
+
+    config = Stupidedi::Config.new
+
+    # Link the "00501" value in ISA12 element to the 5010 interchange definition
+    config.interchange.register("00501") do
+      Stupidedi::Versions::Interchanges::FiveOhOne::InterchangeDef
+    end
+
+    # Link the "005010" value in GS08 to the 5010 functional group definition
+    config.functional_group.register("005010") do
+      Stupidedi::Versions::FunctionalGroups::FiftyTen::FunctionalGroupDef
+    end
+
+    # Link "005010X222" in GS08 or ST03, "HC" in GS01, and "837"
+    # in ST01 to the implementation guide definition
+    config.transaction_set.register("005010X222", "HC", "837") do
+      Stupidedi::Guides::FiftyTen::X222::HC837P
+    end
+
+    # Instantiate a new BuilderDsl
+    b = Stupidedi::Builder::BuilderDsl.build(config)
+
+[`InterchangeDef`][2] specifies which segments can occur directly in the
+interchange envelope (e.g. `ISA` and `ISE`), the order in which they can occur,
+and the definition of those segments.
+
+[`FunctionalGroupDef`][3] specifies which segments can occur directly in the
+functional group envelope (e.g. `GS` and `GE`), the order in which they occur,
+and the definition of _every_ segment that can occur _inside_ the envelope.
+
+[`TransactionSetDef`][4] specifies the structure of an X12 message, including
+groupings of segments (e.g. tables and loops), and the order in which segments
+and groups of segments may occur. The definition of each segment is given by the
+parent [`FunctionalGroupDef`][3].
+
+Generating a Segment
+--------------------
+
+The [`BuilderDsl`][1] API uses `method_missing` to dynamically respond to method
+calls. If the method name matches the format of a segment identifier, a segment
+is constructed and added to the parse tree. The arguments to the method call
+should be the elements of the segment.
+
+    b.ISA("00", "",             # authorization information
+          "00", "",             # authentication information
+          "ZZ", "SUBMITTER ID", # submitter identification
+          "ZZ", "RECEIVER ID",  # recipient identification
+          Time.now.utc,         # date
+          Time.now.utc,         # time
+          "^",                  # repetition separator
+          "00501",              # interchange version
+          "333666999",          # control number
+          "1",                  # acknowledgement request
+          "T",                  # usage indicator
+          ":")                  # component separator
+
+> _Note_: The repetition separator "ˆ" and component separator ":" have no
+> special meaning when generating X12. These elements are only meaningful to
+> Stupidedi when parsing X12 from an input stream (see
+> [Parsing X12](Parsing.html)).
+
+Alternatively, the [`#segment!`][5] method can be used to avoid the method
+lookup overhead incurred by `method_missing`.
+
+  [5]: Stupidedi/Builder/BuilderDsl.html#segment!-instance_method
+
+### Simple Elements
+
+Simple elements of _any_ type can be constructed from Strings (this is how X12
+is parsed from a file), but certain element types can be constructed from other
+types of Ruby values.
+
+The description of each element type below pertains to the `FiftyTen` functional
+group definition. The [`SimpleElementDef`][7] and [`SimpleElementVal`][8] classes
+define the minimal interfaces that are extended by subclasses like `AN` and
+`StringVal`. See the [`FiftyTen::ElementTypes`][6] namespace for more examples.
+
+  [6]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes.html
+  [7]: Stupidedi/Schema/SimpleElementDef.html
+  [8]: Stupidedi/Values/SimpleElementVal.html
+
+#### Strings
+
+String elements (declared with type `AN`) can be constructed from any value that
+responds to `#to_s`. The constructed element is a [`StringVal`][9].
+
+  [9]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes/StringVal.html
+
+#### Identifiers
+
+Identifier elements (declared with type `ID`) can be constructed from any value
+that responds to `#to_s`. The constructed element is an [`IdentifierVal`][10].
+
+  [10]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes/IdentifierVal.html
+
+#### Dates
+
+Date elements (declared with type `DT`) can be constructed from a `String` of
+either six or eight characters, and from any value that responds to `#year`,
+`#month`, and `#day`. This includes the `Date`, `Time`, and `DateTime` classes
+included with the standard Ruby libraries. The constructed element is a
+[`DateVal`][11].
+
+  [11]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes/DateVal.html
+
+#### Times
+
+Time elements (declared with type `TM`) can be constructed from a `String` of
+either two, four, six, or more than six characters, and from the `Time` and
+`DateTime` value types. The constructed element is a [`TimeVal`][12].
+
+  [12]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes/TimeVal.html
+
+#### Numbers
+
+Numeric and decimal elements (declared with type `Nn` and `R`, respectively) can
+be constructed from any value that responds to `#to_d`. The constructed element
+is a [`FixnumVal`][13] or [`FloatVal`][14].
+
+  [13]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes/FixnumVal.html
+  [14]: Stupidedi/Versions/FunctionalGroups/FiftyTen/ElementTypes/FloatVal.html
+
+### Composite Elements
+
+Composite elements are constructed with the [`#composite`][24] method. The
+constructed element is a [`CompositeElementVal`][15]. Arguments to the method
+call should be the component elements. For instance, to generate an `HI` segment
+with three composite elements:
+
+    b.HI(b.composite("ABK", "7868"),
+         b.composite("ABF", "052"),
+         b.composite("ABF", "E9283"))
+
+  [15]: Stupidedi/Values/CompositeElementVal.html
+
+### Repeated Elements
+
+Repeated elements are constructed using the [`#repeated`][25] method. The
+constructed element is a [`RepeatedElementVal`][16]. The arguments to the method
+call should be either all simple elements or all composite elements, according
+to the element definition.
+
+    b.AK9(b.repeated("R", "X", "E"), 1, 1, 0)
+
+    b.IK4(b.repeated(
+            b.composite(3, 1),
+            b.composite(4)),
+          1068, 7, "B")
+
+  [16]: Stupidedi/Values/RepeatedElementVal.html
+
+Element Placeholders
+--------------------
+
+Because [`BuilderDsl`][1] builds a parse tree as segments are generated, it can
+infer and validate certain information about the elements in a segment.
+
+### Blank Elements
+
+Blank elements (simple, composite, and repeated) can be generated from a `nil`
+argument, but you can improve readability by using [`#blank`][26], and
+no-argument calls to [`#composite`][24] and [`#repeated`][25]. These are
+arguably more self-documenting.
+
+    b.AK9(nil, 1, 1, 0)
+    b.AK9(b.repeated, 1, 1, 0)
+
+    b.HI(nil, b.composite(b.blank, "052"))
+    b.HI(b.composite, b.composite(b.blank, "052"))
+
+Also, if fewer than the defined number of elements are given as arguments, the
+missing arguments generate blank elements. For example, the following statements
+both generate the same segment.
+
+    b.ST("835", "1234")
+    b.ST("835", "1234", b.blank)
+
+### Default Elements
+
+Certain elements are declared with a single value in [`#allowed_values`][18].
+These are usually qualifier elements, like `NM103`, whose value adds little
+readability. These values can be inferred by [`BuilderDsl`][1] when the
+[`#default`][27] placeholder is used. For example, when generating the X222 837P
+the following statements generate the same segment.
+
+    b.BHT("0019", "00", control_number, Time.now.utc, Time.now.utc, "CH")
+
+    b.BHT(b.default, "00", control_number, Time.now.utc, Time.now.utc, "CH")
+
+When a default value cannot be inferred, a [`ParseError`][17] is thrown. Note
+that repeated and composite elements can only be generated by [`#default`][27],
+when they are declared `NOT USED`.
+
+  [17]: Stupidedi/Exceptions/ParseError.html
+  [18]: Stupidedi/Schema/SimpleElementUse.html#allowed_values-instance_method
+
+### Unused Elements
+
+For elements that are declared to never be sent, `nil` or [`#blank`][26] will
+generate the empty element; however using [`#not_used`][28] is arguably more
+self-documenting. If [`BuilderDsl`][1] determines that the element is not
+declared as such, it will raise a [`ParseError`][17]. For example the X221 835
+document declares ST03 with `NOT USED`:
+
+    b.ST("835", "1234", b.not_used)
+
+Syntax Validation
+-----------------
+
+The parse tree that [`BuilderDsl`][1] maintains is used to ensure only
+well-formed X12 is generated. This means segments occur in the correct order
+and have the correct number and type of elements.
+
+### Segment Order
+
+The order in which segments may occur is defined by the active
+[`TransactionSetDef`][4], [`FunctionalGroupDef`][3], and [`InterchangeDef`][2].
+Internally, an instance of [`StateMachine`][19] is used to both
+incrementally build the parse tree and keep track of which segments can occur
+from the given state. The [`#successors`][21] method will return one or more
+[`InstructionTable`][20] values which enumerate the segments that may occur in
+the current state:
+
+    pp b.successors
+
+    [InstructionTable(
+      1: Instruction[REF: Subscriber Secon..](pop: 0, drop: 0),
+      2: Instruction[REF: Property and Cas..](pop: 0, drop: 0),
+      3: Instruction[PER: Property and Cas..](pop: 0, drop: 3),
+      4: Instruction[NM1: Subscriber Name   ](pop: 1, drop: 0, push: LoopState),
+      5: Instruction[NM1: Payer Name        ](pop: 1, drop: 0, push: LoopState),
+      6: Instruction[CLM: Claim Informatio..](pop: 1, drop: 2, push: LoopState),
+      7: Instruction[ HL: Subscriber Hiera..](pop: 2, drop: 0, push: LoopState),
+      8: Instruction[ HL: Billing Provider..](pop: 3, drop: 0, push: TableState),
+      9: Instruction[ HL: Subscriber Hiera..](pop: 3, drop: 0, push: TableState),
+     10: Instruction[ HL: Patient Hierachi..](pop: 3, drop: 0, push: TableState),
+     11: Instruction[ SE: Transaction Set ..](pop: 3, drop: 4, push: TableState),
+     12: Instruction[ ST](pop: 4, drop: 0, push: TransactionSetState),
+     13: Instruction[ GE: Functional Group..](pop: 4, drop: 2),
+     14: Instruction[ GS](pop: 5, drop: 0, push: FunctionalGroupState),
+     15: Instruction[IEA: Interchange Cont..](pop: 5, drop: 2),
+     16: Instruction[ISA](pop: 6, drop: 0, push: InterchangeState))]
+
+  [19]: Stupidedi/Builder/StateMachine.html
+  [20]: Stupidedi/Builder/InstructionTable.html
+  [21]: Stupidedi/Builder/BuilderDsl.html#successors-instance_method
+
+The above output pertains to the X222 837 implementation guide. The output shows
+a single active [`InstructionTable`][20] and the segments it is able to accept.
+For more information about how the parser works, see {file:design/Parser.md Parser Design}.
+Attempting to generate a segment that is not a member of at least one of the
+instruction tables will cause a [`ParseError`][17] to be raised.
+
+    b.N3("SUITE 111", "1234 OCEAN BLVD")
+      #=> Segment N3 cannot occur here (Stupidedi::Exceptions::ParseError)
+
+### Element Types
+
+The [`InterchangeDef`][2] and [`TransactionSetDef`][4] classes both respond to
+`#segment_dict`, which allows looking up a [`SegmentDef`][23] by segment its
+identifier. The [`SegmentDef`][23] indicates the number of elements and their
+types (composite, repeated, simple).  This information allows [`BuilderDsl`][1]
+to raise a [`ParseError`][17] on the following conditions:
+
+  [23]: Stupidedi/Schema/SegmentDef.html
+
+Generating a composite element where a simple or repeated element is defined:
+
+    b.NM1(b.composite(nil, "B"), nil)
+      #=> NM101 is a simple element (Stupidedi::Exceptions::ParseError)
+
+Generating a simple element where a repeated or composite element is defined:
+
+    b.REF(nil, nil, nil, "D")
+      #=> REF04 is a composite element (Stupidedi::Exceptions::ParseError)
+
+    b.DMG(nil, nil, nil, nli, "E")
+      #=> DMG05 is a repeatable element (Stupiedi::Exceptions::ParseError)
+
+    b.DMG(nil, nil, nil, nil, b.repeated("E"))
+      #=> DMG05 is a composite element (Stupidedi::Exceptions::ParseError)
+
+Generating a repeated element where a non-repeated element is defined:
+
+    b.NM1(b.repeated("A", "B"))
+      #=> NM101 is a simple element (Stupidedi::Exceptions::ParseError)
+
+Generating more than the defined number of elements:
+
+    b.N3(nil, nil, nil)
+      #=> N3 has only 4 elements (Stupidedi::Exceptions::ParseError)
+
+    b.REF(nil, nil, nil, b.composite("A", "B", "C", "D", "E", "F", "G"))
+      #=> REF04 has only 6 components (Stupidedi::Exceptions::ParseError)
+
+  [24]: Stupidedi/Builder/BuilderDsl.html#composite-instance_method
+  [25]: Stupidedi/Builder/BuilderDsl.html#repeated-instance_method
+  [26]: Stupidedi/Builder/BuilderDsl.html#blank-instance_method
+  [27]: Stupidedi/Builder/BuilderDsl.html#default-instance_method
+  [28]: Stupidedi/Builder/BuilderDsl.html#not_used-instance_method