slurm_hostlist 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 995f5429991f0a2fa26b5f7810da33de0ff8f6df6ed6f041a7e340f119248fd0
+  data.tar.gz: 716770221f07852d043f8d3dae881fd0514fd9d202ef3f0387e0efa6e850a818
+SHA512:
+  metadata.gz: f6f7f62383ed60a557b5562f774addc72393b6cb518d1ee38e8bf53f4b7110e411180b8b5a75fed62c680a2377c3b935ba2995b7974db286bb796a438c600c99
+  data.tar.gz: 86d9552ef5c05c3de523efd5406845d477f582b2df3c5fc763553434009a24cf53b747249cd53aeba198e17539eb3139c7920b0ca81f778425e47292829cabac

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `expand`, `compress` (with `sort:`), `count` and `valid?`,
+  plus a `slurm-hostlist` command. Differentially tested against Slurm's
+  `hostlist.c`.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ohio Supercomputer Center
+
+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,152 @@
+# slurm_hostlist
+
+Expand and compress [Slurm](https://slurm.schedmd.com/) hostlist expressions
+in Ruby, getting the same answers Slurm does.
+
+```ruby
+require 'slurm_hostlist'
+
+SlurmHostlist.expand('n[01-03],login1')
+# => ["n01", "n02", "n03", "login1"]
+
+SlurmHostlist.compress(%w[n01 n02 n03 n07 login1])
+# => "n[01-03,07],login1"
+```
+
+No dependencies. It's a port of Slurm's own `src/common/hostlist.c`,
+differentially tested against it, so edge cases that break a quick regex
+work the way Slurm handles them: suffixes after brackets (`node[1-4]-ib`),
+several bracket groups (`rack[1-2]-n[01-16]`), and mixed zero-padding.
+
+## Install
+
+```sh
+gem install slurm_hostlist
+```
+
+or in a Gemfile:
+
+```ruby
+gem 'slurm_hostlist'
+```
+
+Ruby 2.7 or newer.
+
+## Usage
+
+| Call | Same as |
+|---|---|
+| `SlurmHostlist.expand(expression)` → `Array<String>` | `scontrol show hostnames` |
+| `SlurmHostlist.compress(hosts)` → `String` | `scontrol show hostlist` |
+| `SlurmHostlist.compress(hosts, sort: true)` → `String` | `scontrol show hostlistsorted` |
+| `SlurmHostlist.count(expression)` → `Integer` | number of hosts, duplicates included |
+| `SlurmHostlist.valid?(expression)` → `true`/`false` | whether Slurm accepts it |
+
+`compress` takes an array of host names or an expression string. Input
+Slurm would reject (`n[3-1]`, `n[1`, `n[]`) raises
+`SlurmHostlist::InvalidHostlist`, a subclass of `ArgumentError`.
+
+```ruby
+SlurmHostlist.expand('rack[1-2]-n[1-2]')
+# => ["rack1-n1", "rack1-n2", "rack2-n1", "rack2-n2"]
+
+SlurmHostlist.compress(%w[n3 n1 n2])              # => "n[3,1-2]"   (order kept)
+SlurmHostlist.compress(%w[n3 n1 n2], sort: true)  # => "n[1-3]"
+
+SlurmHostlist.expand(ENV.fetch('SLURM_JOB_NODELIST'))
+```
+
+A command is included too:
+
+```sh
+$ slurm-hostlist expand 'n[01-03]'
+n01
+n02
+n03
+$ slurm-hostlist compress n01 n02 n03
+n[01-03]
+$ squeue -h -o %N | slurm-hostlist compress --sort
+```
+
+## Behaviour worth knowing
+
+These all match Slurm:
+
+- **Order and duplicates are kept.** `expand('n[1-3],n2')` gives
+  `n1 n2 n3 n2`. Without `sort: true`, `compress` only joins a host onto the
+  range just before it, so `%w[n3 n1 n2]` gives `n[3,1-2]`.
+- **Zero-padding comes from the low number.** `n[01-3]` gives
+  `n01 n02 n03`; `n[1-02]` gives `n1 n2`.
+- **Padding that can't be shared stays apart.** `%w[n01 n1 n2]` compresses to
+  `n[01,1-2]`, but `%w[n9 n10]` to `n[9-10]`.
+- **Hosts from a bracket with a suffix aren't re-bracketed.** Compressing
+  `node[1-2]-ib` gives `node1-ib,node2-ib`.
+- **With three or more bracket groups, Slurm's order isn't left-to-right:**
+  in `a[1-2]b[3-4]c[5-6]` the *middle* group changes slowest
+  (`a1b3c5 a1b3c6 a2b3c5 a2b3c6 a1b4c5 ...`).
+- **Numbers are read with C's `strtoul`**, quirks included: `n[+3]` and
+  `n[ 3]` give `n03` (width comes from the text as written), and `n[5-]`
+  gives `n5`.
+
+## How it's checked against Slurm
+
+- **Differential testing.** `script/differential` generates random
+  expressions, realistic ones and deliberately odd ones, and compares this
+  gem with Slurm on all three operations. Before the first release it ran
+  300,000 cases against Slurm's `hostlist.c` (Slurm `master`, built the way
+  production Slurm is, with asserts off) with no differences.
+  `script/oracle/build.sh` rebuilds that oracle from Slurm's source (it needs
+  only git and gcc), and
+  `script/differential --oracle script/oracle/build/hostlist_oracle` runs the
+  comparison.
+- **Recorded cases in CI.** `test/fixtures/slurm_cases.jsonl` holds about
+  3,000 cases and Slurm's answers, recorded with `script/record_fixtures`, and
+  the test suite replays them, so CI checks against Slurm without Slurm
+  installed.
+- **Check against your own Slurm.** On any machine with `scontrol`:
+
+  ```sh
+  script/differential --scontrol --cases 1000
+  ```
+
+## Known differences and limits
+
+- **Host numbers of 18446744073709551615 (2⁶⁴ − 1) or more are rejected.**
+  Current Slurm rejects them too, but released versions before SchedMD
+  commit `0266d18d3e` (September 2026) accept them: the number silently
+  becomes 18446744073709551615 (a different host), and a range ending there
+  can run the parser out of memory. Against an older `scontrol`,
+  `script/differential` counts these separately. Real clusters don't number
+  hosts anywhere near this.
+- **Sorted output in cases where Slurm itself misbehaves.** For some inputs,
+  Slurm's `hostlistsorted` code reads memory it has already freed, so its
+  output depends on how Slurm was compiled. For
+  `rack[17-21,18446744073709551614]`, one build of Slurm's code returned
+  `rack[18446744073709551614]` (five hosts dropped) and another returned
+  something else. There's nothing reliable to match there. It takes unusual input, such as host
+  numbers 2³¹ or more apart, or mixed padding widths that overlap, and
+  `Hostlist#diverged_from_slurm?` reports when it happens. `expand` and
+  unsorted `compress` never go down that path.
+- **`{...}` hostlist functions** are expanded by slurmctld, not by the
+  hostlist code, so they're treated as literal text, as Slurm does when no
+  controller is reachable.
+- **Multi-dimensional (3D/4D) node naming**, from Slurm builds configured
+  for more than one dimension, isn't supported. This covers ordinary
+  one-dimensional clusters, which is what current Slurm installs use.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+To re-record the fixture from a local Slurm:
+
+```sh
+script/record_fixtures --scontrol
+```
+
+## License
+
+MIT. Copyright Ohio Supercomputer Center.

data/exe/slurm-hostlist

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# slurm-hostlist expand 'n[01-03],login1'      one host per line
+# slurm-hostlist compress n01 n02 n03          n[01-03]
+# slurm-hostlist compress --sort < hosts.txt   hosts from stdin, sorted
+# slurm-hostlist count 'n[1-100]'              100
+
+require 'slurm_hostlist'
+
+USAGE = <<~TEXT
+  usage: slurm-hostlist expand EXPRESSION
+         slurm-hostlist compress [--sort] [HOST ...]   (reads stdin if no hosts given)
+         slurm-hostlist count EXPRESSION
+TEXT
+
+command = ARGV.shift
+begin
+  case command
+  when 'expand'
+    abort USAGE if ARGV.length != 1
+    puts SlurmHostlist.expand(ARGV.first)
+  when 'compress'
+    sort = ARGV.delete('--sort') ? true : false
+    hosts = ARGV.empty? ? $stdin.read.split : ARGV
+    puts SlurmHostlist.compress(hosts, sort: sort)
+  when 'count'
+    abort USAGE if ARGV.length != 1
+    puts SlurmHostlist.count(ARGV.first)
+  when '-v', '--version'
+    puts SlurmHostlist::VERSION
+  else
+    abort USAGE
+  end
+rescue SlurmHostlist::InvalidHostlist => e
+  abort "slurm-hostlist: #{e.message}"
+end

data/lib/slurm_hostlist/host_range.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SlurmHostlist
+  # One run of hosts sharing a prefix and a zero-padding width, e.g. the
+  # "n[01-04]" in "n[01-04],login1". A host with no trailing number (or one
+  # expanded from a bracket followed by a suffix, like "node1-ib") is stored
+  # as a "single" host whose prefix is the whole name.
+  #
+  # Mirrors Slurm's hostrange_t. The fields are mutable on purpose: Slurm
+  # adjusts widths in place when it decides two ranges can merge, and the
+  # output depends on that.
+  class HostRange
+    attr_accessor :prefix, :lo, :hi, :width, :single
+
+    def self.single(name)
+      new(name, 0, 0, 0, true)
+    end
+
+    def initialize(prefix, lo, hi, width, single = false)
+      @prefix = prefix
+      @lo = lo
+      @hi = hi
+      @width = width
+      @single = single
+    end
+
+    def count
+      return 1 if single
+
+      hi - lo + 1
+    end
+
+    # The host names in this range, in order.
+    def hosts
+      return [prefix] if single
+
+      (lo..hi).map { |n| prefix + SlurmHostlist.pad(n, width) }
+    end
+
+    # The numeric part as written inside brackets: "01" or "01-04".
+    # Slurm's hostrange_numstr().
+    def numstr
+      return '' if single
+
+      text = SlurmHostlist.pad(lo, width)
+      text += "-#{SlurmHostlist.pad(hi, width)}" if lo < hi
+      text
+    end
+
+    def copy
+      return HostRange.single(prefix) if single
+
+      HostRange.new(prefix, lo, hi, width)
+    end
+  end
+
+  # Slurm's "%0*lu": the number, left-padded with zeros to width.
+  def self.pad(number, width)
+    number.to_s.rjust(width, '0')
+  end
+end

data/lib/slurm_hostlist/hostlist.rb

@@ -0,0 +1,517 @@
+# frozen_string_literal: true
+
+module SlurmHostlist
+  # A parsed hostlist: an ordered list of HostRange objects.
+  #
+  # This is a port of the parts of Slurm's src/common/hostlist.c that back
+  # `scontrol show hostnames`, `show hostlist` and `show hostlistsorted`.
+  # Method comments name the C function each one follows, so behaviour can be
+  # checked against Slurm line by line.
+  class Hostlist
+    ULONG_MAX = (2**64) - 1
+    MAX_RANGE = 64 * 1024        # hosts in one bracket range (MAX_SLURM_NODES)
+    MAX_PREFIX_CNT = 64 * 1024   # hosts from brackets earlier in a name
+    MAX_RANGES = 256 * 1024      # comma-separated ranges in one bracket
+    # Binary, like the text they're compared against (parsing works on bytes).
+    SEPARATORS = "\t, \n".b.freeze
+    SPACES = " \t\n\v\f\r".b.freeze
+
+    attr_reader :ranges
+
+    def initialize(ranges = [])
+      @ranges = ranges
+      @diverged_from_slurm = false
+    end
+
+    # True if sort! went down a path where Slurm reads freed memory, so
+    # Slurm's own output can't be reproduced (see #coalesce).
+    def diverged_from_slurm?
+      @diverged_from_slurm
+    end
+
+    # Parse a hostlist expression. Raises InvalidHostlist when Slurm would
+    # reject it. Slurm's _hostlist_create_bracketed().
+    def self.parse(expression)
+      text = expression.to_s.b
+      # C strings end at the first NUL.
+      nul = text.index("\0")
+      text = text[0...nul] if nul
+
+      list = new
+      tokens(text).each do |token|
+        ok = list.push_token(token)
+        raise InvalidHostlist, "invalid hostlist: #{expression}" unless ok
+      end
+      list
+    end
+
+    # Split on separators, keeping bracketed parts together:
+    # "a[1,2],b" is two tokens, "a[1,2]" and "b". Slurm's _next_tok().
+    def self.tokens(text)
+      tokens = []
+      length = text.length
+      pos = 0
+
+      loop do
+        pos += 1 while pos < length && separator?(text[pos])
+        break if pos >= length
+
+        start = pos
+        parse = pos
+        pos = scan_token_end(text, pos, parse)
+        tokens << text[start...pos]
+        pos += 1 while pos < length && separator?(text[pos])
+      end
+
+      tokens
+    end
+
+    # Find where the token starting at pos ends. A separator inside a
+    # [...] pair doesn't end the token.
+    def self.scan_token_end(text, pos, parse)
+      length = text.length
+      loop do
+        pos += 1 while pos < length && !separator?(text[pos])
+
+        extended = false
+        loop do
+          open = text.index('[', parse)
+          return pos if open.nil? || open >= pos
+
+          close = text.index(']', parse)
+          return pos if close.nil? || close < open
+
+          if close < pos
+            parse = close + 1
+          else
+            pos = close
+            extended = true
+            break
+          end
+        end
+        return pos unless extended
+      end
+    end
+
+    def self.separator?(char)
+      SEPARATORS.include?(char)
+    end
+
+    # C's strtoul(), base 10. Returns [value, index after the number], with
+    # index 0 when nothing was converted. Skips leading whitespace, takes an
+    # optional sign, and clamps overflow to ULONG_MAX, as glibc does.
+    def self.strtoul(text)
+      i = 0
+      i += 1 while i < text.length && SPACES.include?(text[i])
+
+      negative = false
+      if text[i] == '+' || text[i] == '-'
+        negative = (text[i] == '-')
+        i += 1
+      end
+
+      digits_start = i
+      i += 1 while i < text.length && text[i] >= '0' && text[i] <= '9'
+      return [0, 0] if i == digits_start
+
+      magnitude = text[digits_start...i].to_i
+      value = if magnitude > ULONG_MAX
+                ULONG_MAX
+              elsif negative
+                (ULONG_MAX + 1 - magnitude) % (ULONG_MAX + 1)
+              else
+                magnitude
+              end
+      [value, i]
+    end
+
+    # One entry inside brackets: "7", "01-16". Returns [lo, hi, width] or nil.
+    # The width is the length of the low number as written.
+    # Slurm's _parse_single_range().
+    def self.parse_single_range(text)
+      return nil if text.include?('x') # "boxes" are for multi-dimensional systems
+
+      dash = text.index('-')
+      if dash
+        lo_text = text[0...dash]
+        hi_text = text[(dash + 1)..]
+        return nil if hi_text.start_with?('-') # no negative numbers
+      else
+        lo_text = text
+        hi_text = nil
+      end
+
+      width = lo_text.length
+      lo, lo_end = strtoul(lo_text)
+      return nil if lo_end.zero?
+
+      if hi_text && !hi_text.empty?
+        hi, hi_end = strtoul(hi_text)
+        return nil if hi_end.zero? || hi_end != hi_text.length
+      else
+        hi = lo
+        return nil if lo_end != lo_text.length
+      end
+
+      return nil if hi == ULONG_MAX
+      return nil if lo > hi
+      return nil if hi - lo + 1 > MAX_RANGE
+
+      [lo, hi, width]
+    end
+
+    # "1-3,7,10-12" -> [[1, 3, 1], [7, 7, 1], [10, 12, 2]], or nil if any
+    # entry is invalid. Slurm's _parse_range_list().
+    def self.parse_range_list(text)
+      entries = text.empty? ? [''] : text.split(',', -1)
+      raise InvalidHostlist, 'too many ranges' if entries.length > MAX_RANGES
+
+      ranges = []
+      entries.each do |entry|
+        range = parse_single_range(entry)
+        return nil if range.nil?
+
+        ranges << range
+      end
+      ranges
+    end
+
+    # Add one token: a plain host name or a bracketed expression.
+    # Returns false if Slurm would reject it.
+    def push_token(token)
+      open = token.rindex('[')
+      return push_host(token) if open.nil?
+
+      prefix = token[0...open]
+      rest = token[(open + 1)..]
+      close = rest.index(']')
+      return false if close.nil?
+
+      after = rest[(close + 1)..]
+      suffix = after.empty? || after.start_with?(',') ? nil : after
+
+      ranges = self.class.parse_range_list(rest[0...close])
+      return false if ranges.nil?
+
+      push_range_list(prefix, suffix, ranges) == 0
+    end
+
+    # Expand any brackets left in the prefix ("rack[1-2]-n" in
+    # "rack[1-2]-n[1-4]"), then push the ranges for each resulting prefix.
+    # Returns 0 or -1. Slurm's _push_range_list().
+    def push_range_list(prefix, suffix, ranges)
+      open = prefix.rindex('[')
+      close = prefix.rindex(']')
+      unless open && close && close > open
+        ranges.each { |lo, hi, width| push_hr(prefix, suffix, lo, hi, width) }
+        return 0
+      end
+
+      head = prefix[0...open]
+      tail = prefix[(close + 1)..]
+      recurse = head.include?('[')
+
+      prefix_ranges = self.class.parse_range_list(prefix[(open + 1)...close])
+      return -1 if prefix_ranges.nil?
+
+      prefix_count = 0
+      prefix_ranges.each do |lo, hi, width|
+        prefix_count += hi - lo + 1
+        return -1 if prefix_count > MAX_PREFIX_CNT
+
+        (lo..hi).each do |n|
+          new_prefix = head + SlurmHostlist.pad(n, width) + tail
+          if recurse
+            # Slurm keeps MAX(rc, rc1) starting from 0, so a failure in a
+            # deeper bracket is ignored rather than failing the whole list.
+            push_range_list(new_prefix, suffix, ranges)
+          else
+            ranges.each { |r_lo, r_hi, r_width| push_hr(new_prefix, suffix, r_lo, r_hi, r_width) }
+          end
+        end
+      end
+      0
+    end
+
+    # Push a range. With a suffix ("node[1-2]-ib"), each host is pushed as a
+    # whole name, so it is never re-bracketed. Slurm's hostlist_push_hr().
+    def push_hr(prefix, suffix, lo, hi, width)
+      if suffix
+        (lo..hi).each do |n|
+          push_range(HostRange.single(prefix + SlurmHostlist.pad(n, width) + suffix))
+        end
+      else
+        push_range(HostRange.new(prefix, lo, hi, width))
+      end
+    end
+
+    # Push a plain host name, splitting off any trailing number.
+    # Slurm's hostlist_push_host_dims() and _parse_hostname_len().
+    def push_host(name)
+      idx = name.length - 1
+      idx -= 1 while idx >= 0 && name[idx] >= '0' && name[idx] <= '9'
+      prefix_length = idx + 1
+
+      if prefix_length == name.length
+        push_range(HostRange.single(name))
+        return true
+      end
+
+      number = name[prefix_length..].to_i
+      return false if number >= ULONG_MAX
+
+      width = name.length - prefix_length
+      push_range(HostRange.new(name[0...prefix_length], number, number, width))
+      true
+    end
+
+    # Append a range, merging it into the last one when it continues it.
+    # Only the last range is considered, so input order matters.
+    # Slurm's hostlist_push_range().
+    def push_range(range)
+      last = @ranges.last
+      if last &&
+         last.hi == range.lo - 1 &&
+         self.class.prefix_cmp(last, range).zero? &&
+         self.class.width_combine(last, range)
+        last.hi = range.hi
+      else
+        @ranges << range.copy
+      end
+    end
+
+    def hosts
+      @ranges.flat_map(&:hosts)
+    end
+
+    # The compressed form, e.g. "n[1-3,5],login1".
+    # Slurm's hostlist_ranged_string() and _get_bracketed_list().
+    def to_s
+      parts = []
+      i = 0
+      while i < @ranges.length
+        part, i = bracketed_list(i)
+        parts << part
+      end
+      parts.join(',')
+    end
+
+    def bracketed_list(start)
+      first = @ranges[start]
+      following = @ranges[start + 1]
+      needs_brackets = first.count > 1 || self.class.within_range(first, following)
+
+      text = first.prefix.dup
+      text << '[' if needs_brackets
+
+      i = start
+      loop do
+        text << ',' if i > start
+        text << @ranges[i].numstr
+        i += 1
+        break unless i < @ranges.length && self.class.within_range(@ranges[i], @ranges[i - 1])
+      end
+
+      text << ']' if needs_brackets
+      [text, i]
+    end
+
+    # --- sorting (scontrol show hostlistsorted) --------------------------------
+
+    # Sort, then merge overlapping and adjacent ranges. Duplicates are kept.
+    # Slurm's hostlist_sort().
+    def sort!
+      return self if @ranges.length <= 1
+
+      @ranges = self.class.merge_sort(@ranges)
+      coalesce
+      collapse
+      self
+    end
+
+    # glibc's qsort() is a top-down merge sort (msort.c). The comparison can
+    # change widths as a side effect, so the order comparisons happen in
+    # matters; this follows msort's exactly.
+    def self.merge_sort(items)
+      return items.dup if items.length <= 1
+
+      left_size = items.length / 2
+      left = merge_sort(items[0...left_size])
+      right = merge_sort(items[left_size..])
+
+      merged = []
+      li = 0
+      ri = 0
+      while li < left.length && ri < right.length
+        if range_cmp(left[li], right[ri]) <= 0
+          merged << left[li]
+          li += 1
+        else
+          merged << right[ri]
+          ri += 1
+        end
+      end
+      merged.concat(left[li..]) if li < left.length
+      merged.concat(right[ri..]) if ri < right.length
+      merged
+    end
+
+    # Order by prefix (natural order), then by first number, or by width when
+    # widths can't be combined. Slurm's hostrange_cmp(); the result is a C
+    # int, so a large difference is truncated to 32 bits as it is there.
+    def self.range_cmp(first, second)
+      result = prefix_cmp(first, second)
+      return result unless result.zero?
+
+      if width_combine(first, second)
+        c_int(first.lo - second.lo)
+      else
+        first.width - second.width
+      end
+    end
+
+    def self.c_int(value)
+      low = value & 0xFFFFFFFF
+      low >= 2**31 ? low - 2**32 : low
+    end
+
+    # Split overlapping neighbours so no host appears in two ranges, keeping
+    # the duplicates as their own one-host ranges. Slurm's hostlist_coalesce().
+    def coalesce
+      i = @ranges.length - 1
+      while i > 0
+        overlap = self.class.intersect(@ranges[i - 1], @ranges[i])
+        if overlap
+          previous = @ranges[i - 1]
+          following = @ranges[i]
+          insert_at = i
+
+          following.hi = previous.hi if overlap.hi < previous.hi
+          previous.hi = overlap.lo
+          following.lo = overlap.hi
+
+          # Slurm removes index i here (the following range, not the empty
+          # one) and then keeps reading the range it just freed, so what
+          # Slurm outputs from this point on is undefined; it can drop hosts.
+          # Flag it so callers and the differential test can tell.
+          if previous.hi < previous.lo
+            @diverged_from_slurm = true
+            delete_range(i)
+          end
+
+          while overlap.lo <= overlap.hi
+            one = HostRange.new(overlap.prefix, overlap.lo, overlap.lo, overlap.width)
+            # Slurm's j++ advances even when the insert is skipped.
+            if overlap.lo > previous.hi
+              insert_range(one, insert_at)
+              insert_at += 1
+            end
+            if overlap.lo < following.lo
+              insert_range(one, insert_at)
+              insert_at += 1
+            end
+            overlap.lo += 1
+          end
+          i = @ranges.length
+        end
+        i -= 1
+      end
+    end
+
+    # Join neighbours that continue each other. Slurm's hostlist_collapse().
+    def collapse
+      i = @ranges.length - 1
+      while i > 0
+        previous = @ranges[i - 1]
+        following = @ranges[i]
+        if previous.hi == following.lo - 1 &&
+           self.class.prefix_cmp(previous, following).zero? &&
+           self.class.width_combine(previous, following)
+          previous.hi = following.hi
+          delete_range(i)
+        end
+        i -= 1
+      end
+    end
+
+    # The hosts two ranges share, as a new range, or nil.
+    # Slurm's hostrange_intersect().
+    def self.intersect(first, second)
+      return nil if first.single || second.single
+      return nil unless first.hi > second.lo
+      return nil unless prefix_cmp(first, second).zero?
+      return nil unless width_combine(first, second)
+
+      overlap = first.copy
+      overlap.lo = second.lo
+      overlap.hi = [second.hi, first.hi].min
+      overlap
+    end
+
+    # Slurm's hostlist_insert_range(): a copy goes in; nothing happens if the
+    # position is past the end.
+    def insert_range(range, position)
+      return false if position > @ranges.length
+
+      @ranges.insert(position, range.copy)
+      true
+    end
+
+    def delete_range(position)
+      @ranges.delete_at(position)
+    end
+
+    # --- comparisons ---------------------------------------------------------
+
+    # 0 when both ranges share a prefix and both are (or both aren't) single
+    # hosts. Slurm's hostrange_prefix_cmp().
+    def self.prefix_cmp(first, second)
+      return 1 if first.nil?
+      return -1 if second.nil?
+
+      result = if first.prefix == second.prefix
+                 0
+               else
+                 NaturalCompare.compare(first.prefix, second.prefix)
+               end
+      return result unless result.zero?
+
+      (second.single ? 1 : 0) - (first.single ? 1 : 0)
+    end
+
+    # True when two ranges belong inside the same brackets.
+    # Slurm's hostrange_within_range().
+    def self.within_range(first, second)
+      return false unless prefix_cmp(first, second).zero?
+
+      !first.single && !second.single
+    end
+
+    # Can two ranges share one zero-padding width without changing any host
+    # name? If so, one width is adjusted in place to match the other.
+    # Slurm's hostrange_width_combine() and _width_equiv().
+    def self.width_combine(first, second)
+      return true if first.width == second.width
+
+      first_pad = zero_padding(first.lo, first.width)
+      first_pad_other = zero_padding(first.lo, second.width)
+      second_pad = zero_padding(second.lo, second.width)
+      second_pad_other = zero_padding(second.lo, first.width)
+
+      return false if first_pad != first_pad_other && second_pad != second_pad_other
+
+      if first_pad != first_pad_other
+        second.width = first.width
+      else
+        first.width = second.width
+      end
+      true
+    end
+
+    # Zeros needed to pad number to width. Slurm's _zero_padded().
+    def self.zero_padding(number, width)
+      digits = number.to_s.length
+      width > digits ? width - digits : 0
+    end
+  end
+end

data/lib/slurm_hostlist/natural_compare.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SlurmHostlist
+  # Slurm's natural-order string comparison (strnatcmp, by Martin Pool), ported
+  # so prefix ordering and "same prefix" checks agree with Slurm exactly.
+  # Works on bytes, as the C original does. Returns -1, 0 or 1.
+  module NaturalCompare
+    ZERO = 48
+    NINE = 57
+    # C isspace() in the "C" locale: space, \t, \n, \v, \f, \r
+    SPACES = [32, 9, 10, 11, 12, 13].freeze
+
+    module_function
+
+    def compare(a, b)
+      a = a.bytes
+      b = b.bytes
+      ai = 0
+      bi = 0
+
+      loop do
+        ca = a[ai]
+        cb = b[bi]
+
+        # Skip leading whitespace.
+        while space?(ca)
+          ai += 1
+          ca = a[ai]
+        end
+        while space?(cb)
+          bi += 1
+          cb = b[bi]
+        end
+
+        # Compare a run of digits.
+        if digit?(ca) && digit?(cb)
+          fractional = (ca == ZERO || cb == ZERO)
+          result = if fractional
+                     compare_left(a, ai, b, bi)
+                   else
+                     compare_right(a, ai, b, bi)
+                   end
+          return result if result != 0
+        end
+
+        return 0 if ca.nil? && cb.nil?
+
+        return -1 if signed(ca) < signed(cb)
+        return 1 if signed(ca) > signed(cb)
+
+        ai += 1
+        bi += 1
+      end
+    end
+
+    # Right-aligned numbers: the longest run of digits wins; at equal length,
+    # the first differing digit decides.
+    def compare_right(a, ai, b, bi)
+      bias = 0
+      loop do
+        ca = a[ai]
+        cb = b[bi]
+
+        return bias if !digit?(ca) && !digit?(cb)
+        return -1 unless digit?(ca)
+        return 1 unless digit?(cb)
+
+        if ca < cb
+          bias = -1 if bias.zero?
+        elsif ca > cb
+          bias = 1 if bias.zero?
+        end
+
+        ai += 1
+        bi += 1
+      end
+    end
+
+    # Left-aligned numbers (one starts with 0): the first different digit wins.
+    def compare_left(a, ai, b, bi)
+      loop do
+        ca = a[ai]
+        cb = b[bi]
+
+        return 0 if !digit?(ca) && !digit?(cb)
+        return -1 unless digit?(ca)
+        return 1 unless digit?(cb)
+        return -1 if ca < cb
+        return 1 if ca > cb
+
+        ai += 1
+        bi += 1
+      end
+    end
+
+    # nil is the end of the string (C's NUL). C's char is signed on the
+    # platforms Slurm runs on, so bytes above 127 compare as negative.
+    def signed(byte)
+      return 0 if byte.nil?
+
+      byte > 127 ? byte - 256 : byte
+    end
+
+    def digit?(byte)
+      !byte.nil? && byte >= ZERO && byte <= NINE
+    end
+
+    def space?(byte)
+      !byte.nil? && SPACES.include?(byte)
+    end
+  end
+end

data/lib/slurm_hostlist/version.rb

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

data/lib/slurm_hostlist.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'slurm_hostlist/version'
+require_relative 'slurm_hostlist/natural_compare'
+require_relative 'slurm_hostlist/host_range'
+require_relative 'slurm_hostlist/hostlist'
+
+# Expand and compress Slurm hostlist expressions, matching Slurm's own
+# behaviour (`scontrol show hostnames`, `show hostlist`, `show hostlistsorted`).
+#
+#   SlurmHostlist.expand('n[01-03],login1')   # => ["n01", "n02", "n03", "login1"]
+#   SlurmHostlist.compress(%w[n1 n2 n3 n7])   # => "n[1-3,7]"
+module SlurmHostlist
+  # Raised for input Slurm itself would reject, e.g. "n[3-1]" or "n[1-".
+  class InvalidHostlist < ArgumentError; end
+
+  module_function
+
+  # Expand an expression into host names, in Slurm's order and keeping
+  # duplicates. Like `scontrol show hostnames`.
+  #
+  #   expand('rack[1-2]-n[1-2]')  # => ["rack1-n1", "rack1-n2", "rack2-n1", "rack2-n2"]
+  #   expand('')                  # => []
+  def expand(expression)
+    encoding = encoding_of(expression)
+    Hostlist.parse(expression).hosts.map { |host| host.force_encoding(encoding) }
+  end
+
+  # Compress host names (an Array, or an expression String) into Slurm's
+  # compact form. Like `scontrol show hostlist`: input order is kept and
+  # duplicates aren't removed. With sort: true, like
+  # `scontrol show hostlistsorted`.
+  #
+  #   compress(%w[n3 n1 n2])              # => "n[3,1-2]"
+  #   compress(%w[n3 n1 n2], sort: true)  # => "n[1-3]"
+  def compress(hosts, sort: false)
+    expression = hosts.is_a?(Array) ? hosts.join(',') : hosts.to_s
+    list = Hostlist.parse(expression)
+    list.sort! if sort
+    list.to_s.force_encoding(encoding_of(expression))
+  end
+
+  # Number of hosts an expression expands to, duplicates included.
+  def count(expression)
+    Hostlist.parse(expression).ranges.sum(&:count)
+  end
+
+  # True if Slurm would accept the expression.
+  def valid?(expression)
+    Hostlist.parse(expression)
+    true
+  rescue InvalidHostlist
+    false
+  end
+
+  def encoding_of(value)
+    value.is_a?(String) ? value.encoding : Encoding::UTF_8
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: slurm_hostlist
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Travis Ravert
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Pure Ruby, dependency-free expansion and compression of Slurm hostlist
+  expressions like "n[01-16],login[1-2]". A port of Slurm's hostlist.c,
+  differentially tested against Slurm to give the same results as
+  `scontrol show hostnames`, `show hostlist` and `show hostlistsorted`.
+email:
+- travert@osc.edu
+executables:
+- slurm-hostlist
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/slurm-hostlist
+- lib/slurm_hostlist.rb
+- lib/slurm_hostlist/host_range.rb
+- lib/slurm_hostlist/hostlist.rb
+- lib/slurm_hostlist/natural_compare.rb
+- lib/slurm_hostlist/version.rb
+homepage: https://github.com/Oglopf/slurm_hostlist
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Oglopf/slurm_hostlist
+  changelog_uri: https://github.com/Oglopf/slurm_hostlist/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Expand and compress Slurm hostlists, matching Slurm's own output
+test_files: []