hummel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51c766a08cd0ff86bb1c6e7b24015ac5a0dcb7bccfce1afd50b97943d5e2b2e4
+  data.tar.gz: ca7137d3dfe54500e91f34cc83f295b35096a688690168a13edcab8071522d33
+SHA512:
+  metadata.gz: 16a70da398fb107964d014cd393a18417fc6112d7bbb854f72297e9626ef718b196bd8b6a128f95c23444c4db95b81add9708d2aa19e55b8fdf1a7fc2773f275
+  data.tar.gz: 28018bb7b58fcc429a53c8001ea643d62331aeec9432a8aa267a8c7ab03c3b1a7e1f9a4263d83621cd8b893e8067255b31918abf3d4d3529fbbc05a84ab9d5fa

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.4.7

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-12
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Derek Bender
+
+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,95 @@
+# hummel
+
+An HUML parser implementation in ruby.
+
+> **Note:** The gem is named `hummel` because `huml` was already taken on rubygems.org.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hummel', source: 'https://gem.coop'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install hummel --source https://gem.coop
+```
+
+## Usage
+
+### Parsing HUML
+
+```ruby
+require 'hummel'
+
+huml_string = <<~HUML
+  name: John Doe
+  age: 30
+  email: john@example.com
+HUML
+
+data = Hummel::Decode.parse(huml_string)
+# => {"name"=>"John Doe", "age"=>30, "email"=>"john@example.com"}
+```
+
+### Encoding to HUML
+
+```ruby
+require 'hummel'
+
+data = {
+  name: "John Doe",
+  age: 30,
+  hobbies: ["reading", "coding", "hiking"]
+}
+
+huml_string = Hummel::Encode.stringify(data)
+puts huml_string
+# Output:
+# age: 30
+# hobbies::
+#   - reading
+#   - coding
+#   - hiking
+# name: John Doe
+```
+
+### Options
+
+You can include the HUML version header when encoding:
+
+```ruby
+Hummel::Encode.stringify(data, include_version: true)
+# Output:
+# %HUML v0.1.0
+#
+# age: 30
+# ...
+```
+
+## 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 [gem.coop](https://gem.coop).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/djbender/hummel. 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/djbender/hummel/blob/main/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 Hummel project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/djbender/hummel/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/hummel/decode.rb

@@ -0,0 +1,825 @@
+module Hummel
+  module Decode
+    def self.parse(input)
+      parser = Parser.new(input)
+      parser.parse
+    end
+
+    class Error < StandardError; end
+  end
+
+  class Parser
+    class ParseError < Hummel::Decode::Error
+      attr_reader :line
+
+      def initialize(message, line)
+        @line = line
+        super("line #{line}: #{message}")
+      end
+    end
+
+    TYPES = {
+      INLINE_DICT: 1,
+      MULTILINE_DICT: 2,
+      EMPTY_LIST: 3,
+      EMPTY_DICT: 4,
+      MULTILINE_LIST: 5,
+      INLINE_LIST: 6,
+      SCALAR: 7
+    }
+    SPECIAL_VALUES = [
+      ["true", true],
+      ["false", false],
+      ["null", nil],
+      ["nan", Float::NAN],
+      ["inf", Float::INFINITY]
+    ]
+
+    ESCAPE_MAP = {
+      '"' => '"',
+      "\\" => "\\",
+      "/" => "/",
+      "n" => "\n",
+      "t" => "\t",
+      "r" => "\r",
+      "f" => "\f",
+      "v" => "\v"
+    }
+
+    NUMBER_BASE_PREFIXES = [
+      ["0x", 16],
+      ["0o", 8],
+      ["0b", 2]
+    ]
+
+    attr_reader :data
+    attr_accessor :pos, :line
+
+    def initialize(data)
+      @data = data
+      @pos = 0
+      @line = 1
+    end
+
+    def parse
+      raise error("empty document is undefined") if data.empty?
+
+      if peek_string("%HUML")
+        advance(5)
+
+        if !done? && data[pos] == " "
+          advance(1)
+
+          # parse version string
+          starting_pos = pos
+          while !done? && ![" ", "\n", "#"].include?(data[pos])
+            self.pos += 1
+          end
+
+          if pos > starting_pos
+            version = data[starting_pos...pos]
+            if version != "v0.1.0"
+              raise error("unsupported version '#{version}'. expected 'v0.1.0'")
+            end
+          end
+        end
+
+        consume_line
+      end
+
+      skip_blank_lines
+
+      raise error("empty doc is undefined") if done?
+      raise error("root element must not be indented") if current_indent != 0
+      raise error("'::' indicator not allowed at document root") if peek_string("::")
+      raise error("':' indicator not allowed at document root") if peek_string(":") && !key_value_pair?
+
+      type_handlers = {
+        TYPES.fetch(:INLINE_DICT) => -> {
+          assert_root_end(parse_inline_vector_contents(TYPES[:INLINE_DICT]), "root inline dict")
+        },
+        TYPES[:MULTILINE_DICT] => -> {
+          parse_multiline_dict(0)
+        },
+        TYPES[:EMPTY_LIST] => -> {
+          advance(2)
+          consume_line
+          assert_root_end([], "root list")
+        },
+        TYPES[:EMPTY_DICT] => -> {
+          advance(2)
+          consume_line
+          assert_root_end({}, "root dict")
+        },
+        TYPES[:MULTILINE_LIST] => -> {
+          parse_multiline_list(0)
+        },
+        TYPES[:INLINE_LIST] => -> {
+          assert_root_end(
+            parse_inline_vector_contents(TYPES.fetch(:INLINE_LIST)),
+            "root inline list"
+          )
+        },
+        TYPES[:SCALAR] => -> {
+          val = parse_value(0)
+          consume_line
+          assert_root_end(val, "root scalar value")
+        }
+      }
+      type_handlers[root_type].call
+    end
+
+    # 90% sure this is a valid ruby version
+    def root_type
+      if key_value_pair?
+        return TYPES.fetch(:INLINE_DICT) if inline_dict_at_root?
+        return TYPES.fetch(:MULTILINE_DICT)
+      end
+      return TYPES.fetch(:EMPTY_LIST) if peek_string("[]")
+      return TYPES.fetch(:EMPTY_DICT) if peek_string("{}")
+      return TYPES.fetch(:MULTILINE_LIST) if peek_char(pos) == "-"
+      return TYPES.fetch(:INLINE_LIST) if inline_list_at_root?
+
+      TYPES.fetch(:SCALAR)
+    end
+
+    def assert_root_end(val, description)
+      skip_blank_lines
+      unless done?
+        raise error("unexpected content after #{description}")
+      end
+      val
+    end
+
+    def parse_multiline_dict(indent)
+      result = {}
+
+      loop do
+        skip_blank_lines
+        break if done?
+        break if current_indent < indent
+
+        if current_indent != indent
+          raise error("bad indent #{current_indent}, expected #{indent}")
+        end
+
+        unless key_start?
+          raise error("invalid character '#{data[pos]}', expected key")
+        end
+
+        key = parse_key
+
+        if result.include?(key)
+          raise error("duplicat key '#{key}' in dict")
+        end
+
+        indicator = parse_indicator
+
+        result[key] = if indicator == ":"
+          assert_space("after ':'")
+
+          multiline = peek_string("```") || peek_string('""""')
+
+          value = parse_value(current_indent)
+
+          consume_line unless multiline
+          value
+        else
+          parse_vector(current_indent + 2)
+        end
+      end
+
+      result
+    end
+
+    def parse_multiline_list(indent)
+      result = []
+
+      loop do
+        skip_blank_lines
+        break if done?
+        break if current_indent < indent
+
+        if current_indent != indent
+          raise error("bad indent #{current_indent}, expected #{indent}")
+        end
+
+        break if data[pos] != "-"
+
+        advance(1)
+        assert_space("after '-'")
+
+        result << if peek_string("::")
+          # nested vector
+          advance(2)
+          parse_vector(current_indent + 2)
+        else
+          # scalar value
+          parse_value(current_indent).tap do
+            consume_line
+          end
+        end
+      end
+
+      result
+    end
+
+    def multiline_vector_type(indent)
+      skip_blank_lines
+
+      if done? || current_indent < indent
+        raise error("ambiguous empty vector after '::'. Use [] or {}.")
+      end
+
+      if data[pos] == "-"
+        "list"
+      else
+        "dict"
+      end
+    end
+
+    def parse_vector(indent)
+      starting_pos = pos
+      skip_spaces
+
+      if done? || data[pos] == "\n" || data[pos] == "#"
+        self.pos = starting_pos
+        consume_line
+
+        vector_type = multiline_vector_type(indent)
+        next_indent = current_indent
+
+        parse_multiline_method = method(:"parse_multiline_#{vector_type}")
+        return parse_multiline_method.call(next_indent)
+      end
+
+      self.pos = starting_pos
+      assert_space("after '::'")
+
+      parse_inline_vector
+    end
+
+    def parse_inline_vector
+      if peek_string("[]")
+        advance(2)
+        consume_line
+        []
+      elsif peek_string("{}")
+        advance(2)
+        consume_line
+        {}
+      elsif inline_dict?
+        parse_inline_vector_contents(TYPES.fetch(:INLINE_DICT))
+      else
+        parse_inline_vector_contents(TYPES.fetch(:INLINE_LIST))
+      end
+    end
+
+    def parse_inline_vector_contents(type)
+      result = if type == TYPES.fetch(:INLINE_DICT)
+        {}
+      else
+        []
+      end
+
+      @first = nil  # Reset for each new inline vector
+
+      while !done? && data[pos] != "\n" && data[pos] != "#"
+        skip_first do
+          expect_comma
+        end
+
+        if type == TYPES.fetch(:INLINE_DICT)
+          key = parse_key
+          if done? || data[pos] != ":"
+            raise error("expected ':' in inline dict")
+          end
+
+          advance(1)
+          assert_space("in inline dict")
+
+          if result.include?(key)
+            raise error("duplicate key '#{key}' in dict")
+          end
+
+          result[key] = parse_value(0)
+        else
+          result.push(parse_value(0))
+        end
+
+        if !done? && data[pos] == " "
+          next_pos = pos + 1
+
+          next_pos += 1 while next_pos < data.length && data[next_pos] == " "
+          if next_pos < data.length && data[next_pos] == ","
+            skip_spaces
+          else
+            break
+          end
+        end
+      end
+
+      consume_line
+      result
+    end
+
+    def parse_key
+      skip_spaces
+      if peek_char(pos) == '"'
+        return parse_string
+      end
+
+      start = pos
+      while !done? && alpha_numeric?(data[pos]) ||
+          data[pos] == "-" || data[pos] == "_"
+        self.pos += 1
+      end
+
+      if self.pos == start
+        raise error("expected a key")
+      end
+
+      data[start...self.pos]
+    end
+
+    def parse_indicator
+      if done? || data[pos] != ":"
+        raise error("expected ':' or '::' after key")
+      end
+
+      advance(1)
+
+      if !done? && data[pos] == ":"
+        advance(1)
+        return "::"
+      end
+
+      ":"
+    end
+
+    def parse_value(key_indent)
+      if done?
+        raise error("unexpected end of input, expected a value")
+      end
+      character = data[self.pos]
+
+      if character == '"'
+        return peek_string('"""') ? parse_multiline_string(key_indent, false) : parse_string
+      end
+
+      if character == "`" && peek_string("```")
+        return parse_multiline_string(key_indent, true)
+      end
+
+      SPECIAL_VALUES.each do |string, value|
+        if peek_string(string)
+          advance(string.length)
+          return value
+        end
+      end
+
+      if character == "+"
+        advance(1)
+        if peek_string("inf")
+          advance(3)
+          return Float::INFINITY
+        end
+
+        if digit?(peek_char(self.pos))
+          self.pos -= 1
+          return parse_number
+        end
+        raise error("invalid character after '+'")
+      end
+
+      if character == "-"
+        advance(1)
+        if peek_string("inf")
+          advance(3)
+          return -Float::INFINITY
+        end
+
+        if digit?(peek_char(self.pos))
+          self.pos -= 1
+          return parse_number
+        end
+
+        raise error("invalid character after '-'")
+      end
+
+      if digit?(character)
+        return parse_number
+      end
+
+      raise error("unexpected character '#{character}' when parsing value")
+    end
+
+    def parse_string
+      advance(1)
+
+      result = ""
+      until done?
+        character = data[pos]
+
+        case character
+        when '"'
+          advance(1)
+          return result
+        when "\n"
+          raise error("newlines not allowed in single-line strings")
+        when "\\"
+          advance(1)
+          if done?
+            raise error("incomplete escape sequence")
+          end
+
+          escape = data[pos]
+
+          if ESCAPE_MAP.include?(escape)
+            result << ESCAPE_MAP.fetch(escape)
+          else
+            raise error("invalid escape character '\\#{escape}'")
+          end
+        else
+          result << character
+        end
+
+        advance(1)
+      end
+
+      raise error("unclosed string")
+    end
+
+    def parse_multiline_string(key_indent, preserve_spaces)
+      delimiter = data[pos, 3]
+      advance(3)
+      consume_line
+
+      # define line processing base on string type
+      process_line = if preserve_spaces
+        ->(content, line_indent) do
+          # strip required 2-space indent relative to key
+          required_indent = key_indent + 2
+          if content.length >= required_indent && space_string?(content[0, required_indent])
+            return content[required_indent..]
+          end
+
+          content
+        end
+      else
+        ->(content, _line_indent) { content.strip }
+      end
+
+      lines = []
+
+      until done?
+        line_starting_pos = pos
+        line_indent = 0
+
+        # count indentation
+        while !done? && data[pos] == " "
+          line_indent += 1
+          self.pos += 1
+        end
+
+        # check for closing delimiter
+        if peek_string(delimiter)
+          if line_indent != key_indent
+            raise error("multiline closing delimiter must be at same indentation as the key (#{key_indent} spaces)")
+          end
+
+          advance(3)
+          consume_line
+
+          return lines.join("\n")
+        end
+
+        # get line content
+        self.pos = line_starting_pos
+        line_content = consume_line_content
+        lines.push(process_line.call(line_content, line_indent))
+      end
+
+      raise error("unclosed multiline string")
+    end
+
+    # parses numbers in various formats: decimal, hex, octal, binary, float
+    def parse_number
+      starting_pos = pos
+
+      # handle sign
+      next_character = peek_char(pos)
+      if ["+", "-"].include?(next_character)
+        advance(1)
+      end
+
+      NUMBER_BASE_PREFIXES.each do |prefix, base|
+        if peek_string(prefix)
+          parse_base(start: starting_pos, base: base, prefix:)
+        end
+      end
+
+      float = false
+
+      until done?
+        character = data[pos]
+
+        if digit?(character) || character == "_"
+          advance(1) # TODO: make advance always do 1 by default
+        elsif character == "."
+          float = true
+          advance(1)
+        elsif character.downcase == "e"
+          float = true
+          advance(1)
+
+          if ["+", "-"].include?(peek_char(pos))
+            advance(1)
+          end
+        else
+          break
+        end
+      end
+
+      # remove underscores and parse
+      number_string = data[starting_pos...pos].delete("_")
+      begin
+        float ? Float(number_string) : Integer(number_string)
+      rescue ArgumentError => e
+        raise error("invalid number: #{e.message}")
+      end
+    end
+
+    def parse_base(start:, base:, prefix:)
+      advance(prefix.length)
+      number_start = pos
+
+      validators = {
+        16 => ->(c) { hex?(c) },
+        8 => ->(c) { ("0".."7").cover?(c) },
+        2 => ->(c) { ["0", "1"].include?(c) }
+      }
+
+      while !done? && validators.fetch(base).call(data[pos])
+        advance(1)
+      end
+
+      if pos == number_start
+        raise error("invalid number literal, requires digits after prefix")
+      end
+
+      sign = (data[start] == "-") ? -1 : 1
+      number_string = data[number_start...pos].delete("_")
+
+      sign * Integer(number_string, base)
+    end
+
+    def skip_blank_lines
+      until done?
+        line_start = self.pos
+        skip_spaces
+
+        if done?
+          raise error("trailing spaces are not allowed") if self.pos > line_start
+          return
+        end
+
+        if !["\n", "#"].include?(data[self.pos])
+          return # Found content
+        end
+
+        if data[self.pos] == "\n" && self.pos > line_start
+          raise error("trailing spaces are not allowed")
+        end
+
+        self.pos = line_start
+        consume_line
+      end
+    end
+
+    def consume_line
+      content_start = self.pos
+      skip_spaces
+
+      if done? || data[self.pos] == "\n"
+        if self.pos > content_start
+          raise error("trailing spaces are not allowed")
+        end
+      elsif data[self.pos] == "#"
+        if self.pos == content_start && current_indent != self.pos - line_start
+          raise error("a value must be separated from an inline comment by a space")
+        end
+
+        self.pos += 1
+        if !done? && ![" ", "\n"].include?(data[self.pos])
+          raise error("comment hash '#' must be followed by a space")
+        end
+
+      else
+        raise error("unexpected content at end of line")
+      end
+
+      # NOTE: this section has been refactored
+      next_new_line = data.index("\n", self.pos)
+      if next_new_line
+        remaining_line = data[self.pos...next_new_line]
+        if remaining_line.end_with?(" ") && remaining_line.length > 0
+          raise error("trailing spaces are not allowed")
+        end
+
+        self.pos = next_new_line + 1
+        @line += 1
+      else
+        self.pos = data.length
+      end
+    end
+
+    def consume_line_content
+      starting_pos = pos
+      next_newline = data.index("\n", pos)
+
+      if next_newline.nil?
+        # no more newlines, consume to end
+        content = data[starting_pos..]
+        self.pos = data.length
+        return content
+      end
+
+      content = data[starting_pos...next_newline]
+      self.pos = next_newline + 1
+      self.line += 1
+
+      content
+    end
+
+    def assert_space(context)
+      if done? || data[pos] != " "
+        raise error("expected single space #{context}")
+      end
+
+      advance(1)
+
+      if !done? && data[pos] == " "
+        raise error("expected single space #{context}, found multiple")
+      end
+    end
+
+    def expect_comma
+      skip_spaces
+
+      if done? || data[pos] != ","
+        raise error("expected a comma in inline collection")
+      end
+
+      if pos > 0 && data[pos - 1] == " "
+        raise error("no spaces allowed before comma")
+      end
+
+      advance(1)
+      assert_space("after comma")
+    end
+
+    def current_indent
+      start = line_start
+      indent = 0
+      while start + indent < data.length && data[start + indent] == " "
+        indent += 1
+      end
+
+      indent
+    end
+
+    def line_start
+      if self.pos > 0 && self.pos <= data.length && data[self.pos - 1] == "\n"
+        self.pos
+      else
+        return 0 if self.pos <= 0 # prevent -1 array access wrap arounds
+
+        last_newline = data.rindex("\n", self.pos - 1)
+        last_newline ? last_newline + 1 : 0
+      end
+    end
+
+    def key_value_pair?
+      current_pos = self.pos
+      parse_key
+      !done? && data[self.pos] == ":"
+    rescue ParseError
+      false
+    ensure
+      self.pos = current_pos
+    end
+
+    def inline_dict?
+      current_pos = pos
+      while current_pos < data.length && !["\n", "#"].include?(data[current_pos])
+        if data[current_pos] == ":"
+          if current_pos + 1 >= data.length || data[current_pos + 1] != ":"
+            return true
+          end
+        end
+        current_pos += 1
+      end
+      false
+    end
+
+    def inline_list_at_root?
+      line_end = data.index("\n", self.pos) || data.length
+      line = data[self.pos...line_end]
+      comment_index = line.index("#")
+      content = comment_index ? line[0...comment_index] : line
+
+      content.include?(",") && !content.include?(":")
+    end
+
+    def inline_dict_at_root?
+      line_end = data.index("\n", pos) || data.length
+      comment_index = data.index("#", pos) || data.length
+
+      marker = [
+        line_end,
+        comment_index
+      ].min
+
+      line = data[pos...marker]
+      has_colon = line.include?(":") && !line.include?("::")
+      has_comma = line.include?(",")
+
+      return false unless has_colon && has_comma
+
+      remaining_content = if line_end != -1
+        data[0...line_end]
+      else
+        data
+      end.split("\n")[1..].any? do |line|
+        trimmed = line.strip
+        trimmed && !trimmed.start_with?("#")
+      end
+
+      !remaining_content
+    end
+
+    def key_start?
+      !done? && data[pos] == '"' || alpha?(data[pos])
+    end
+
+    def done?
+      self.pos >= data.length
+    end
+
+    def advance(amount)
+      self.pos += amount
+    end
+
+    def skip_spaces
+      while !done? && data[self.pos] == " "
+        advance(1)
+      end
+    end
+
+    def peek_string(string)
+      # really unsure if the start_with? is correct
+      self.pos + string.length <= data.length && data[self.pos..].start_with?(string)
+    end
+
+    def peek_char(position)
+      return data[position] if position >= 0 && position < data.length
+      '\0'
+    end
+
+    def digit?(character)
+      character.match?(/\d/)
+    end
+
+    def alpha?(character)
+      character.match?(/[a-zA-Z]/)
+    end
+
+    def alpha_numeric?(character)
+      alpha?(character) || digit?(character)
+    end
+
+    def hex?(character)
+      digit?(character) ||
+        ("a".."f").cover?(character.downcase)
+    end
+
+    def space_string?(string)
+      string.strip == ""
+    end
+
+    def error(message)
+      ParseError.new(message, self.line)
+    end
+
+    def skip_first
+      return unless block_given?
+
+      @first = true if @first.nil?
+      yield unless @first
+      @first = false
+    end
+
+    class IncompleteMethod < StandardError; end
+  end
+end

data/lib/hummel/encode.rb

@@ -0,0 +1,120 @@
+require "json"
+
+module Hummel
+  module Encode
+    # Regular expression to validate bare keys (no quotes needed)
+    BARE_KEY_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/
+
+    class << self
+      # Convert a Ruby object to HUML format
+      def stringify(obj, cfg = {})
+        lines = []
+        lines.concat(["%HUML v0.1.0", ""]) if cfg[:include_version]
+
+        lines.concat(encode_value(obj, 0, true))
+        lines << "" # Ensure document ends with newline
+
+        lines.join("\n")
+      end
+
+      private
+
+      # Core encoding methods
+
+      # Encode a value to HUML format - returns array of lines
+      def encode_value(value, indent, is_root_level = false)
+        return ["null"] if value.nil?
+
+        case value
+        when TrueClass, FalseClass
+          [value.to_s]
+        when Numeric
+          [format_number(value)]
+        when String
+          encode_string(value, indent)
+        when Array
+          encode_array(value, indent, is_root_level)
+        when Hash
+          encode_object(value, indent, is_root_level)
+        else
+          raise ArgumentError, "Unsupported type: #{value.class}"
+        end
+      end
+
+      # Type-specific encoding methods
+
+      # Format a number for HUML output
+      def format_number(num)
+        return "nan" if num.respond_to?(:nan?) && num.nan?
+        return "inf" if num == Float::INFINITY
+        return "-inf" if num == -Float::INFINITY
+
+        num.to_s
+      end
+
+      # Encode a string value - returns array of lines
+      def encode_string(str, indent)
+        return [str.to_json] unless str.include?("\n")
+
+        # Multi-line string
+        str_lines = str.split("\n")
+        str_lines.pop if str_lines.last && str_lines.last.empty?
+
+        ["```"] + str_lines.map { |line| "#{" " * indent}#{line}" } + ["#{" " * (indent - 2)}```"]
+      end
+
+      # Encode an array value - returns array of lines
+      def encode_array(arr, indent, is_root_level = false)
+        return ["[]"] if arr.empty?
+
+        item_indent = is_root_level ? 0 : indent
+
+        arr.flat_map do |item|
+          item_lines = encode_value(item, item_indent + 2)
+
+          if vector?(item) && !item.empty?
+            # Non-empty vector: "- ::" on one line, value on next lines
+            ["#{" " * item_indent}- ::"] + item_lines
+          else
+            # Scalar or empty vector: "- value" on same line
+            ["#{" " * item_indent}- #{item_lines.first}"] + item_lines[1..]
+          end
+        end
+      end
+
+      # Encode an object value - returns array of lines
+      def encode_object(obj, indent, is_root_level = false)
+        return ["{}"] if obj.empty?
+
+        key_indent = is_root_level ? 0 : indent
+
+        obj.sort_by { |key, _| key.to_s }.flat_map do |key, value|
+          is_vec = vector?(value)
+          value_lines = encode_value(value, key_indent + 2)
+
+          if is_vec && !value.empty?
+            # Non-empty vector: key:: on one line, value on next lines
+            ["#{" " * key_indent}#{quote_key(key)}::"] + value_lines
+          else
+            # Scalar or empty vector: combine key and value on first line
+            separator = is_vec ? ":: " : ": "
+            ["#{" " * key_indent}#{quote_key(key)}#{separator}#{value_lines.first}"] + value_lines[1..]
+          end
+        end
+      end
+
+      # Helper methods
+
+      # Determines if a value is a vector (array or object)
+      def vector?(value)
+        value.is_a?(Array) || value.is_a?(Hash)
+      end
+
+      # Quotes a key if necessary
+      def quote_key(key)
+        key_str = key.to_s
+        BARE_KEY_REGEX.match?(key_str) ? key_str : key_str.to_json
+      end
+    end
+  end
+end

data/lib/hummel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hummel
+  VERSION = "0.1.0"
+end

data/lib/hummel.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "hummel/version"
+require_relative "hummel/decode"
+require_relative "hummel/encode"
+
+module Hummel
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/hummel.rbs

@@ -0,0 +1,4 @@
+module Hummel
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: hummel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Derek Bender
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: HUML (Human Markup Language) is a data serialization format designed
+  for human readability. This gem provides a complete Ruby implementation including
+  a parser for decoding HUML documents and an encoder for converting Ruby objects
+  to HUML format.
+email:
+- 170351+djbender@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".ruby-version"
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/hummel.rb
+- lib/hummel/decode.rb
+- lib/hummel/encode.rb
+- lib/hummel/version.rb
+- sig/hummel.rbs
+homepage: https://github.com/djbender/hummel
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/djbender/hummel
+  source_code_uri: https://github.com/djbender/hummel
+  changelog_uri: https://github.com/djbender/hummel/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby parser and encoder for HUML (Human Markup Language)
+test_files: []