Class: Mustermann::Pattern Abstract

Inherits:
Object
  • Object
show all
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

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:



55
56
57
58
 
# File 'lib/mustermann/pattern.rb', line 55

def initialize(string, uri_decode: true, **options)
  @uri_decode = uri_decode
  @string     = string.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:



38
39
40
41
42
43
44
45
 
# File 'lib/mustermann/pattern.rb', line 38

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

  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.



28
29
30
 
# File 'lib/mustermann/pattern.rb', line 28

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



19
20
21
22
23
24
 
# File 'lib/mustermann/pattern.rb', line 19

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:



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

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:



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

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.

  • (ArgumentError) —

    raised if a value is missing or unknown



132
133
134
 
# File 'lib/mustermann/pattern.rb', line 132

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:



70
71
72
 
# File 'lib/mustermann/pattern.rb', line 70

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

#named_captures ⇒ Array<String>

Returns capture names.

Returns:

  • (Array<String>) —

    capture names.

See Also:



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

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:



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

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.



103
104
105
106
107
108
109
110
111
112
 
# File 'lib/mustermann/pattern.rb', line 103

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



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

def to_s
  @string.dup
end