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) (defaults to: {}) —

    options for fine-tuning the pattern behavior

Raises:

  • (Mustermann::Error) —

    if the pattern can’t be generated from the string

See Also:



61
62
63
64
65
 
# File 'lib/mustermann/pattern.rb', line 61

def initialize(string, options = {})
  uri_decode = options.fetch(:uri_decode, true)
  @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) (defaults to: {}) —

    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
50
51
 
# File 'lib/mustermann/pattern.rb', line 41

def self.new(string, options = {})
  ignore_unknown_options = options.fetch(:ignore_unknown_options, false)
  options.delete(:ignore_unknown_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 ||= 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:



92
93
94
 
# File 'lib/mustermann/pattern.rb', line 92

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:



84
85
86
 
# File 'lib/mustermann/pattern.rb', line 84

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>}) (defaults to: {}) —

    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:



143
144
145
 
# File 'lib/mustermann/pattern.rb', line 143

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:



77
78
79
 
# File 'lib/mustermann/pattern.rb', line 77

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

#named_captures ⇒ Array<String>

Returns capture names.

Returns:

  • (Array<String>) —

    capture names.

See Also:



98
99
100
 
# File 'lib/mustermann/pattern.rb', line 98

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:



104
105
106
 
# File 'lib/mustermann/pattern.rb', line 104

def names
  []
end

#params(string = nil, options = {}) ⇒ 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.



110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/mustermann/pattern.rb', line 110

def params(string = nil, options = {})
  options, string = string, nil if string.is_a?(Hash)
  captures = options[:captures]
  offset   = options[: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



68
69
70
 
# File 'lib/mustermann/pattern.rb', line 68

def to_s
  @string.dup
end