picoglob 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac02c0c9ac62540cbd3e42e65acc4214842d0cc595644e13679607004da0dfa9
+  data.tar.gz: 3c8c99572698165a76c90983e031b6105e44e7946dd15c71ed8c192c01961823
+SHA512:
+  metadata.gz: e287bbdf2f7748715de21feb07fcb3edeadf36656a1d47b59e9e0e62080864d65aac65135f71a1df360f042d7ae93f993defe3197a5ab7e163cd97dddd402180
+  data.tar.gz: 5311aec1c0031f231b28a359e47efca6c11e302451c389d4a352bf07f77a657f70a5dc2e1a89a2fa3906cde8a99fdd20bdace3169fa90cb95f963d723d444f86

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-28
+
+### Added
+- Initial release.
+- `Picoglob.new(pattern, **opts)` -> `Picoglob::Matcher` (compile once, match many).
+- `Picoglob.match?`, `Picoglob.to_regexp`, `Picoglob.filter` convenience methods.
+- `Matcher#match?`, `#===`, `#to_regexp`, `#filter`, `#pattern`, `#regexp`.
+- Glob syntax: `*`, `**`, `**/`, `?`, `[...]`, `[!...]`/`[^...]`, `{a,b}`,
+  `{1..n}` ranges, and extglobs `@()`, `?()`, `*()`, `+()`, `!()`, plus escaping.
+- Options: `separator`, `dot`, `extglob`, `nocase`.
+- `Picoglob::ParseError` for malformed patterns.
+
+[Unreleased]: https://github.com/tachyurgy/picoglob/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tachyurgy/picoglob/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Levelbrook Consulting
+
+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,112 @@
+# picoglob
+
+Compile **bash-style glob patterns into reusable Ruby `Regexp`s** so you can
+match *arbitrary strings* — S3 keys, routes, log lines, branch names, queue
+topics — not just files on disk.
+
+It's the missing Ruby counterpart to JavaScript's
+[picomatch](https://github.com/micromatch/picomatch) / minimatch. Ruby ships
+`File.fnmatch` and `Dir.glob`, but neither hands you a reusable `Regexp`, and
+`File.fnmatch`'s brace/extglob support is awkward to use off the filesystem.
+
+Pure Ruby, zero dependencies.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "picoglob"
+```
+
+```sh
+gem install picoglob
+```
+
+## Usage
+
+```ruby
+require "picoglob"
+
+# One-shot
+Picoglob.match?("src/**/*.{rb,erb}", "src/app/models/user.rb")  # => true
+Picoglob.match?("*.rb", "lib/foo.rb")                           # => false (single * doesn't cross "/")
+
+# Compile once, match many (recommended in hot paths)
+g = Picoglob.new("logs/*.log")
+g.match?("logs/app.log")    # => true
+g.match?("logs/2026/x.log") # => false
+
+# Get the underlying Regexp
+Picoglob.to_regexp("*.rb")   # => /\A(?:(?!\.)[^\/]*)\.rb\z/
+
+# Filter a list
+Picoglob.filter("**/*.rb", ["a.rb", "lib/b.rb", "c.txt"])  # => ["a.rb", "lib/b.rb"]
+
+# Use it in a case/when (Matcher implements ===)
+case key
+when Picoglob.new("uploads/**/*.jpg") then handle_image
+end
+```
+
+## Supported syntax
+
+| Pattern | Meaning |
+|---|---|
+| `*` | any run of non-separator characters |
+| `**` | globstar — any run of characters, *including* separators |
+| `**/` | zero or more whole path segments (so `src/**/*.rb` also matches `src/foo.rb`) |
+| `?` | exactly one non-separator character |
+| `[abc]` `[a-z]` | character class |
+| `[!abc]` `[^abc]` | negated character class |
+| `{a,b,c}` | alternation — one of the alternatives |
+| `{1..5}` | numeric range expansion |
+| `@(a\|b)` | exactly one of (extglob) |
+| `?(a\|b)` | zero or one of (extglob) |
+| `*(a\|b)` | zero or more of (extglob) |
+| `+(a\|b)` | one or more of (extglob) |
+| `!(a\|b)` | anything except (extglob) |
+| `\*` | a literal `*` (escape any metacharacter) |
+
+Braces and extglobs nest, and compile recursively, so things like
+`{a,b{c,d}}` and `image.@(jp?(e)g\|png)` work.
+
+## Options
+
+```ruby
+Picoglob.new(pattern,
+  separator: "/",   # the char that * / ? won't cross (use "." for dotted names, etc.)
+  dot:       false, # when false, wildcards won't match a leading "." (shell behavior)
+  extglob:   true,  # enable @()/?()/*()/+()/!() extglobs
+  nocase:    false) # case-insensitive matching
+```
+
+```ruby
+Picoglob.match?("*.RB", "foo.rb", nocase: true)        # => true
+Picoglob.match?("*", ".hidden")                        # => false (dotfile protected)
+Picoglob.match?("*", ".hidden", dot: true)             # => true
+Picoglob.match?("a.*.c", "a.b.c", separator: ".")      # => true
+```
+
+## Why not just use `File.fnmatch`?
+
+`File.fnmatch` is fine for matching against the filesystem, but:
+
+- it doesn't give you a reusable `Regexp` to combine, inspect, or reuse;
+- brace expansion requires `File::FNM_EXTGLOB` and still can't be turned into a
+  pattern you keep;
+- there's no extglob (`@()`, `+()`, `!()`, …) support;
+- the dotfile / separator rules aren't configurable per call.
+
+`picoglob` gives you a compiled `Regexp` you own, with picomatch-style semantics,
+that works on any string.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT © Levelbrook Consulting. See [LICENSE](LICENSE).

data/lib/picoglob/compiler.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+module Picoglob
+  # Raised when a glob pattern is malformed (e.g. an unbalanced brace or bracket).
+  class ParseError < StandardError; end
+
+  # Compiles a bash-style glob pattern into a Ruby Regexp source string.
+  #
+  # Supported syntax:
+  #   *            any run of non-separator characters
+  #   **           any run of characters, including separators (globstar)
+  #   ?            any single non-separator character
+  #   [abc] [a-z]  character class; [!...] or [^...] negates
+  #   {a,b,c}      brace alternation (one of the comma-separated alternatives)
+  #   {1..3}       numeric brace range expansion -> {1,2,3}
+  #   @(a|b)       exactly one of the patterns (extglob)
+  #   ?(a|b)       zero or one of the patterns (extglob)
+  #   *(a|b)       zero or more of the patterns (extglob)
+  #   +(a|b)       one or more of the patterns (extglob)
+  #   !(a|b)       anything except the patterns (extglob)
+  #   \x           escape the next character (literal)
+  #
+  # @api private
+  class Compiler
+    # @param separator [String] the path separator that `*`/`?` will not cross
+    # @param dot [Boolean] when false, a leading `.` must be matched explicitly
+    #   (a leading `*`/`?`/`[` will not match it), mirroring shell globbing
+    # @param extglob [Boolean] enable extglob constructs (@/?/*/+/! followed by `(`)
+    # @param nocase [Boolean] case-insensitive matching
+    def initialize(separator: "/", dot: false, extglob: true, nocase: false)
+      @sep = separator
+      @dot = dot
+      @extglob = extglob
+      @nocase = nocase
+    end
+
+    # @param pattern [String]
+    # @return [Regexp]
+    def compile(pattern)
+      @chars = pattern.chars
+      @pos = 0
+      body = parse_sequence(top_level: true)
+      raise ParseError, "unexpected #{current.inspect}" unless eof?
+
+      src = "\\A#{body}\\z"
+      Regexp.new(src, @nocase ? Regexp::IGNORECASE : nil)
+    end
+
+    private
+
+    def sep_re
+      Regexp.escape(@sep)
+    end
+
+    # A single "non-separator" character class fragment, e.g. "[^/]".
+    def not_sep
+      "[^#{sep_re}]"
+    end
+
+    def current
+      @chars[@pos]
+    end
+
+    def peek(n = 1)
+      @chars[@pos + n]
+    end
+
+    def advance
+      c = @chars[@pos]
+      @pos += 1
+      c
+    end
+
+    def eof?
+      @pos >= @chars.length
+    end
+
+    # Parse a run of glob tokens until a terminator. When +stop+ is given
+    # (a set of characters), parsing stops *before* consuming a terminator.
+    def parse_sequence(stop: nil, top_level: false)
+      out = +""
+      until eof?
+        c = current
+        break if stop&.include?(c)
+
+        out << parse_token(at_segment_start: out.empty? || just_after_sep?(out), top_level: top_level)
+      end
+      out
+    end
+
+    # Did the regex built so far end at a segment boundary? Used for the
+    # leading-dot rule.
+    def just_after_sep?(built)
+      built.end_with?(sep_re)
+    end
+
+    def parse_token(at_segment_start:, top_level:)
+      c = current
+
+      # extglob: a prefix char immediately followed by '('
+      if @extglob && "@?*+!".include?(c) && peek == "("
+        return parse_extglob
+      end
+
+      case c
+      when "\\"
+        advance
+        nxt = advance
+        raise ParseError, "dangling escape" if nxt.nil?
+
+        Regexp.escape(nxt)
+      when "*"
+        parse_star(at_segment_start: at_segment_start)
+      when "?"
+        advance
+        # respect leading-dot rule at a segment start
+        at_segment_start && !@dot ? "(?!\\.)#{not_sep}" : not_sep
+      when "["
+        parse_class
+      when "{"
+        parse_brace
+      when "}", ")", "|", ","
+        # Only meaningful inside the corresponding construct; at top level treat
+        # as a literal so patterns like "a,b" or "100%}" don't explode.
+        Regexp.escape(advance)
+      else
+        Regexp.escape(advance)
+      end
+    end
+
+    def parse_star(at_segment_start:)
+      advance # consume first '*'
+      if current == "*"
+        # globstar: consume all consecutive '*'
+        advance while current == "*"
+        parse_globstar(at_segment_start: at_segment_start)
+      elsif at_segment_start && !@dot
+        "(?:(?!\\.)#{not_sep}*)"
+      else
+        "#{not_sep}*"
+      end
+    end
+
+    # Globstar (`**`) matches across separators. The special, shell-standard
+    # form is `**/`, which matches zero or more *whole* path segments — so
+    # `src/**/*.rb` also matches `src/foo.rb`. To make "zero segments" work we
+    # swallow the trailing separator here and emit a group that can match
+    # nothing.
+    def parse_globstar(at_segment_start:)
+      if at_segment_start && current == @sep
+        advance # consume the '/' that follows '**'
+        seg = @dot ? "#{not_sep}+" : "(?!\\.)#{not_sep}*"
+        # zero or more "segment/" groups; matches the empty string too
+        "(?:#{seg}#{sep_re})*"
+      elsif at_segment_start && !@dot
+        "(?:(?!\\.).)*"
+      else
+        ".*"
+      end
+    end
+
+    def parse_class
+      advance # '['
+      negate = false
+      if current == "!" || current == "^"
+        negate = true
+        advance
+      end
+      body = +""
+      # A ']' immediately after the (optional) negation is a literal ']'.
+      if current == "]"
+        body << "\\]"
+        advance
+      end
+      until eof? || current == "]"
+        ch = advance
+        body << if ch == "\\"
+                  # explicit escape inside the class: take the next char literally
+                  nxt = advance
+                  raise ParseError, "dangling escape in character class" if nxt.nil?
+
+                  escape_in_class(nxt)
+                elsif ch == "-"
+                  # keep '-' so ranges like 0-9 / a-z are preserved
+                  "-"
+                else
+                  escape_in_class(ch)
+                end
+      end
+      raise ParseError, "unterminated character class" if eof?
+
+      advance # ']'
+      "[#{negate ? '^' : ''}#{body}]"
+    end
+
+    # Escape a single character so it is a literal inside a Ruby regex
+    # character class. Only ']', '\\' and '^' are special there (we treat '-'
+    # specially in the caller so ranges survive).
+    def escape_in_class(ch)
+      case ch
+      when "]", "\\", "^"
+        "\\#{ch}"
+      else
+        ch
+      end
+    end
+
+    # {a,b,c}  -> (?:a|b|c)
+    # {1..5}   -> (?:1|2|3|4|5)
+    def parse_brace
+      advance # '{'
+      # numeric range?
+      if (range = try_numeric_range)
+        return range
+      end
+
+      alts = []
+      depth = 0
+      current_alt = +""
+      loop do
+        raise ParseError, "unterminated brace" if eof?
+
+        c = current
+        if c == "}" && depth.zero?
+          advance
+          alts << current_alt
+          break
+        elsif c == "," && depth.zero?
+          advance
+          alts << current_alt
+          current_alt = +""
+        elsif c == "{"
+          depth += 1
+          current_alt << advance
+        elsif c == "}"
+          depth -= 1
+          current_alt << advance
+        else
+          current_alt << advance
+        end
+      end
+
+      # A brace with no comma (e.g. "{foo}") is treated literally by bash.
+      if alts.length == 1
+        return "\\{#{compile_fragment(alts.first)}\\}"
+      end
+
+      "(?:#{alts.map { |a| compile_fragment(a) }.join('|')})"
+    end
+
+    # Try to parse "{m..n}" starting just after '{'. Restores position on failure.
+    def try_numeric_range
+      start = @pos
+      num1 = +""
+      num1 << advance while current&.match?(/\d/)
+      if current == "." && peek == "." && !num1.empty?
+        advance
+        advance
+        num2 = +""
+        num2 << advance while current&.match?(/\d/)
+        if current == "}" && !num2.empty?
+          advance
+          lo = num1.to_i
+          hi = num2.to_i
+          range = lo <= hi ? (lo..hi) : (hi..lo).to_a.reverse
+          return "(?:#{range.to_a.join('|')})"
+        end
+      end
+      @pos = start
+      nil
+    end
+
+    # extglob: PREFIX( pat | pat | ... )
+    def parse_extglob
+      prefix = advance # @ ? * + !
+      advance # '('
+      alts = []
+      current_alt = +""
+      depth = 0
+      loop do
+        raise ParseError, "unterminated extglob" if eof?
+
+        c = current
+        if c == ")" && depth.zero?
+          advance
+          alts << current_alt
+          break
+        elsif c == "|" && depth.zero?
+          advance
+          alts << current_alt
+          current_alt = +""
+        elsif c == "("
+          depth += 1
+          current_alt << advance
+        elsif c == ")"
+          depth -= 1
+          current_alt << advance
+        else
+          current_alt << advance
+        end
+      end
+
+      inner = "(?:#{alts.map { |a| compile_fragment(a) }.join('|')})"
+      case prefix
+      when "@" then inner
+      when "?" then "#{inner}?"
+      when "*" then "#{inner}*"
+      when "+" then "#{inner}+"
+      when "!" then "(?:(?!#{inner}#{sep_re}*$)#{not_sep}*)"
+      end
+    end
+
+    # Compile a nested fragment (alternative body, extglob branch) using the
+    # same options. We don't apply the leading-dot rule inside fragments.
+    def compile_fragment(str)
+      sub = Compiler.new(separator: @sep, dot: true, extglob: @extglob, nocase: @nocase)
+      sub.compile_body(str)
+    end
+
+    protected
+
+    # Compile +str+ to a regex body string (no anchors). Used for nested
+    # fragments so we get full recursive glob support inside {} and extglobs.
+    def compile_body(str)
+      @chars = str.chars
+      @pos = 0
+      body = parse_sequence
+      raise ParseError, "unexpected #{current.inspect}" unless eof?
+
+      body
+    end
+  end
+end

data/lib/picoglob/version.rb

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

data/lib/picoglob.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "picoglob/version"
+require_relative "picoglob/compiler"
+
+# Picoglob compiles bash-style glob patterns into Ruby Regexps so you can match
+# *arbitrary strings* — S3 keys, routes, log lines, branch names — not just
+# files on disk.
+#
+# It's the missing Ruby counterpart to JS's picomatch / minimatch. Ruby ships
+# `File.fnmatch` and `Dir.glob`, but neither gives you a reusable `Regexp`, and
+# `File.fnmatch` has limited brace/extglob support that's awkward to use off the
+# filesystem.
+#
+# @example One-shot match
+#   Picoglob.match?("src/**/*.{rb,erb}", "src/app/models/user.rb") # => true
+#
+# @example Compile once, match many (fast)
+#   g = Picoglob.new("logs/*.log")
+#   g.match?("logs/app.log")   # => true
+#   g.match?("logs/2026/x.log") # => false (single * doesn't cross "/")
+#
+# @example Filter a list
+#   Picoglob.filter("**/*.rb", ["a.rb", "lib/b.rb", "c.txt"]) # => ["a.rb", "lib/b.rb"]
+#
+# @example Extglob
+#   Picoglob.match?("image.+(jpg|png)", "image.png") # => true
+module Picoglob
+  # Build a reusable matcher.
+  #
+  # @param pattern [String] the glob pattern
+  # @param separator [String] path separator that `*`/`?` won't cross (default "/")
+  # @param dot [Boolean] match leading dots with wildcards (default false, shell-like)
+  # @param extglob [Boolean] enable extglob syntax (default true)
+  # @param nocase [Boolean] case-insensitive (default false)
+  # @return [Picoglob::Matcher]
+  def self.new(pattern, **opts)
+    Matcher.new(pattern, **opts)
+  end
+
+  # Convenience: does +string+ match +pattern+?
+  # @return [Boolean]
+  def self.match?(pattern, string, **opts)
+    Matcher.new(pattern, **opts).match?(string)
+  end
+
+  # Convenience: compile +pattern+ to a Regexp.
+  # @return [Regexp]
+  def self.to_regexp(pattern, **opts)
+    Matcher.new(pattern, **opts).to_regexp
+  end
+
+  # Convenience: keep only the strings that match +pattern+.
+  # @return [Array<String>]
+  def self.filter(pattern, strings, **opts)
+    Matcher.new(pattern, **opts).filter(strings)
+  end
+
+  # A compiled glob. Compile once, match many times.
+  class Matcher
+    # @return [String] the original glob pattern
+    attr_reader :pattern
+    # @return [Regexp] the compiled regular expression
+    attr_reader :regexp
+
+    def initialize(pattern, separator: "/", dot: false, extglob: true, nocase: false)
+      @pattern = pattern
+      @regexp = Compiler.new(
+        separator: separator, dot: dot, extglob: extglob, nocase: nocase
+      ).compile(pattern)
+    end
+
+    # @param string [String]
+    # @return [Boolean]
+    def match?(string)
+      @regexp.match?(string)
+    end
+    alias === match?
+
+    # @return [Regexp]
+    def to_regexp
+      @regexp
+    end
+
+    # @param strings [Enumerable<String>]
+    # @return [Array<String>]
+    def filter(strings)
+      strings.select { |s| @regexp.match?(s) }
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: picoglob
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Levelbrook Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |-
+  Picoglob turns bash-style glob patterns (*, **, ?, [...], {a,b}, {1..3}, and extglobs
+  like @(a|b), +(a|b), !(a|b)) into reusable Ruby Regexps, so you can match arbitrary
+  strings -- S3 keys, routes, log lines, branch names -- not just files on disk. It is
+  the missing Ruby counterpart to JavaScript's picomatch / minimatch. Pure Ruby, no
+  dependencies.
+email:
+- levelbrookteam@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/picoglob.rb
+- lib/picoglob/compiler.rb
+- lib/picoglob/version.rb
+homepage: https://consulting.levelbrook.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://consulting.levelbrook.com
+  source_code_uri: https://github.com/tachyurgy/picoglob
+  changelog_uri: https://github.com/tachyurgy/picoglob/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: 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: Compile bash-style glob patterns into Ruby Regexps (picomatch for Ruby).
+test_files: []