curly_bracket_parser 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2581aa770602a42a73eb9f79f3840dd53609d2905a75db5aaf3a5b0dac1f018
-  data.tar.gz: 912c7fb9c2285515bf5b7af00da8c629222af329e68dd431f5cd649c20815df4
+  metadata.gz: 418d901b8d9fc3ce2ed71432dfd387a94c2748b4800d77db21df617da6211255
+  data.tar.gz: 5d996dce7be3078c843b607e5e3aab44ad34ffc382efee8520f0789a9efee8da
 SHA512:
-  metadata.gz: 05eba36a79347485fd42db86ecfe49824913b497a89b6f36aa3b2924c4b2b8b6b1fae89b4bb3099708f5b76488706d1d6da4ff035f0c41bbf52cb0633f96a624
-  data.tar.gz: 56a9306ca6375a6e7c4366781b638eb509918c2a101703de930d0f481a8661ef00e1054925c74ff845c3de0cd2ea51f6b7304f34a259aad27379a8a15fa51c3b
+  metadata.gz: b2201ae74405f971a57996c95a3cb45f17e291b670063ba6ada1daf219c6db19a3e8734a6b5577afc959b8a8299efcb6f188dee3ab3ffce702aee7ab7d09dcd0
+  data.tar.gz: 19a1a19ad91be2886e256e43c6b7d5a1a49f44cad29195adec1d672650465349c505ada161da6b795e85cbf47b85e8bb028ed465594e58d8fea8925fcd210edd

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Matthäus J. N. Beyrle
+Copyright (c) 2020-2021 Matthäus J. N. Beyrle
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,14 +1,10 @@
 # curly_bracket_parser
 
-Simple parser to replace curly brackets `{{like_this}}` inside strings like URLs, texts or even files easily.
+Ruby gem providing a simple parser to replace curly brackets `{{like_this}}` inside strings like URLs, texts or even files easily.
 
 Additional support for build-in filters and custom filters make them more powerful. `{{example|my_filter}}`
 
-Using [LuckyCase](https://github.com/magynhard/lucky_case), all its case formats are supported as filter.
-
-```diff
-- beta version
-```
+Using [LuckyCase](https://github.com/magynhard/lucky_case), all its case formats are supported as filter by default.
 
 
 
@@ -17,7 +13,7 @@ Using [LuckyCase](https://github.com/magynhard/lucky_case), all its case formats
 # Contents
 
 * [Installation](#installation)
-* [Usage](#usage)
+* [Usage examples](#usage)
 * [Documentation](#documentation)
 * [Contributing](#contributing)
 
@@ -95,7 +91,7 @@ Use `#parse_file!` instead to write the parsed string directly into the file!
 
 You can define default variables, which will be replaced automatically without passing them by parameters, but can be overwritten with parameters.
 
-Because of providing blocks, your variables can dynamically depend on other states.
+Because of providing blocks, your variables can dynamically depend on other states (e.g. current date).
 
 ```ruby
     CurlyBracketParser.register_default_var('version') do

data/lib/curly_bracket_parser.rb

@@ -1,7 +1,11 @@
 require 'lucky_case'
 
 require 'curly_bracket_parser/version'
+require_relative 'custom_errors/filter_already_registered_error'
+require_relative 'custom_errors/invalid_filter_error'
+require_relative 'custom_errors/invalid_variable_error'
 require_relative 'custom_errors/unresolved_variables_error'
+require_relative 'custom_errors/variable_already_registered_error'
 
 #
 # CurlyBracketParser
@@ -17,8 +21,8 @@ module CurlyBracketParser
   VARIABLE_DECODER_REGEX = /{{([^{}\|]+)\|?([^{}\|]*)}}/
   VARIABLE_REGEX = /{{[^{}]+}}/
 
-  VALID_FILTERS = [
-      LuckyCase::CASES.keys.map(&:to_s)
+  VALID_DEFAULT_FILTERS = [
+    LuckyCase::CASES.keys.map(&:to_s)
   ].flatten
 
   #----------------------------------------------------------------------------------------------------
@@ -28,16 +32,26 @@ module CurlyBracketParser
   # @param [String] string to parse
   # @param [Hash<Symbol => String>] variables <key: 'value'>
   # @param [Symbol] unresolved_vars :raise, :keep, :replace => define how to act when unresolved variables within the string are found.
-  # @param [String] replace_pattern pattern used when param unresolved_vars is set to :replace. You can include the var name \\1 and filter \\1. Empty string to remove unresolved variables.
+  # @param [String] replace_pattern pattern used when param unresolved_vars is set to :replace. You can include the var name \\1 and filter \\2. Empty string to remove unresolved variables.
   # @return [String, UnresolvedVariablesError] parsed string
   def self.parse(string, variables, unresolved_vars: :raise, replace_pattern: "##\\1##")
+    variables ||= {}
     result_string = string.clone
     if CurlyBracketParser.any_variable_included? string
       loop do
         variables(string).each do |string_var|
-          name, filter = decode_variable(string_var)
+          dec = decode_variable(string_var)
+          name = dec[:name]
+          filter = dec[:filter]
           if variables[name.to_sym]
-            value = process_filter(variables[name.to_sym], filter)
+            value = if filter
+                      process_filter(filter, variables[name.to_sym])
+                    else
+                      variables[name.to_sym]
+                    end
+            result_string.gsub!(string_var, value)
+          elsif registered_default_var?(name.to_s)
+            value = process_default_var(name)
             result_string.gsub!(string_var, value)
           end
         end
@@ -89,38 +103,147 @@ module CurlyBracketParser
 
   # Register your custom filter to the filter list
   #
-  # @param [String] name of the filter, also used then in your strings, e.g. {{var_name|my_filter_name}}
+  # @param [String] filter name of the filter, also used then in your strings, e.g. {{var_name|my_filter_name}}
   # @param [Lambda] function of the filter to run the variable against
-  # @return [Boolean] true if filter was added, false if it already exists
-  def self.register_filter(name, &block)
-    raise "NOT IMPLEMENTED YET!"
+  # @raise [FilterAlreadyRegisteredError] if filter does already exist
+  # @return [Proc] given block
+  def self.register_filter(filter, &block)
+    @@registered_filters ||= {}
+    filter = filter.to_s
+    if valid_filter?(filter)
+      raise FilterAlreadyRegisteredError, "The given filter name '#{filter}' is already registered"
+    else
+      @@registered_filters[filter] = block
+    end
   end
 
   #----------------------------------------------------------------------------------------------------
 
-  def self.register_default_variable(name, &block)
-    raise "NOT IMPLEMENTED YET!"
+  # Process the given value with the given filter
+  #
+  # @param [String] filter name of the filter, also used then in your strings, e.g. {{var_name|my_filter_name}}
+  # @param [String] value string to apply the specified filter on
+  # @return [String] converted string with applied filter
+  def self.process_filter(filter, value)
+    @@registered_filters ||= {}
+    filter = filter.to_s
+    if @@registered_filters[filter]
+      @@registered_filters[filter].call(value)
+    elsif VALID_DEFAULT_FILTERS.include?(filter) && LuckyCase.valid_case_type?(filter)
+      LuckyCase.convert_case(value, filter)
+    else
+      message = "Invalid filter '#{filter}'. Valid filters are: #{self.valid_filters.join(' ')}"
+      raise InvalidFilterError, message
+    end
   end
 
   #----------------------------------------------------------------------------------------------------
 
-  def self.process_filter(value, filter)
-    return value unless filter
-    if VALID_FILTERS.include? filter
-      if LuckyCase.valid_case_type? filter
-        return LuckyCase.convert_case(value, filter)
-      else
-        raise "FILTER '#{filter}' NOT IMPLEMENTED YET!"
-      end
+  # Retrieve Array with valid filters
+  #
+  # @return [Array<String>] of valid filters
+  def self.valid_filters
+    all_filters = VALID_DEFAULT_FILTERS
+    @@registered_filters ||= {}
+    all_filters + @@registered_filters.keys.map(&:to_s)
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Check if a given filter is valid
+  #
+  # @param [String] name
+  # @return [Boolean] true if filter exists, otherwise false
+  def self.valid_filter?(name)
+    self.valid_filters.include? name
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Register a default variable to be replaced automatically by the given block value in future
+  # If the variable exists already, it will raise an VariableAlreadyRegisteredError
+  #
+  # @param [String] name of the default var
+  # @param [Proc] block
+  # @raise [VariableAlreadyRegisteredError] if variable is already registered
+  # @return [Proc] given block
+  def self.register_default_var(name, &block)
+    @@registered_default_vars ||= {}
+    name = name.to_s
+    if registered_default_var?(name)
+      raise VariableAlreadyRegisteredError, "The given variable name '#{name}' is already registered. If you want to override that variable explicitly, call #register_default_var! instead!"
+    else
+      @@registered_default_vars[name] = block
+    end
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Return the given default variable by returning the result of its block/proc
+  #
+  # @param [String] name of the variable to return
+  # @return [String] value of the variable
+  def self.process_default_var(name)
+    @@registered_default_vars ||= {}
+    name = name.to_s
+    if @@registered_default_vars[name]
+      @@registered_default_vars[name].call()
     else
-      raise "Invalid filter '#{filter}'"
+      message = "Invalid default variable '#{name}'. Valid registered default variables are: #{self.registered_default_vars.keys.join(' ')}"
+      raise InvalidVariableError, message
     end
   end
 
   #----------------------------------------------------------------------------------------------------
 
-  def self.has_filter?(variable)
-    decode_variable(variable)[:filter] != nil
+  # Register a default variable to be replaced automatically by the given block value in future
+  # If the variable exists already, it will be overwritten
+  #
+  # @param [String] name of the default var
+  # @param [Proc] block
+  # @raise [VariableAlreadyRegisteredError] if variable is already registered
+  # @return [Proc] given block
+  def self.register_default_var!(name, &block)
+    @@registered_default_vars ||= {}
+    name = name.to_s
+    @@registered_default_vars[name] = block
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Unregister / remove an existing default variable
+  #
+  # @param [String] name of the variable
+  # @return [Boolean] true if variable existed and was unregistered, false if it didn't exist
+  def self.unregister_default_var(name)
+    @@registered_default_vars ||= {}
+    name = name.to_s
+    if @@registered_default_vars[name]
+      @@registered_default_vars.delete(name)
+      true
+    else
+      false
+    end
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Return an array of registered default variables
+  #
+  # @return [Array<String>]
+  def self.registered_default_vars
+    @@registered_default_vars ||= {}
+    @@registered_default_vars.keys.map(&:to_s)
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Check if the given variable is a registered default variable
+  #
+  # @param [String] name of the variable
+  # @return [Boolean] true if variable is registered, otherwise false
+  def self.registered_default_var?(name)
+    self.registered_default_vars.include? name
   end
 
   #----------------------------------------------------------------------------------------------------
@@ -131,26 +254,30 @@ module CurlyBracketParser
   #   '{{var_name|filter_name}}' => { name: 'var_name', filter: 'filter_name' }
   #
   # @param [String] variable
-  # @return [Array(String, String)] name, filter
+  # @return [Hash<String => String>] name, filter
   def self.decode_variable(variable)
-    var = decoded_variables(variable).first
-    [var.keys.first, var.values.first]
+    decoded_variables(variable).first
   end
 
   #----------------------------------------------------------------------------------------------------
 
-  # scans the given url for variables with pattern '{{var}}'
+  # Scans the given url for variables with pattern '{{var|optional_filter}}'
+  #
+  # @example
+  #   'The variable {{my_var|my_filter}} is inside this string' => [{ name: "my_var", filter: "my_filter"}]
+  #
   # @param [String] string to scan
   # @return [Array<Hash<Symbol => String>>] array of variable names and its filters
   def self.decoded_variables(string)
-    var_name = 0
-    var_filter = 1
-    string.scan(VARIABLE_DECODER_REGEX).map { |e| {"#{e[var_name].strip}": e[var_filter].strip != '' ? e[var_filter].strip : nil } }.flatten
+    var_name_index = 0
+    var_filter_index = 1
+    string.scan(VARIABLE_DECODER_REGEX).map { |e| { name: "#{e[var_name_index].strip}", filter: e[var_filter_index].strip != '' ? e[var_filter_index].strip : nil } }.flatten
   end
 
   #----------------------------------------------------------------------------------------------------
 
-  # scans the given url for variables with pattern '{{var}}'
+  # Scans the given url for variables with pattern '{{var|optional_filter}}'
+  #
   # @param [String] string to scan
   # @return [Array<String>] array of variable names and its filters
   def self.variables(string)
@@ -160,7 +287,8 @@ module CurlyBracketParser
   #----------------------------------------------------------------------------------------------------
 
   # Check if any variable is included in the given string
-  # @param [Object] string
+  #
+  # @param [String] string name of variable to check for
   # @return [Boolean] true if any variable is included in the given string, otherwise false
   def self.any_variable_included?(string)
     string.match(VARIABLE_REGEX) != nil
@@ -169,8 +297,9 @@ module CurlyBracketParser
   #----------------------------------------------------------------------------------------------------
 
   # Check if one of the given variable names is included in the given string
+  #
   # @param [Array<String>] variable_names
-  # @param [String] string
+  # @param [String] string name of variable to check for
   # @return [Boolean] true if one given variable name is included in given the string, otherwise false
   def self.includes_one_variable_of(variable_names, string)
     decoded_variables(string).each do |dvar|

data/lib/curly_bracket_parser/version.rb

@@ -1,3 +1,3 @@
 module CurlyBracketParser
-  VERSION = '0.1.0'.freeze
+  VERSION = '1.0.0'.freeze
 end

data/lib/custom_errors/filter_already_registered_error.rb

@@ -0,0 +1,2 @@
+class FilterAlreadyRegisteredError < StandardError
+end

data/lib/custom_errors/invalid_filter_error.rb

@@ -0,0 +1,2 @@
+class InvalidFilterError < StandardError
+end

data/lib/custom_errors/invalid_variable_error.rb

@@ -0,0 +1,2 @@
+class InvalidVariableError < StandardError
+end

data/lib/custom_errors/variable_already_registered_error.rb

@@ -0,0 +1,2 @@
+class VariableAlreadyRegisteredError < StandardError
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: curly_bracket_parser
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Matthäus Beyrle
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-22 00:00:00.000000000 Z
+date: 2021-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lucky_case
@@ -85,7 +85,11 @@ files:
 - curly_bracket_parser.gemspec
 - lib/curly_bracket_parser.rb
 - lib/curly_bracket_parser/version.rb
+- lib/custom_errors/filter_already_registered_error.rb
+- lib/custom_errors/invalid_filter_error.rb
+- lib/custom_errors/invalid_variable_error.rb
 - lib/custom_errors/unresolved_variables_error.rb
+- lib/custom_errors/variable_already_registered_error.rb
 homepage: https://github.com/magynhard/curly_bracket_parser
 licenses:
 - MIT