hcl_data 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10aa51e1fe382d2d9eed002a2096c3922924ecbde6850dc26108ffd1f416f4da
+  data.tar.gz: eb8245bb4441eafca9a18cbe6cb111573596af40ba992233c76a8df3c331d2d8
+SHA512:
+  metadata.gz: 7dba19c69393e5d29aa9ea474d45f38b0a8a8dd53224109a81df81431680f393a76c8c80cc29af2de1096dc2250df1c8a717b4ad6a3d64880398ab90deba9fc4
+  data.tar.gz: 1a2dbd14fdbfc8a2f1b01969d5d6ec2bb032e556216ec3abe13a0b6421bcc50fdb61d5c8ce3537aed8331a908e98aed7cd17fed0120d5decea638a158c87c968

data/AGENTS.md

@@ -0,0 +1,25 @@
+# hcl_data
+
+A Ruby gem for reading and writing data in HCL (HashiCorp Configuration Language) format.
+Supports the JSON-equivalent subset of HCL grammar: scalars, arrays, maps, and blocks.
+
+API: `HclData.dump` / `HclData.load`, like JSON/YAML.
+
+## Development approach
+
+Strict TDD. Always write a failing test before writing implementation code.
+
+1. Write a test that fails
+2. Write the minimum code to make it pass
+3. Refactor if needed
+4. Repeat
+
+Never write implementation code without a failing test first.
+
+Stage working files with `git add` whenever `bundle exec rake` passes.
+
+## Rubocop
+
+Avoid relaxing rubocop checks (e.g. raising `Max` limits). If code triggers an offense, refactor to fix it.
+
+If/when we do relax checks, do so in a targeted way (e.g. per-class, or per-method).

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Mike Williams <mdub@dogbiscuit.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# hcl_data
+
+[![Gem Version](https://img.shields.io/gem/v/hcl_data)](https://rubygems.org/gems/hcl_data)
+[![CI](https://github.com/mdub/hcl_data/actions/workflows/ci.yml/badge.svg)](https://github.com/mdub/hcl_data/actions/workflows/ci.yml)
+
+A Ruby library for reading and writing data in [HCL](https://github.com/hashicorp/hcl) (HashiCorp Configuration Language) format.
+
+Supports the JSON-equivalent subset of HCL grammar: scalars, arrays, maps, and blocks.
+
+## Installation
+
+```ruby
+gem 'hcl_data'
+```
+
+## Usage
+
+The API follows the `load`/`dump` conventions of `Marshal`, `JSON`, and `YAML`:
+
+```ruby
+require 'hcl_data'
+
+# parse HCL
+data = HclData.load(<<~HCL)
+  name = "web"
+  port = 8080
+  enabled = true
+
+  server {
+    host = "localhost"
+    tags = ["primary", "us-east"]
+  }
+HCL
+
+# => {"name"=>"web", "port"=>8080, "enabled"=>true,
+#     "server"=>{"host"=>"localhost", "tags"=>["primary", "us-east"]}}
+
+# generate HCL
+puts HclData.dump(data)
+```
+
+### IO support
+
+`load` accepts a String or any IO-like object (anything responding to `read`):
+
+```ruby
+data = File.open('config.hcl') { |f| HclData.load(f) }
+```
+
+`dump` accepts an optional IO as a second argument:
+
+```ruby
+File.open('config.hcl', 'w') { |f| HclData.dump(data, f) }
+```
+
+### Supported HCL features
+
+- String, integer, float, boolean, and null values
+- Arrays
+- Maps (with `=` or `:` separator)
+- Blocks (unlabeled, labeled, nested)
+- Repeated blocks (parsed as arrays)
+- Heredoc strings (`<<EOF`, `<<~EOF`)
+- Comments (`#`, `//`, `/* */`)
+
+### Not supported
+
+This gem targets HCL as a data format (the JSON-equivalent subset). The following HCL language features are not supported:
+
+- String interpolation (`"${var.name}"`)
+- Expressions, operators, and function calls
+- Variable references
+- `for` expressions
+- Splat expressions (`*.id`)
+- Conditional expressions (`condition ? true : false`)
+- Template directives (`%{if ...}`, `%{for ...}`)
+- Dynamic blocks
+
+## License
+
+MIT

data/lib/hcl_data/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module HclData
+
+  class Error < StandardError; end
+  class ParseError < Error; end
+
+end

data/lib/hcl_data/generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module HclData
+
+  # Generates HCL from Ruby data structures.
+  class Generator
+
+    def initialize(data)
+      @data = data
+    end
+
+    def generate
+      generate_body(@data, 0)
+    end
+
+    private
+
+    def generate_body(data, depth)
+      indent = '  ' * depth
+      data.map do |key, value|
+        if value.is_a?(Hash)
+          generate_block(indent, key, value, depth)
+        else
+          "#{indent}#{key} = #{generate_value(value)}\n"
+        end
+      end.join
+    end
+
+    def generate_block(indent, key, body, depth)
+      "#{indent}#{key} {\n#{generate_body(body, depth + 1)}#{indent}}\n"
+    end
+
+    def generate_value(value)
+      case value
+      when nil then 'null'
+      when true then 'true'
+      when false then 'false'
+      when String then value.inspect
+      when Numeric then value.to_s
+      when Hash then "{ #{value.map { |k, v| "#{k} = #{generate_value(v)}" }.join(', ')} }"
+      when Array then "[#{value.map { |v| generate_value(v) }.join(', ')}]"
+      else raise ArgumentError, "unsupported value type: #{value.class}"
+      end
+    end
+
+  end
+
+end

data/lib/hcl_data/lexer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'strscan'
+
+module HclData
+
+  Token = Struct.new(:type, :value)
+
+  # Tokenizes HCL input.
+  class Lexer
+
+    ESCAPE_SEQUENCES = {
+      '"' => '"',
+      '\\' => '\\',
+      'n' => "\n",
+      't' => "\t",
+      'r' => "\r"
+    }.freeze
+
+    SINGLE_CHAR_TOKENS = {
+      '{' => :LBRACE, '}' => :RBRACE,
+      '[' => :LBRACKET, ']' => :RBRACKET,
+      '=' => :EQUALS, ',' => :COMMA, ':' => :COLON,
+      "\n" => :NEWLINE
+    }.freeze
+
+    def initialize(input)
+      @scanner = StringScanner.new(input)
+    end
+
+    def tokens
+      result = []
+      while (token = next_token)
+        result << token
+      end
+      result << Token.new(:EOF, nil)
+    end
+
+    private
+
+    def next_token
+      skip_whitespace_and_comments
+      return nil if @scanner.eos?
+
+      if @scanner.scan('"')
+        scan_string
+      elsif @scanner.scan(/<<~?-?/)
+        scan_heredoc
+      elsif @scanner.scan(/[{}\[\]=,:\n]/)
+        Token.new(SINGLE_CHAR_TOKENS[@scanner.matched], nil)
+      elsif @scanner.scan(/-?\d+\.\d+([eE][+-]?\d+)?/) || @scanner.scan(/-?\d+[eE][+-]?\d+/)
+        Token.new(:FLOAT, @scanner.matched.to_f)
+      elsif @scanner.scan(/-?\d+/)
+        Token.new(:INTEGER, @scanner.matched.to_i)
+      elsif @scanner.scan(/[a-zA-Z_][a-zA-Z0-9_-]*/)
+        keyword_or_identifier(@scanner.matched)
+      else
+        ch = @scanner.getch
+        raise ParseError, "unexpected character #{ch.inspect}"
+      end
+    end
+
+    def scan_string
+      value = +''
+      loop do
+        if @scanner.eos?
+          raise ParseError, 'unterminated string'
+        elsif @scanner.scan('"')
+          return Token.new(:STRING, value)
+        elsif @scanner.scan(/\\u([0-9a-fA-F]{4})/)
+          value << @scanner[1].to_i(16).chr(Encoding::UTF_8)
+        elsif @scanner.scan(/\\(.)/)
+          value << (ESCAPE_SEQUENCES[@scanner[1]] || @scanner[1])
+        else
+          @scanner.scan(/[^"\\]+/)
+          value << @scanner.matched
+        end
+      end
+    end
+
+    def scan_heredoc
+      strip = @scanner.matched.include?('~')
+      marker = @scanner.scan(/[A-Z_]+/) or raise ParseError, 'expected heredoc marker'
+      @scanner.scan(/[ \t]*\n/) or raise ParseError, 'expected newline after heredoc marker'
+      body = @scanner.scan_until(/\n[ \t]*#{marker}[ \t]*$/) or raise ParseError, 'unterminated heredoc'
+      value = body.sub(/\n[ \t]*#{marker}[ \t]*\z/, "\n")
+      value = strip_heredoc_indent(value) if strip
+      Token.new(:STRING, value)
+    end
+
+    def strip_heredoc_indent(text)
+      lines = text.split("\n", -1)
+      min_indent = lines.reject(&:empty?).map { |l| l[/^ */].length }.min || 0
+      lines.map { |l| l.length >= min_indent ? l[min_indent..] : l }.join("\n")
+    end
+
+    def keyword_or_identifier(word)
+      case word
+      when 'true' then Token.new(:TRUE, true)
+      when 'false' then Token.new(:FALSE, false)
+      when 'null' then Token.new(:NULL, nil)
+      else Token.new(:IDENTIFIER, word)
+      end
+    end
+
+    def skip_whitespace_and_comments
+      loop do
+        @scanner.scan(/[ \t]+/)
+        if @scanner.scan(%r{//[^\n]*}) || @scanner.scan(/#[^\n]*/)
+          next
+        elsif @scanner.scan(%r{/\*})
+          @scanner.scan_until(%r{\*/})
+          next
+        else
+          break
+        end
+      end
+    end
+
+  end
+
+end

data/lib/hcl_data/parser.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module HclData
+
+  # Parses HCL tokens into Ruby data structures.
+  class Parser
+
+    def initialize(input)
+      @tokens = Lexer.new(input).tokens
+      @pos = 0
+    end
+
+    def parse
+      parse_body
+    end
+
+    private
+
+    def parse_body
+      result = {}
+      skip_newlines
+      while current_type == :IDENTIFIER
+        key = current.value
+        advance
+        if current_type == :EQUALS
+          advance
+          result[key] = parse_expression
+        elsif %i[STRING LBRACE].include?(current_type)
+          merge_block(result, key, parse_block)
+        else
+          raise ParseError, "expected EQUALS or LBRACE, got #{current_type}"
+        end
+        skip_newlines
+      end
+      result
+    end
+
+    def parse_block
+      labels = []
+      while current_type == :STRING
+        labels << current.value
+        advance
+      end
+      expect(:LBRACE)
+      body = parse_body
+      expect(:RBRACE)
+      labels.reverse.reduce(body) { |inner, label| { label => inner } }
+    end
+
+    def parse_expression
+      case current_type
+      when :STRING, :INTEGER, :FLOAT, :TRUE, :FALSE, :NULL
+        current.value.tap { advance }
+      when :LBRACKET
+        parse_array
+      when :LBRACE
+        parse_map
+      else
+        raise ParseError, "unexpected token #{current_type}"
+      end
+    end
+
+    def parse_array
+      advance # skip [
+      result = []
+      skip_newlines
+      unless current_type == :RBRACKET
+        result << parse_expression
+        while %i[COMMA NEWLINE].include?(current_type)
+          advance
+          skip_newlines
+          break if current_type == :RBRACKET
+
+          result << parse_expression
+        end
+      end
+      expect(:RBRACKET)
+      result
+    end
+
+    def parse_map
+      advance # skip {
+      result = {}
+      skip_newlines
+      while %i[IDENTIFIER STRING].include?(current_type)
+        key = current.value
+        advance
+        raise ParseError, "expected EQUALS or COLON, got #{current_type}" unless %i[EQUALS COLON].include?(current_type)
+
+        advance
+        result[key] = parse_expression
+        advance if current_type == :COMMA
+        skip_newlines
+      end
+      expect(:RBRACE)
+      result
+    end
+
+    def merge_block(result, key, value)
+      if result.key?(key)
+        result[key] = [result[key]] unless result[key].is_a?(Array)
+        result[key] << value
+      else
+        result[key] = value
+      end
+    end
+
+    def current = @tokens[@pos]
+    def current_type = current&.type
+    def advance = @pos += 1
+
+    def expect(type)
+      raise ParseError, "expected #{type}, got #{current_type}" if current_type != type
+
+      advance
+    end
+
+    def skip_newlines
+      advance while current_type == :NEWLINE
+    end
+
+  end
+
+end

data/lib/hcl_data/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module HclData
+
+  VERSION = '1.0.0'
+
+end

data/lib/hcl_data.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'hcl_data/version'
+require 'hcl_data/errors'
+require 'hcl_data/lexer'
+require 'hcl_data/parser'
+require 'hcl_data/generator'
+
+# Read and write data in HCL format.
+module HclData
+
+  def self.load(input)
+    input = input.read if input.respond_to?(:read)
+    Parser.new(input).parse
+  end
+
+  def self.dump(data, io = nil)
+    hcl = Generator.new(data).generate
+    if io
+      io.write(hcl)
+      io
+    else
+      hcl
+    end
+  end
+
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: hcl_data
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mike Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A library for reading and writing data in HCL (HashiCorp Configuration
+  Language) format, supporting the JSON-equivalent subset of the grammar.
+email: mdub@dogbiscuit.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CLAUDE.md
+- LICENSE
+- README.md
+- lib/hcl_data.rb
+- lib/hcl_data/errors.rb
+- lib/hcl_data/generator.rb
+- lib/hcl_data/lexer.rb
+- lib/hcl_data/parser.rb
+- lib/hcl_data/version.rb
+homepage: https://github.com/mdub/hcl_data
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Read and write HCL data
+test_files: []