wildling 2.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17473f92bca01e0d3a1d43266416823b2464bec246c23533db1f7e316a1b527b
+  data.tar.gz: 9b5856610a2df75531421c54edc2251bf468987a9c0023caf8d03603318e0781
+SHA512:
+  metadata.gz: d28a9bed8d486cb9386090cd6172e0de961ba57be9195ab24964a72cba41fbff3b4fdd2ed1b96ab11c74b1b977df133ac4ad6c7192eefc6b5edd194b40f20c0c
+  data.tar.gz: 4db4fb08a085f3810888f4c43608265a7596fadc0af4cf93dbaf695c94236110960ef474217eca981d70c675c0c1c3a68a202671359bc91e28763796fecd24ce

data/README.md

@@ -0,0 +1,76 @@
+# wildling
+
+Ruby library and CLI for pattern-based string generation. **Zero third-party gems** (stdlib only, including `json`). Requires Ruby 3.0+.
+
+<!-- wildling:preamble -->
+**Docs:** [Website](https://dotmonk.github.io/wildling/) · [Sandbox](https://dotmonk.github.io/wildling/sandbox.html) · [Syntax](https://dotmonk.github.io/wildling/syntax.html) · [Source](https://github.com/dotmonk/wildling/tree/main/ruby)
+
+**Registry:** [RubyGems](https://rubygems.org/gems/wildling)
+
+## Example
+
+```text
+http://${'dev,stage,prod'}\-${'api,web'}#{0-2}.example.${'com,net,org'}/@.html
+```
+
+(The `\-` is a literal hyphen; bare `-` would mean “one letter or digit”. `@` is one lowercase letter.)
+
+That builds **URL-shaped** candidates: scheme `http://`, then environment × service × optional digits × TLD, then a one-letter path page. Three environments, two services, zero–two digits (`''`, `0`–`9`, `00`–`99`), three TLDs, and `a`–`z` → **51948** strings — the kind of list you generate for fuzzing links or probing staging hosts, not type out.
+
+A few of them:
+
+- `http://dev-api.example.com/a.html` / `http://stage-web.example.com/z.html`
+- `http://dev-api0.example.net/a.html` / `http://prod-web9.example.org/m.html`
+- `http://dev-api00.example.com/a.html` / `http://prod-web99.example.org/z.html`
+
+Named dictionaries (`%{'hosts'}`) work the same way when the word lists live in files.
+
+Try it in the [sandbox](https://dotmonk.github.io/wildling/sandbox.html?pattern=http%3A%2F%2F%24%7B%27dev%2Cstage%2Cprod%27%7D%5C-%24%7B%27api%2Cweb%27%7D%23%7B0-2%7D.example.%24%7B%27com%2Cnet%2Corg%27%7D%2F%40.html), or see [pattern syntax](https://dotmonk.github.io/wildling/syntax.html) for length ranges, dictionaries, and escapes.
+<!-- /wildling:preamble -->
+
+## Install
+
+From this repository:
+
+```bash
+cd ruby
+./build.sh
+./bin/wildling "Year 19##"
+```
+
+**Git (Bundler):**
+
+```ruby
+gem "wildling", git: "https://github.com/dotmonk/wildling.git", tag: "v2.0.0", glob: "ruby/wildling.gemspec"
+```
+
+**Registry:** `gem install wildling`
+
+```ruby
+require_relative "lib/wildling"
+
+wildling = Wildling.create(["Year 19##"])
+value = wildling.next
+while value != false
+  puts value
+  value = wildling.next
+end
+```
+
+## CLI
+
+```bash
+./bin/wildling "Year 19##"
+./bin/wildling --dictionary planets:../dictionaries/planets.txt "%{'planets'}"
+./bin/wildling --template ./config.json
+```
+
+Help text and `--check` output follow [`docs/cli.md`](../docs/cli.md) / [`docs/help.txt`](../docs/help.txt).
+
+## Build
+
+```bash
+./build.sh   # Docker (ruby:3.3-alpine): copy help.txt + syntax-check
+```
+
+Project tests live in `../tests/` and are run with `../test.sh`.

data/bin/wildling

@@ -0,0 +1,29 @@
+#!/bin/sh
+DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$DIR/.." && pwd)"
+ENTRY="$DIR/wildling.rb"
+
+ensure_help() {
+    if [ ! -f "$ROOT/lib/wildling/help.txt" ] && [ -f "$ROOT/../docs/help.txt" ]; then
+        cp "$ROOT/../docs/help.txt" "$ROOT/lib/wildling/help.txt"
+    fi
+}
+
+if command -v ruby >/dev/null 2>&1; then
+    ensure_help
+    exec ruby "$ENTRY" "$@"
+fi
+
+ensure_help
+if [ ! -f "$ROOT/lib/wildling/help.txt" ]; then
+    echo "help.txt missing. Run ruby/build.sh first." >&2
+    exit 1
+fi
+
+exec docker run --rm \
+    -v "$ROOT:/app:ro" \
+    -v "$(pwd):/work" \
+    -w /work \
+    --network=host \
+    ruby:3.3-alpine \
+    ruby /app/bin/wildling.rb "$@"

data/bin/wildling.rb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+root = File.expand_path("..", __dir__)
+$LOAD_PATH.unshift(File.join(root, "lib"))
+
+require "wildling"
+
+Wildling::Cli.main

data/help.txt

@@ -0,0 +1,43 @@
+wildling - pattern based string generator
+
+USAGE
+    wildling [options] [pattern ...]
+
+OPTIONS
+    --select #                  Print only combination number # (repeatable)
+    --range #-#                 Print combinations from # to # inclusive (repeatable)
+    --check                     Print generation info instead of results
+    --dictionary <name>:<path>  Load a dictionary file as <name> (repeatable)
+    --template <path>           Load options from a JSON template file
+    --help, -h                  Show this help message
+    --version, -v               Show version
+
+PATTERNS
+    # #{N} #{N-M}               digits 0-9; optional fixed or ranged length
+    @ @{N} @{N-M}               lowercase a-z
+    * *{N} *{N-M}               lowercase a-z and digits 0-9
+    & &{N} &{N-M}               lowercase and uppercase letters
+    ! !{N} !{N-M}               uppercase A-Z
+    ? ?{N} ?{N-M}               uppercase A-Z and digits 0-9
+    - -{N} -{N-M}               letters and digits
+    ${'a,b',N-M}               combinations from a comma-separated word list
+    %{'name'} %{'name',N-M}     words from a named dictionary
+    \# \@ \$ ...                escape a wildcard character
+
+TEMPLATE JSON
+    {
+      "patterns": ["Year 19##", "%{'colors'}"],
+      "dictionaries": {
+        "colors": "path/to/colors.txt",
+        "inline": ["red", "blue"]
+      },
+      "select": [0, 2],
+      "range": ["5-7"],
+      "check": false
+    }
+
+EXAMPLES
+    wildling --dictionary colors:./colors.txt "%{'colors'}#"
+    wildling --template ./config.json
+    wildling --select 0 --range 8-9 "##"
+    wildling "${'blue,red',1-2}"

data/lib/wildling/cli.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "wildling"
+
+module Wildling
+  module Cli
+    module_function
+
+    CliArgs = Struct.new(
+      :selects, :ranges, :check, :dictionaries, :patterns, :help, :version,
+      keyword_init: true
+    )
+
+    def parse_range(value)
+      parts = value.split("-", 2)
+      return nil if parts.length != 2 || !parts[0].match?(/\A\d+\z/) || !parts[1].match?(/\A\d+\z/)
+
+      start = parts[0].to_i
+      finish = parts[1].to_i
+      start <= finish ? [start, finish] : nil
+    end
+
+    def load_dictionary_file(path)
+      File.read(path, encoding: "UTF-8").split(/\r?\n/).map(&:strip).reject(&:empty?)
+    end
+
+    def apply_dictionary(result, name, value)
+      if value.is_a?(Array)
+        result.dictionaries[name] = value.map(&:to_s)
+        return
+      end
+      return unless value.is_a?(String) && File.exist?(value)
+
+      begin
+        result.dictionaries[name] = load_dictionary_file(value)
+      rescue SystemCallError
+        # ignore unreadable dictionary files
+      end
+    end
+
+    def apply_template(result, path)
+      unless File.exist?(path)
+        warn "Template file not found: #{path}"
+        exit 1
+      end
+
+      begin
+        template = JSON.parse(File.read(path, encoding: "UTF-8"))
+      rescue SystemCallError, JSON::ParserError
+        warn "Invalid JSON template: #{path}"
+        exit 1
+      end
+
+      unless template.is_a?(Hash)
+        warn "Invalid JSON template: #{path}"
+        exit 1
+      end
+
+      result.check = true if template["check"] == true
+
+      select = template["select"]
+      if select.is_a?(Array)
+        select.each do |val|
+          number = Integer(val)
+          result.selects << number if number >= 0
+        rescue ArgumentError, TypeError
+          next
+        end
+      end
+
+      ranges = template["range"]
+      if ranges.is_a?(Array)
+        ranges.each do |range_str|
+          parsed = parse_range(range_str.to_s)
+          result.ranges << parsed if parsed
+        end
+      end
+
+      dictionaries = template["dictionaries"]
+      if dictionaries.is_a?(Hash)
+        dictionaries.each do |name, value|
+          apply_dictionary(result, name.to_s, value) if value.is_a?(String) || value.is_a?(Array)
+        end
+      end
+
+      patterns = template["patterns"]
+      if patterns.is_a?(Array)
+        patterns.each { |pattern| result.patterns << pattern.to_s }
+      end
+    end
+
+    def parse_args(args)
+      result = CliArgs.new(
+        selects: [],
+        ranges: [],
+        check: false,
+        dictionaries: {},
+        patterns: [],
+        help: false,
+        version: false
+      )
+      i = 0
+      while i < args.length
+        arg = args[i]
+
+        case arg
+        when "--help", "-h"
+          result.help = true
+          i += 1
+        when "--version", "-v"
+          result.version = true
+          i += 1
+        when "--check"
+          result.check = true
+          i += 1
+        when "--select"
+          i += 1
+          break if i >= args.length
+
+          begin
+            val = Integer(args[i])
+            result.selects << val if val >= 0
+          rescue ArgumentError, TypeError
+            # skip invalid select
+          end
+          i += 1
+        when "--range"
+          i += 1
+          break if i >= args.length
+
+          parsed = parse_range(args[i])
+          result.ranges << parsed if parsed
+          i += 1
+        when "--dictionary"
+          i += 1
+          break if i >= args.length
+
+          name, path = args[i].split(":", 2)
+          apply_dictionary(result, name, path) if name && path && !name.empty? && !path.empty?
+          i += 1
+        when "--template"
+          i += 1
+          if i >= args.length
+            warn "Missing path for --template"
+            exit 1
+          end
+          apply_template(result, args[i])
+          i += 1
+        else
+          result.patterns << arg
+          i += 1
+        end
+      end
+      result
+    end
+
+    def load_help_text
+      here = File.expand_path(__dir__)
+      candidates = [
+        File.join(here, "help.txt"),
+        File.join(here, "..", "..", "docs", "help.txt")
+      ]
+      candidates.each do |path|
+        return File.read(path, encoding: "UTF-8") if File.exist?(path)
+      end
+      "wildling - pattern based string generator\n\nHelp text unavailable.\n"
+    end
+
+    def format_list(values)
+      values.nil? || values.empty? ? "" : " #{values.map(&:to_s).join(' ')}"
+    end
+
+    def format_check_output(args, total, generators)
+      lines = [
+        "patterns:#{format_list(args.patterns)}",
+        "dictionaries:#{format_list(args.dictionaries.keys)}",
+        "select:#{format_list(args.selects)}",
+        "range:#{format_list(args.ranges.map { |start, finish| "#{start}-#{finish}" })}",
+        "total: #{total}"
+      ]
+      generators.each do |gen|
+        lines << "generator: #{gen.source} #{gen.count}"
+      end
+      lines.join("\n")
+    end
+
+    def main(argv = nil)
+      args = parse_args(argv || ARGV)
+
+      if args.help
+        puts load_help_text.rstrip
+        exit 0
+      end
+
+      if args.version
+        puts "wildling #{VERSION}"
+        exit 0
+      end
+
+      if args.patterns.empty?
+        warn "No pattern provided. Use --help for usage information."
+        exit 1
+      end
+
+      wildcard = ::Wildling.create(args.patterns, args.dictionaries)
+
+      if args.check
+        puts format_check_output(args, wildcard.count, wildcard.generators)
+        exit 0
+      end
+
+      if !args.selects.empty? || !args.ranges.empty?
+        oor = false
+        args.selects.each do |index|
+          value = wildcard.get(index)
+          if value == false
+            $stderr.puts "out of range: #{index}"
+            oor = true
+          else
+            puts value
+          end
+        end
+        args.ranges.each do |start, finish|
+          (start..finish).each do |index|
+            value = wildcard.get(index)
+            if value == false
+              $stderr.puts "out of range: #{index}"
+              oor = true
+            else
+              puts value
+            end
+          end
+        end
+        exit(oor ? 1 : 0)
+      end
+
+      value = wildcard.next
+      while value != false
+        puts value
+        value = wildcard.next
+      end
+    end
+  end
+end

data/lib/wildling/generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "parse_pattern"
+
+module Wildling
+  class Generator
+    attr_reader :source
+
+    def initialize(input_pattern, dictionaries)
+      @source = input_pattern
+      @tokens = ::Wildling.parse_pattern(input_pattern, dictionaries)
+      @count = 1
+      @tokens.each { |token| @count *= token.count }
+    end
+
+    def count
+      @count
+    end
+
+    def tokens
+      @tokens
+    end
+
+    def get(index)
+      return "" if index > @count - 1 || index < 0
+
+      string_array = []
+      index_with_offset = index
+      @tokens.each do |token|
+        string_array << token.get(index_with_offset % token.count)
+        index_with_offset /= token.count
+      end
+      string_array.join
+    end
+  end
+end

data/lib/wildling/parse_pattern.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "token"
+
+module Wildling
+  TOKEN_PARSING_REGEX = /(\\[%@$*#&?!-]|[%@$*#&?!-]\{.*?\}|[%@$*#&?!-])/
+
+  module_function
+
+  def parse_length_with_variants(part, variants)
+    match = part.match(/\{((\d+)-(\d+)|(\d+))\}/)
+
+    start_length = 1
+    end_length = 1
+
+    if match
+      if match[2]
+        start_length = match[2].to_i
+        end_length = match[3].to_i
+      elsif match[1]
+        start_length = match[1].to_i
+        end_length = start_length
+      end
+    end
+
+    {
+      "variants" => variants,
+      "startLength" => start_length,
+      "endLength" => end_length,
+      "src" => part
+    }
+  end
+
+  def parse_length_with_string(part)
+    match = part.match(/\{'(.*)'(?:,(\d+)-(\d+))?(?:,(\d+))?\}/)
+    return false unless match
+
+    if match[2] && match[3]
+      return {
+        "string" => match[1] || "",
+        "startLength" => match[2].to_i,
+        "endLength" => match[3].to_i,
+        "src" => part
+      }
+    end
+
+    if match[4]
+      length = match[4].to_i
+      return {
+        "string" => match[1] || "",
+        "startLength" => length,
+        "endLength" => length,
+        "src" => part
+      }
+    end
+
+    {
+      "string" => match[1] || "",
+      "startLength" => 1,
+      "endLength" => 1,
+      "src" => part
+    }
+  end
+
+  def simple_tokenizer(variants_string)
+    variants = variants_string.chars
+    lambda do |part|
+      Token.new(parse_length_with_variants(part, variants))
+    end
+  end
+
+  def dictionary_tokenizer(part, dictionaries)
+    options = parse_length_with_string(part)
+    if options == false || (options["string"] && !options["string"].empty? && !dictionaries.key?(options["string"]))
+      options = {
+        "variants" => [part],
+        "startLength" => 1,
+        "endLength" => 1,
+        "src" => part
+      }
+    else
+      options["variants"] = dictionaries[options["string"] || ""] || []
+    end
+    Token.new(options)
+  end
+
+  def words_tokenizer(part)
+    options = parse_length_with_string(part)
+
+    if options == false
+      options = {
+        "variants" => [part],
+        "startLength" => 1,
+        "endLength" => 1,
+        "src" => part
+      }
+    else
+      variants = []
+      work_string = options["string"] || ""
+      index = 0
+      while index < work_string.length
+        if work_string[index, 2] == "\\,"
+          index += 2
+        elsif work_string[index] == ","
+          variants << work_string[0...index]
+          work_string = work_string[(index + 1)..] || ""
+          index = 0
+        else
+          index += 1
+        end
+      end
+      variants << work_string
+      options["variants"] = variants.map { |variant| variant.gsub("\\,", ",") }
+    end
+
+    Token.new(options)
+  end
+
+  def part_to_token(part, dictionaries)
+    tokenizers = {
+      "#" => simple_tokenizer("0123456789"),
+      "@" => simple_tokenizer("abcdefghijklmnopqrstuvwxyz"),
+      "*" => simple_tokenizer("abcdefghijklmnopqrstuvwxyz0123456789"),
+      "-" => simple_tokenizer(
+        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+      ),
+      "!" => simple_tokenizer("ABCDEFGHIJKLMNOPQRSTUVWXYZ"),
+      "?" => simple_tokenizer("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"),
+      "&" => simple_tokenizer("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"),
+      "%" => ->(p) { dictionary_tokenizer(p, dictionaries) },
+      "$" => method(:words_tokenizer)
+    }
+
+    tokenizer = part.empty? ? nil : tokenizers[part[0]]
+    is_escaped = part.length > 1 && part[0] == "\\" && tokenizers.key?(part[1])
+
+    if tokenizer
+      tokenizer.call(part)
+    elsif is_escaped
+      Token.new(
+        "variants" => [part.sub(/^\\/, "")],
+        "src" => part
+      )
+    else
+      Token.new(
+        "variants" => [part],
+        "src" => part
+      )
+    end
+  end
+
+  def parse_pattern(input_pattern, dictionaries)
+    dictionaries ||= {}
+    parts = input_pattern.split(TOKEN_PARSING_REGEX).reject(&:empty?)
+    parts.map { |part| part_to_token(part, dictionaries) }
+  end
+end

data/lib/wildling/token.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Wildling
+  class Token
+    def initialize(options)
+      options = symbolize_keys(options)
+      @src = options.fetch(:src, "")
+      @start_length = default_integer(options[:startLength], 1)
+      @end_length = default_integer(options[:endLength], 1)
+      @variants = options[:variants] || []
+      @count = 0
+      (@start_length..@end_length).each do |length|
+        @count += @variants.length**length
+      end
+    end
+
+    def count
+      @count
+    end
+
+    def src
+      @src
+    end
+
+    def get(index)
+      return "" if index > @count - 1 || index < 0
+      return "" if index.zero? && @start_length.zero?
+
+      index_with_offset = index
+      string_length = @start_length
+      (@start_length..@end_length).each do |length|
+        string_length = length
+        offset_count = @variants.length**length
+        break if index_with_offset < offset_count
+
+        index_with_offset -= offset_count
+      end
+
+      string_array = []
+      string_length.times do
+        variant_index = index_with_offset % @variants.length
+        index_with_offset /= @variants.length
+        string_array << @variants[variant_index]
+      end
+      string_array.join
+    end
+
+    private
+
+    def default_integer(option, fallback)
+      option.is_a?(Integer) && option >= 0 ? option : fallback
+    end
+
+    def symbolize_keys(hash)
+      hash.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+    end
+  end
+end

data/lib/wildling/wildling.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "generator"
+
+module Wildling
+  VERSION = "2.0.2"
+
+  # Main enumerator. Prefer Wildling.create(...) from callers.
+  class Client
+    def initialize(patterns, dictionaries = nil)
+      @dictionaries = dictionaries || {}
+      @generators = patterns.map { |pattern| Generator.new(pattern, @dictionaries) }
+      @pattern_count = @generators.sum(&:count)
+      @internal_index = 0
+    end
+
+    def index
+      @internal_index
+    end
+
+    def count
+      @pattern_count
+    end
+
+    def reset
+      @internal_index = 0
+    end
+
+    def next
+      return false if @internal_index == @pattern_count
+
+      @internal_index += 1
+      get(@internal_index - 1)
+    end
+
+    def generators
+      @generators
+    end
+
+    def get(index)
+      return false if index > @pattern_count - 1 || index < 0
+
+      segment_index = 0
+      @generators.each do |generator|
+        pattern_index = index - segment_index
+        return generator.get(pattern_index) if pattern_index < generator.count
+
+        segment_index += generator.count
+      end
+      false
+    end
+  end
+
+  def self.create(patterns, dictionaries = nil)
+    Client.new(patterns, dictionaries)
+  end
+end

data/lib/wildling.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "wildling/token"
+require_relative "wildling/parse_pattern"
+require_relative "wildling/generator"
+require_relative "wildling/wildling"
+require_relative "wildling/cli"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: wildling
+version: !ruby/object:Gem::Version
+  version: 2.0.2
+platform: ruby
+authors:
+- dotmonk
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies: []
+description: Enumerate pattern combinations for wordlists, domains, and test data.
+email:
+- dotmonk@users.noreply.github.com
+executables:
+- wildling
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/wildling
+- bin/wildling.rb
+- help.txt
+- lib/wildling.rb
+- lib/wildling/cli.rb
+- lib/wildling/generator.rb
+- lib/wildling/parse_pattern.rb
+- lib/wildling/token.rb
+- lib/wildling/wildling.rb
+homepage: https://github.com/dotmonk/wildling
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dotmonk/wildling
+  source_code_uri: https://github.com/dotmonk/wildling/tree/main/ruby
+  changelog_uri: https://github.com/dotmonk/wildling/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+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: Pattern based string generator library and CLI
+test_files: []