Class: Mustermann::Pattern Abstract

Inherits:
Object
  • Object
show all
Includes:
Mustermann
Defined in:
lib/mustermann/pattern.rb

Overview

This class is abstract.

Superclass for all pattern implementations.

Direct Known Subclasses

Identity, RegexpBased, Shell

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Mustermann

[]

Constructor Details

#initialize(string, **options) ⇒ Pattern

Returns a new instance of Pattern.

Parameters:

  • string (String) —

    the string representation of the pattern

  • options (Hash) —

    options for fine-tuning the pattern behavior

Raises:

  • (Mustermann::Error) —

    if the pattern can’t be generated from the string

See Also:



59
60
61
62
 
# File 'lib/mustermann/pattern.rb', line 59

def initialize(string, uri_decode: true, **options)
  @uri_decode = uri_decode
  @string     = string.to_s.dup
end

Class Method Details

.new(string, **options) ⇒ Mustermann::Pattern

Returns a new instance of Mustermann::Pattern.

Parameters:

  • string (String) —

    the string representation of the pattern

  • options (Hash) —

    options for fine-tuning the pattern behavior

Returns:

Raises:

  • (ArgumentError) —

    if some option is not supported

  • (Mustermann::Error) —

    if the pattern can’t be generated from the string

See Also:



41
42
43
44
45
46
47
48
49
 
# File 'lib/mustermann/pattern.rb', line 41

def self.new(string, ignore_unknown_options: false, **options)
  unless ignore_unknown_options
    unsupported = options.keys.detect { |key| not supported?(key) }
    raise ArgumentError, "unsupported option %p for %p" % [unsupported, self] if unsupported
  end

  @map ||= Tool::EqualityMap.new
  @map.fetch(string, options) { super(string, options) }
end

.supported?(option) ⇒ Boolean

Returns Whether or not option is supported.

Parameters:

  • option (Symbol) —

    The option to check.

Returns:

  • (Boolean) —

    Whether or not option is supported.



31
32
33
 
# File 'lib/mustermann/pattern.rb', line 31

def self.supported?(option)
  supported_options.include? option
end

.supported_options ⇒ Array<Symbol> .supported_options(*list) ⇒ Array<Symbol>

List of supported options.

Overloads:

  • .supported_options ⇒ Array<Symbol>

    Returns list of supported options.

    Returns:

    • (Array<Symbol>) —

      list of supported options

  • .supported_options(*list) ⇒ Array<Symbol>

    This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

    Adds options to the list.

    Parameters:

    • *list (Symbol) —

      adds options to the list of supported options

    Returns:

    • (Array<Symbol>) —

      list of supported options



22
23
24
25
26
27
 
# File 'lib/mustermann/pattern.rb', line 22

def self.supported_options(*list)
  @supported_options ||= []
  options = @supported_options.concat(list)
  options += superclass.supported_options if self < Pattern
  options
end

Instance Method Details

#===(string) ⇒ Boolean

Note:

Needs to be overridden by subclass.

Returns Whether or not the pattern matches the given string.

Parameters:

  • string (String) —

    The string to match against

Returns:

  • (Boolean) —

    Whether or not the pattern matches the given string

Raises:

  • (NotImplementedError)

See Also:



89
90
91
 
# File 'lib/mustermann/pattern.rb', line 89

def ===(string)
  raise NotImplementedError, 'subclass responsibility'
end

#=~(string) ⇒ Integer?

Returns nil if pattern does not match the string, zero if it does.

Parameters:

  • string (String) —

    The string to match against

Returns:

  • (Integer, nil) —

    nil if pattern does not match the string, zero if it does.

See Also:



81
82
83
 
# File 'lib/mustermann/pattern.rb', line 81

def =~(string)
  0 if self === string
end

#expand(**values) ⇒ String

Note:

This method is only implemented by certain subclasses.

Returns expanded string.

Examples:

Expanding a pattern

pattern = Mustermann.new('/:name(.:ext)?')
pattern.expand(name: 'hello')             # => "/hello"
pattern.expand(name: 'hello', ext: 'png') # => "/hello.png"

Checking if a pattern supports expanding

if pattern.respond_to? :expand
  pattern.expand(name: "foo")
else
  warn "does not support expanding"
end

Parameters:

  • values (Hash{Symbol: #to_s, Array<#to_s>}) —

    values to use for expansion

Returns:

  • (String) —

    expanded string

Raises:

  • (NotImplementedError) —

    raised if expand is not supported.

  • (Mustermann::ExpandError) —

    raised if a value is missing or unknown

See Also:



137
138
139
 
# File 'lib/mustermann/pattern.rb', line 137

def expand(**values)
  raise NotImplementedError, "expanding not supported by #{self.class}"
end

#match(string) ⇒ MatchData, ...

Returns MatchData or similar object if the pattern matches.

Parameters:

  • string (String) —

    The string to match against

Returns:

See Also:



74
75
76
 
# File 'lib/mustermann/pattern.rb', line 74

def match(string)
  SimpleMatch.new(string) if self === string
end

#named_captures ⇒ Array<String>

Returns capture names.

Returns:

  • (Array<String>) —

    capture names.

See Also:



95
96
97
 
# File 'lib/mustermann/pattern.rb', line 95

def named_captures
  {}
end

#names ⇒ Hash{String: Array<Integer>}

Returns capture names mapped to capture index.

Returns:

  • (Hash{String: Array<Integer>}) —

    capture names mapped to capture index.

See Also:



101
102
103
 
# File 'lib/mustermann/pattern.rb', line 101

def names
  []
end

#params(string = nil, captures: nil, offset: 0) ⇒ Hash{String: String, Array<String>}?

Returns Sinatra style params if pattern matches.

Parameters:

  • string (String) (defaults to: nil) —

    the string to match against

Returns:

  • (Hash{String: String, Array<String>}, nil) —

    Sinatra style params if pattern matches.



107
108
109
110
111
112
113
114
115
116
 
# File 'lib/mustermann/pattern.rb', line 107

def params(string = nil, captures: nil, offset: 0)
  return unless captures ||= match(string)
  params   = named_captures.map do |name, positions|
    values = positions.map { |pos| map_param(name, captures[pos + offset]) }.flatten
    values = values.first if values.size < 2 and not always_array? name
    [name, values]
  end

  Hash[params]
end

#to_s ⇒ String

Returns the string representation of the pattern.

Returns:

  • (String) —

    the string representation of the pattern



65
66
67
 
# File 'lib/mustermann/pattern.rb', line 65

def to_s
  @string.dup
end