Regular Expressions

# frozen_string_literal: true

line = "2026-10-18 lend 978-0-13-468599-1 by ana"
re = /(\d{4})-(\d\d)-(\d\d)/

# match returns MatchData or nil; =~ returns an index or nil; match? returns a boolean.
re.match(line) # => #<MatchData "2026-10-18" 1:"2026" 2:"10" 3:"18">
re =~ line # => 0
line =~ /by/ # => 34
line.match?(/lend/) # => true
re.match("no date here") # => nil
[/lend/ === line] # => [true]
/lend/.match(line, 12) # => nil
line.match(/\d+/, 5)[0] # => "10"

# match and =~ set the last-match state; match? does not.
line.match(/(?<verb>lend|return)/)
Regexp.last_match(:verb) # => "lend"
Regexp.last_match.pre_match.length # => 11
Regexp.last_match.post_match.length # => 25
"abc".match?(/b/)
Regexp.last_match(0) # => "lend"
"abc".match(/z/)
Regexp.last_match # => nil

# frozen_string_literal: true

# String#match and match? convert a String argument to a Regexp; sub, gsub, split, scan, index do not.
"a.c".match?("a.c") # => true
"abc".match?("a.c") # => true
"abc".sub("a.c", "X") # => "abc"
"a.c".sub("a.c", "X") # => "X"
"abc".scan("b") # => ["b"]

# =~ needs a Regexp on one side; two Strings raise TypeError, and nil =~ is nil.
begin
  "abc" =~ "b"
rescue TypeError => e
  e.message # => "type mismatch: String given"
end
(nil =~ /a/) # => nil

# match yields the MatchData to a block when it matched.
"order 66".match(/\d+/) { |m| m[0].to_i * 2 } # => 132
"no digits".match(/\d+/) { |m| m[0] } # => nil

# A Regexp embedded in another keeps its own flags through to_s.
word = /ruby/i
combined = /\A#{word} on rails\z/
combined.inspect # => "/\\A(?i-mx:ruby) on rails\\z/"
combined.match?("RUBY on rails") # => true
combined.match?("RUBY ON RAILS") # => false

# Comparison: equal when source and options are equal; sources that merely behave alike differ.
plain = Regexp.new("a")
same = [plain == /a/, plain.eql?(/a/), plain.hash == /a/.hash]
same.all? # => true
[plain == /a/i, Regexp.new("[ab]") == /a|b/] # => [false, false]

# Regexp#=== makes a regexp usable in case/when and returns false for non-strings.
def classify(value)
  case value
  when /\A\d+\z/ then :digits
  when /\A[[:alpha:]]+\z/ then :letters
  else :other
  end
end

[classify("42"), classify("abc"), classify(42), classify(:abc)] # => [:digits, :letters, :other, :letters]

# frozen_string_literal: true

# The last match ($~, $1, ...) is local to the method and thread that matched.
def parse_year(text)
  text =~ /(\d{4})/
  Regexp.last_match(1)
end

"id 7" =~ /(\d)/
parse_year("year 2026") # => "2026"
Regexp.last_match(1) # => "7"

# A block shares the match state of the method that wrote it.
"a1b2".gsub(/\d/) { Regexp.last_match(0).to_i.succ.to_s } # => "a2b3"
Regexp.last_match(0) # => "2"

# Another thread starts with its own, empty match state.
"zzz" =~ /z/
Thread.new { Regexp.last_match }.value # => nil
Regexp.last_match(0) # => "z"

# frozen_string_literal: true

require "English"

# The Perl-style globals. RuboCop prefers Regexp.last_match (Style/PerlBackrefs)
# and the English names (Style/SpecialGlobalVars), so this illustration opts out.
# rubocop:disable Style/PerlBackrefs, Style/SpecialGlobalVars
/s(\w{2}).*(c)/.match("haystack")
[$~, $&, $`, $', $+] # => [#<MatchData "stac" 1:"ta" 2:"c">, "stac", "hay", "k", "c"]
[$1, $2] # => ["ta", "c"]

# The English library gives them readable names.
[$LAST_MATCH_INFO.equal?($~), $MATCH, $PREMATCH, $POSTMATCH, $LAST_PAREN_MATCH] # => [true, "stac", "hay", "k", "c"]
# rubocop:enable Style/PerlBackrefs, Style/SpecialGlobalVars

# frozen_string_literal: true

# i: case-insensitive. Ruby's m is "dot matches newline", not "multi-line anchors".
/ruby/i.match?("RUBY") # => true
/a.c/.match?("a\nc") # => false
/a.c/m.match?("a\nc") # => true
/^b/m.match?("a\nb") # => true
/\Ab/m.match?("a\nb") # => false

# x: whitespace and # comments are ignored, so a pattern can be documented.
ISBN13 = /
  \A
  (?<prefix>97[89])  # GS1 prefix
  -?(?<group>\d{1,5})  # registration group
  -?(?<publisher>\d{1,7})
  -?(?<title>\d{1,6})
  -?(?<check>\d)     # check digit
  \z
/x
parts = ISBN13.match("978-0-13-468599-1").named_captures
parts.values_at("prefix", "publisher", "check") # => ["978", "13", "1"]
/a b/x.match?("ab") # => true
/a\ b/x.match?("a b") # => true
/a[ ]b/x.match?("a b") # => true

# Modes can be switched inside a pattern, for the rest of the group or for a sub-group.
/(?i)te(?-i)st/.match?("TEst") # => true
/(?i)te(?-i)st/.match?("TEST") # => false
/t(?i:e)st/.match?("tEst") # => true
/(?m:a.b)c.d/.match?("a\nbc\nd") # => false

# Flags as integers and as a string (Ruby 3.2); Regexp#options reports the integer.
Regexp.new("a", Regexp::IGNORECASE | Regexp::MULTILINE).options # => 5
Regexp.new("a", "ix").inspect # => "/a/ix"
[Regexp::IGNORECASE, Regexp::EXTENDED, Regexp::MULTILINE] # => [1, 2, 4]
Regexp.new("a", true).inspect # => "/a/i"

# The o flag interpolates once; the value at the first evaluation sticks.
def build(word) = /#{word}/o
[build("cat").source, build("dog").source] # => ["cat", "cat"]

# frozen_string_literal: true

log = "lend 978-0-13-468599-1 ana\nreturn 978-0-13-468599-1 ana\nlend 978-0-596-51774-8 bob"

# scan: all matches; with groups it returns arrays of captures.
log.scan(/^(\w+) (\S+) (\w+)$/).first # => ["lend", "978-0-13-468599-1", "ana"]
log.scan(/\b(?:lend|return)\b/) # => ["lend", "return", "lend"]
log.scan(/\d{3}-\d-\d{2}-\d{6}-\d/).uniq.size # => 1
lent = []
log.scan(/^lend (\S+)/) { |(isbn)| lent << isbn.delete("-") }
lent.join(",") # => "9780134685991,9780596517748"

# sub / gsub: strings, hashes and blocks as replacements.
"ana ruiz".sub(/\w+/, &:capitalize) # => "Ana ruiz"
"ana ruiz".gsub(/\b(\w)/) { Regexp.last_match(1).upcase } # => "Ana Ruiz"
"a-b_c".gsub(/[-_]/, "-" => "+", "_" => "=") # => "a+b=c"
"2026-10-18".gsub(/(\d+)-(\d+)-(\d+)/, '\3/\2/\1') # => "18/10/2026"
"2026-10-18".gsub(/(?<y>\d+)-(?<m>\d+)-(?<d>\d+)/, '\k<d>.\k<m>.\k<y>') # => "18.10.2026"
"a.b".gsub(".", "-") # => "a-b"
"a\\b".gsub("\\", "\\\\\\\\") # => "a\\\\b"
"a\\b".gsub("\\") { "\\\\" } # => "a\\\\b"

# split with a regexp; captures are kept; limit and the empty pattern.
"a, b;c  d".split(/[,;\s]+/) # => ["a", "b", "c", "d"]
"a1b22c".split(/(\d+)/) # => ["a", "1", "b", "22", "c"]
"a1b".split(/(?<=\d)|(?=\d)/) # => ["a", "1", "b"]
"a, b,,".split(/,\s*/) # => ["a", "b"]
"a, b,,".split(/,\s*/, -1) # => ["a", "b", "", ""]

# Other String methods that take a regexp.
"ISBN 9780134685991".slice(/\d{13}/) # => "9780134685991"
"ISBN 9780134685991"[/(?<n>\d{13})/, "n"] # => "9780134685991"
"ISBN 9780134685991"[/ISBN (\d)/, 1] # => "9"
"key = value".partition(/\s*=\s*/) # => ["key", " = ", "value"]
"archive.tar.gz".rpartition(/\.[a-z]+\z/) # => ["archive.tar", ".gz", ""]
"hello world".index(/o/) # => 4
"hello world".rindex(/o/) # => 7
"hello".start_with?(/h.l/) # => true
:symbol.match?(/sym/) # => true
:symbol[/b.l/] # => "bol"

# Enumerable#grep, case/when and slice_before use ===.
%w[ruby go rust].grep(/\Aru/) # => ["ruby", "rust"]
%w[ruby go rust].grep_v(/\Aru/) # => ["go"]
%w[ruby go rust].grep(/\Aru(.)/) { Regexp.last_match(1) } # => ["b", "s"]
%w[ruby go rust].any?(/^g/) # => true

# frozen_string_literal: true

md = /(?<year>\d{4})-(?<month>\d\d)-(?<day>\d\d)/.match("due 2026-10-18, extended")

md.to_a # => ["2026-10-18", "2026", "10", "18"]
md.captures # => ["2026", "10", "18"]
md.names # => ["year", "month", "day"]
md.named_captures # => {"year" => "2026", "month" => "10", "day" => "18"}
md.named_captures(symbolize_names: true) # => {year: "2026", month: "10", day: "18"}
md[0] # => "2026-10-18"
md[:month] # => "10"
md["day"] # => "18"
md[1..2] # => ["2026", "10"]
md.values_at(:year, :day) # => ["2026", "18"]
md.size # => 4
md.string # => "due 2026-10-18, extended"
md.regexp.source # => "(?<year>\\d{4})-(?<month>\\d\\d)-(?<day>\\d\\d)"
md.pre_match # => "due "
md.post_match # => ", extended"

# Positions: character offsets, byte offsets (3.2), and byte begin/end (3.4).
md.begin(0) # => 4
md.end(:year) # => 8
md.offset(:month) # => [9, 11]
md.byteoffset(:day) # => [12, 14]
md.bytebegin(0) # => 4
md.byteend(0) # => 14

# match and match_length (3.1) return the group text or its length.
md.match(:year) # => "2026"
md.match_length(:year) # => 4
md.match_length(:day) # => 2

# Offsets count characters, not bytes, in multibyte strings.
accent = /é/.match("café au lait")
[accent.begin(0), accent.byteoffset(0)] # => [3, [3, 5]]

# MatchData supports pattern matching (3.2): deconstruct gives the captures, deconstruct_keys the named ones.
def period(match)
  case match
  in { year:, month: } then "#{month}/#{year}"
  end
end

def parts(match)
  case match
  in [year, month, day] then [day, month, year]
  end
end

period(md) # => "10/2026"
parts(md) # => ["18", "10", "2026"]
md in { year: "2026" } # => true

# frozen_string_literal: true

ISBN_SHAPE = /\A\d{3}-\d-\d{2}-\d{6}-\d\z/
SAMPLE = "978-0-13-468599-1"
prefix = "978"
fixed = /\A#{prefix}/

# Objects allocated while the block runs.
def allocations
  before = GC.stat(:total_allocated_objects)
  yield
  GC.stat(:total_allocated_objects) - before
end

counts = {
  match?: allocations { 1000.times { ISBN_SHAPE.match?(SAMPLE) } },
  match: allocations { 1000.times { ISBN_SHAPE.match(SAMPLE) } },
  interpolated: allocations { 1000.times { /\A#{prefix}/ } },
  prebuilt: allocations { 1000.times { fixed.match?(SAMPLE) } }
}

# match? allocates nothing per call; match builds a MatchData each time;
# a literal with interpolation builds a new Regexp (and String) on every evaluation.
counts.transform_values { |n| n >= 1000 } # => {match?: false, match: true, interpolated: true, prebuilt: false}

# frozen_string_literal: true

# Ruby 3.2 memoizes backtracking, so most patterns match in time linear in the input.
Regexp.linear_time?(/\A(\w+)\z/) # => true
Regexp.linear_time?("(a+)+$") # => true
# Lookarounds and atomic groups joined the optimization in Ruby 3.3.
Regexp.linear_time?(/(?<=a)b/) # => true
Regexp.linear_time?(/(?>a+)b/) # => true

# Backreferences and subexpression calls still disable it.
Regexp.linear_time?(/\A(a+)+\1\z/) # => false
Regexp.linear_time?(/(?<n>a)\g<n>/) # => false

# A per-regexp timeout (seconds, Float) stops a catastrophic match.
guarded = Regexp.new("\\A(a+)+\\1\\z", timeout: 0.05)
guarded.timeout # => 0.05
begin
  guarded.match?("#{'a' * 30}b")
rescue Regexp::TimeoutError => e
  [e.class, e.class.superclass, e.message] # => [Regexp::TimeoutError, RegexpError, "regexp match timeout"]
end

# The class-wide default applies to every regexp whose own timeout is nil.
Regexp.timeout # => nil
Regexp.timeout = 1.0
Regexp.timeout # => 1.0
/x/.timeout # => nil
Regexp.timeout = nil

# frozen_string_literal: true

module Shelf
  # Parses lines of the loan log, for example:
  #   2026-10-18T09:30:00Z lend 978-0-13-468599-1 ana
  class LogLine
    PATTERN = /
      \A
      (?<at>\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s+   # ISO 8601 timestamp
      (?<action>lend|return)\s+
      (?<isbn>[\d-]{13,17})\s+                     # digits and hyphens
      (?<member>[[:alpha:]][[:alnum:]_.-]*)        # a member name
      \z
    /x

    Entry = Data.define(:at, :action, :isbn, :member)

    # A callable with === works in case/when and grep, like a regexp does.
    IsbnLike = ->(text) { text.to_s.delete("-").match?(/\A\d{13}\z/) }

    def self.parse(line)
      match = PATTERN.match(line.strip) or raise ArgumentError, "unparsable log line: #{line.inspect}"
      Entry.new(**match.named_captures(symbolize_names: true))
    end
  end
end

entry = Shelf::LogLine.parse("2026-10-18T09:30:00Z lend 978-0-13-468599-1 ana\n")
entry.action # => "lend"
entry.member # => "ana"
entry.to_h.values_at(:at, :isbn) # => ["2026-10-18T09:30:00Z", "978-0-13-468599-1"]

begin
  Shelf::LogLine.parse("garbage")
rescue ArgumentError => e
  e.message # => "unparsable log line: \"garbage\""
end

# Searching a catalogue safely: escape the user's words, then join them.
words = ["c++", "(2nd)"]
Regexp.union(words).source # => "c\\+\\+|\\(2nd\\)"
query = Regexp.union(words.map { |w| /#{Regexp.escape(w)}/i })
titles = ["Learning C++ (2nd ed.)", "Learning Ruby", "Effective C++"]
titles.grep(query) # => ["Learning C++ (2nd ed.)", "Effective C++"]

def kind(text)
  case text
  when Shelf::LogLine::IsbnLike then "looks like an ISBN"
  else "something else"
  end
end

kind("978-0-13-468599-1") # => "looks like an ISBN"
kind("Learning Ruby") # => "something else"