adf_builder 0.4.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 838eda978e92f15cfa05a3da07e8a80ee1348f07fb4511abcf2ae79063e0917d
-  data.tar.gz: 205da1b11de1d2748107a0696477787ba0a8f5971ffaabf46f1c25a13fb8079c
+  metadata.gz: ded72167a643d102957459b6d439bbaae8f01833303a3eca082ce4a6f0e264dd
+  data.tar.gz: 64486e697bd4feefa5fdbc8c6cbe01d3d0492878225748ffdf3c8ed1650b8b09
 SHA512:
-  metadata.gz: f85f57a637fcdd0e71b84afda8ad59476a2ffe7ffed04ca521f306950469a87ce895eb71339d1ab48c1fa6d9b5ebab26699654ce9556c613deb39291e876ad72
-  data.tar.gz: bdade6f04b5a64dbb042202052c3ba174f8263b00d735e858a1f9627ce25e4524a53b41d42200108258914c2e582efbcd8f0bf449e17a0de2fd741cd37b489dd
+  metadata.gz: b868564c56972b958839382c2d5c5706ce1b7864ea13e2c7eb38dddccb82f6481a66bc471f679f79589533a8fa9fd29897a387d53d4426ee8bc5490242912b45
+  data.tar.gz: 0c25a32fec2c3015e402fdbe26e0c2af23a2a91ea64840097a7a86acd7c88c4e89a809362b1ea35b8eebaa112dc130534b82f1a3647173ab5f0d1f3aa2b19fa0

data/.gitignore

@@ -11,3 +11,4 @@
 .rspec_status
 
 deploy.txt
+*.gem

data/CHANGELOG.md

@@ -1,4 +1,20 @@
-## [Unreleased]
+## [1.1.0] - 2026-01-19
+- **Feature Complete**: Implemented all ADF 1.0 nodes and attributes including `Vendor`, `Provider`, and complex `Vehicle` tags (`Finance`, `Option`, `Odometer`, `ColorCombination`, `ImageTag`, `Price`).
+- **Singular Field logic**: Methods for singular fields (e.g. `vehicle.year`) now correctly replace existing values instead of appending.
+- **Removed Legacy Code**: Cleaned up deprecated legacy implementation directories.
+
+## [1.0.0] - 2026-01-19
+- **MAJOR OVERHAUL**: Complete rewrtie of the library architecture.
+- **New Block-based DSL**: Intuitive API for building ADF documents (`AdfBuilder.build { vehicle { ... } }`).
+- **Validation**: Strict enforcement of ADF enumerations and structure (e.g. `vehicle status: :new`).
+- **Editing**: New `AdfBuilder.tree` method for programmatic modifications after construction.
+- **Robustness**: Complete rewrite of XML generation using robust heuristics and strict `Ox` serialization.
+- **Compatibility**: Verified for Ruby 3.4.x.
+- **Features**:
+  - Support for multiple vehicles/customers.
+  - Support for singular vs multiple item logic.
+  - Dynamic support for arbitrary/custom tags (`method_missing`).
+  - Automatic handling of XML attributes vs simple elements.
 
 ## [0.4.0] - 2026-01-19
 - Modernized dependencies

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    adf_builder (0.4.0)
+    adf_builder (1.1.0)
       ox (~> 2.14)
 
 GEM
@@ -13,6 +13,8 @@ GEM
     json (2.18.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    nokogiri (1.19.0-arm64-darwin)
+      racc (~> 1.4)
     ox (2.14.23)
       bigdecimal (>= 3.0)
     parallel (1.27.0)
@@ -62,6 +64,7 @@ PLATFORMS
 
 DEPENDENCIES
   adf_builder!
+  nokogiri (~> 1.15)
   rake (~> 13.2)
   rspec (~> 3.13)
   rubocop (~> 1.70)

data/README.md

@@ -1,5 +1,8 @@
 # AdfBuilder
-Hopefully this will help with development in the ADF format. The goal is to intuitively create and update an ADF XML file that can easily be added to an email or saved to a file.
+
+A Ruby gem for creating valid **Auto-lead Data Format (ADF)** XML documents intuitively. 
+
+Version **1.0** introduces a new declarative DSL, strict validation, and a robust architecture.
 
 ## Installation
 
@@ -14,393 +17,134 @@ And then execute:
 $ bundle install
 ```
 
-Or install it yourself as:
-```shell
-$ gem install adf_builder
-```
-
 ## Usage
 
-Quickly create the minimal lead found in the spec document
-```ruby
-builder = AdfBuilder::Builder.new
-builder.minimal_lead
-```
-Start Building
-```ruby
-builder = AdfBuilder::Builder.new
-builder.to_xml
-```
+### The DSL (New in v1.0)
 
+Version 1.0 uses a block-based DSL to structure your ADF document. This aligns the visual structure of your Ruby code with the resulting XML hierarchy.
 
-Outputs
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-04T15:18:30+04:00</requestdate>
-  </prospect>
-</adf>
-```
-
-
-Update Requestdate value
 ```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.request_date.update_val(Date.new(2021,12,12))
-```
-Outputs
+xml = AdfBuilder.build do
+  prospect do
+    # Singular attributes (last call wins)
+    request_date Time.now
+    
+    # Multiple items: Calling 'vehicle' multiple times adds multiple vehicles
+    vehicle do
+      year 2021
+      make 'Ford'
+      model 'F-150'
+      status :new   # Validated attribute
+    end
+    
+    vehicle do
+      year 2023
+      make 'Tesla'
+      model 'Cybertruck'
+      status :used
+    end
+    
+    customer do
+      contact do
+        name 'John Doe', part: 'full'
+        email 'john@example.com'
+        phone '555-1234', type: 'cell'
+      end
+    end
+    
+    vendor do
+       # vendor implementation...
+    end
+  end
+end
+
+puts xml
+```
+
+### Outputs
 
 ```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-12-12T00:00:00+00:00</requestdate>
-  </prospect>
-</adf>
-```
-
-
-Add ID tag to Prospect
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.add_id('howdy', 'Ag')
-```
-
-Outputs
-```xml
-<?ADF version="1.0"?>
-
 <?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <id sequence="1" source="Ag">howdy</id>
-    <requestdate>2021-08-04T15:24:16+04:00</requestdate>
-  </prospect>
-</adf>
-```
-
-Add Vehicle
-
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.vehicles.add(2021, 'Ford', 'Raptor')
-```
-
-Outputs
-
-```xml
 <?ADF version="1.0"?>
-
-<?xml version="1.0"?>
 <adf>
-  <prospect status="new">
-    <requestdate>2021-08-04T18:08:50+04:00</requestdate>
-    <vehicle interest="buy" status="new">
+  <prospect>
+    <requestdate>2026-01-19 16:40:00 -0600</requestdate>
+    <vehicle status="new">
       <year>2021</year>
       <make>Ford</make>
-      <model>Raptor</model>
+      <model>F-150</model>
     </vehicle>
-  </prospect>
-</adf>
-```
-
-Vehicle with different operations
-
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.vehicles.add(2021, 'Toyota', 'Prius', {
-  status: :used,
-})
-builder.prospect.vehicles.update_tags_with_free_text(0, {
-  bodystyle: 'howdy',
-  year: '2000'
-})
-builder.prospect.vehicles.update_odometer(0, 9000, {
-  units: 'km'
-})
-builder.prospect.vehicles.update_condition(0, 'ffff')
-builder.prospect.vehicles.update_imagetag(0, 'http://adfxml.info/adf_spec.pdf', {
-  width: 400,
-  height: 500,
-  alttext: 'Howdy'
-})
-puts builder.to_xml
-```
-
-Outputs
-
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-09T00:53:59+04:00</requestdate>
-    <customer/>
-    <vendor/>
     <vehicle status="used">
-      <year>2000</year>
-      <make>Toyota</make>
-      <model>Prius</model>
-      <bodystyle>howdy</bodystyle>
-      <odometer units="km">9000</odometer>
-      <imagetag width="400" height="500" alttext="Howdy">http://adfxml.info/adf_spec.pdf</imagetag>
+      <year>2023</year>
+      <make>Tesla</make>
+      <model>Cybertruck</model>
     </vehicle>
-  </prospect>
-</adf>
-```
-
-Color Combination
-
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.vehicles.add(2021, 'Toyota', 'Prius', {
-  status: :used,
-})
-builder.prospect.vehicles.add_color_combination(0, 'black', 'yellow', 1)
-puts builder.to_xml
-```
-
-Outputs
-
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-09T00:56:07+04:00</requestdate>
-    <customer/>
-    <vendor/>
-    <vehicle status="used">
-      <year>2021</year>
-      <make>Toyota</make>
-      <model>Prius</model>
-      <colorcombination>
-        <interiorcolor>black</interiorcolor>
-        <exteriorcolor>yellow</exteriorcolor>
-        <preference>1</preference>
-      </colorcombination>
-    </vehicle>
-  </prospect>
-</adf>
-```
-
-Add Vendor
-
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.vendor.add('Dealer One', 'Manager Name', {
-  part: 'full',
-  type: 'individual'
-}) # options for customer object that is required in vendor
-```
-
-Outputs
-
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-08T18:43:02+04:00</requestdate>
-    <customer/>
-    <vendor>
-      <vendorname>Dealer One</vendorname>
-      <contact>
-        <name part="full" type="individual">Manager Name</name>
-      </contact>
-    </vendor>
-  </prospect>
-</adf>
-```
-
-Add Contact with phone
-
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.customer.add('New Guy', {
-  part: 'full',
-  type: 'individual'
-})
-builder.prospect.customer.contact.add_phone('(555)-444-3333')
-```
-
-Outputs
-
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-08T18:44:45+04:00</requestdate>
     <customer>
       <contact>
-        <name part="full" type="individual">New Guy</name>
-        <phone>(555)-444-3333</phone>
+        <name part="full">John Doe</name>
+        <email>john@example.com</email>
+        <phone type="cell">555-1234</phone>
       </contact>
     </customer>
-    <vendor/>
   </prospect>
 </adf>
 ```
-A complex Provider 
 
-```ruby
-builder = AdfBuilder::Builder.new
-provider = builder.prospect.provider
-provider.add('Testing', {part: 'full', type: 'business'})
-provider.update_tags_with_free_text({
-                                                       url: 'howdy',
-                                                       service: "Nice"
-                                                     })
-provider.add_email("test@test.com", {preferredcontact: 0})
-provider.add_phone("+14445556666", {
-  type: 'fax',
-  time: 'day'
-})
-provider.add_contact("Mr Sir")
-provider.contact.add_phone("+132435523424")
-```
-
-```xml
-<?ADF version="1.0"?>
+### Multiple vs Singular Items
 
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-12T18:56:41+04:00</requestdate>
-    <customer/>
-    <vendor/>
-    <provider>
-      <name part="full" type="business">Testing</name>
-      <url>howdy</url>
-      <service>Nice</service>
-      <email preferredcontact="0">test@test.com</email>
-      <phone type="fax" time="day">+14445556666</phone>
-      <contact>
-        <name>Mr Sir</name>
-        <phone>+132435523424</phone>
-      </contact>
-    </provider>
-  </prospect>
-</adf>
-```
+- **Singular Attributes**: Methods that take a value (e.g., `year 2021`, `request_date Time.now`) set an attribute on the current node. Calling them multiple times overwrites the value.
+- **Multiple Nodes**: Methods that take a block (e.g., `vehicle { ... }`) create a new child node and append it. You can call them as many times as needed to add multiple items.
 
-Adding and Updating Price of Vehicle
-```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.vehicles.add(2021, 'Toyota', 'Prius', {
-  status: :used,
-})
+### Advanced: Editing & Programmatic Access
 
-builder.prospect.vehicles.add_price(0,23400, {
-  type: 'quote',
-  currency: 'blah',
-  source: "YES"
-})
+If you need to edit the data after building it (or build it progressively), use `AdfBuilder.tree`. This returns the object tree instead of the XML string.
 
-puts builder.to_xml
+```ruby
+# 1. Build the tree
+tree = AdfBuilder.tree do
+  prospect do
+    vehicle do
+      year 2020
+      make 'Ford'
+      status :new
+    end
+  end
+end
 
-builder.prospect.vehicles.price(0).update(3444, {
-  currency: 'USD'
-})
+# 2. Modify the tree programmatically
+# Access helpers: .prospect, .vehicles, .customers
+prospect = tree.children.first
+vehicle = prospect.vehicles.first
 
-puts builder.to_xml
-```
+vehicle.year(2025) # Update existing value
+vehicle.status(:used)
 
-Outputs
-```xml
-<?ADF version="1.0"?>
+# Add a new vehicle dynamically
+prospect.vehicle do
+  year 2023
+  make 'Tesla'
+  status :new
+end
 
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-13T13:28:50+04:00</requestdate>
-    <customer/>
-    <vendor/>
-    <vehicle status="used">
-      <year>2021</year>
-      <make>Toyota</make>
-      <model>Prius</model>
-      <price type="quote" source="YES">23400</price>
-    </vehicle>
-  </prospect>
-</adf>
+# 3. Serialize to XML
+puts tree.to_xml
 ```
 
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
+### Validation
 
-<adf>
-  <prospect status="new">
-    <requestdate>2021-08-13T13:28:50+04:00</requestdate>
-    <customer/>
-    <vendor/>
-    <vehicle status="used">
-      <year>2021</year>
-      <make>Toyota</make>
-      <model>Prius</model>
-      <price type="quote" source="YES" currency="USD">3444</price>
-    </vehicle>
-  </prospect>
-</adf>
-```
+The library now enforces ADF standards. Invalid enum values will raise an error.
 
-Adding comments to Vehicle
 ```ruby
-builder = AdfBuilder::Builder.new
-builder.prospect.vehicles.add(2021, 'Toyota', 'Prius', {
-  status: :used,
-})
-
-builder.prospect.vehicles.add_comments(0, "This is a comment")
-
-puts builder.to_xml
-```
-
-Outputs
-```xml
-<?ADF version="1.0"?>
-
-<?xml version="1.0"?>
-<adf>
-  <prospect status="new">
-    <requestdate>2021-11-02T16:35:43+04:00</requestdate>
-    <customer/>
-    <vendor/>
-    <vehicle status="used">
-      <year>2021</year>
-      <make>Toyota</make>
-      <model>Prius</model>
-      <comments>This is a comment</comments>
-    </vehicle>
-  </prospect>
-</adf>
+# Raises AdfBuilder::Error: Invalid value for status: broken
+AdfBuilder.build do
+  prospect do
+    vehicle do
+      status :broken 
+    end
+  end
+end
 ```
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will 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).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jippylong12/adf_builder. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jippylong12/adf_builder/blob/master/CODE_OF_CONDUCT.md).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the AdfBuilder project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jippylong12/adf_builder/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/jippylong12/adf_builder.

data/adf_builder.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   spec.add_dependency "ox", "~> 2.14"
+  spec.add_development_dependency "nokogiri", "~> 1.15"
   spec.add_development_dependency "rake", "~> 13.2"
   spec.add_development_dependency "rspec", "~> 3.13"
   spec.add_development_dependency "rubocop", "~> 1.70"

data/lib/adf_builder/dsl.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AdfBuilder
+  class DSL
+    def self.build(&block)
+      root = Nodes::Root.new
+      root.instance_eval(&block) if block_given?
+      root.validate!
+      Serializer.to_xml(root)
+    end
+
+    def self.tree(&block)
+      root = Nodes::Root.new
+      root.instance_eval(&block) if block_given?
+      root
+    end
+  end
+
+  def self.build(&block)
+    DSL.build(&block)
+  end
+
+  def self.tree(&block)
+    DSL.tree(&block)
+  end
+end

data/lib/adf_builder/nodes/customer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AdfBuilder
+  module Nodes
+    class Customer < Node
+      def initialize
+        super
+        @tag_name = :customer
+      end
+
+      def contact(&block)
+        remove_children(:contact)
+        contact = Contact.new
+        contact.instance_eval(&block) if block_given?
+        add_child(contact)
+      end
+
+      def id(value, sequence: nil, source: nil)
+        # id* is multiple
+        add_child(Id.new(value, sequence: sequence, source: source))
+      end
+
+      def timeframe(&block)
+        remove_children(:timeframe)
+        tf = Timeframe.new
+        tf.instance_eval(&block) if block_given?
+        add_child(tf)
+      end
+
+      def comments(value)
+        remove_children(:comments)
+        add_child(GenericNode.new(:comments, {}, value))
+      end
+    end
+
+    class Timeframe < Node
+      def initialize
+        super
+        @tag_name = :timeframe
+      end
+
+      def description(value)
+        remove_children(:description)
+        add_child(GenericNode.new(:description, {}, value))
+      end
+
+      def earliestdate(value)
+        remove_children(:earliestdate)
+        add_child(GenericNode.new(:earliestdate, {}, value))
+      end
+
+      def latestdate(value)
+        remove_children(:latestdate)
+        add_child(GenericNode.new(:latestdate, {}, value))
+      end
+    end
+  end
+end