curly_bracket_parser 0.0.1 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 437e9b2cda38fa373852f4b2f67a35428f99d5c78928820b539ae8c5ecf77d09
-  data.tar.gz: b11dd97f668eff6128b5ae0a9846189c7a8e6291953e7a475080fe705247e9f3
+  metadata.gz: c287b3fc82c91116b7c0ca2f982b81bac5c37e4ca286cd1ea8606de75e0c214f
+  data.tar.gz: 04f59765b1f59ea540d1e152bbc88c0294ca5adc681f30bf1efed3a117cb3afa
 SHA512:
-  metadata.gz: d8286bc6b15346a2babed4de6894be8fadad6c84c9d51ad759fdae906ecec41fdc50d28cf294fb3f8f1b67b6745bf6206e95d337f743ed82fc488cd77b4c6bea
-  data.tar.gz: 3aab318c0069bf40f73443eefb0245e53c35bbddfb6373883e921ae32e3ebd1b26050319ab24e6336baf98283023ee9232a36dd2655745ee3b018170836a490d
+  metadata.gz: 685345c3a8551e0749742550f2dae6784501fefa07318b8e76b2b30fd743c96d1571d2550bee0731a1c1609d82055ec39ff943a6aebf3c39db435d4686d8e01c
+  data.tar.gz: a19c4ffb4fe23ce4945023604aeb34ee28a88bd6f89cf2df08f5eab63151fbb0f1ec6b7ec337f6cc8c0b8d2b57c8dacbfec19cbec7b70b22d68cc8b4caf965c6

data/README.md

@@ -1,9 +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.
 
-alpha version ... to be done ...
+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 by default.
 
 
 
@@ -12,7 +13,7 @@ alpha version ... to be done ...
 # Contents
 
 * [Installation](#installation)
-* [Usage](#usage)
+* [Usage examples](#usage)
 * [Documentation](#documentation)
 * [Contributing](#contributing)
 
@@ -36,23 +37,13 @@ Or install it yourself as:
 
     $ gem install curly_bracket_parser
     
-## Common information
-
-TODO
-
-
-
-
-
 
 <a name="usage"></a>
-## Usage
+## Usage examples
 
-TODO
+You can either parse variables inside strings or even directly in files.
 
-### Examples
-
-#### Basic
+### Basic
 
 ```ruby
     url = "https://my-domain.com/items/{{item_id}}"
@@ -60,7 +51,7 @@ TODO
     # => "https://my-domain.com/items/123"
 ```
 
-#### Filters
+### Filters
 
 ```ruby
     url = "https://my-domain.com/catalog/{{item_name|snake_case}}"
@@ -68,9 +59,51 @@ TODO
     # => "https://my-domain.com/catalog/mega_super_item"
 ```
 
-#### Globals
+For a list of built-in filters visit [LuckyCase](https://github.com/magynhard/lucky_case).
+
+#### Define your custom filter
+
+```ruby
+    CurlyBracketParser.register_filter('7times') do |string|
+      string.to_s * 7
+    end
+
+    text = "Paul went out and screamed: A{{scream|7times}}h"
+    final_text = CurlyBracketParser.parse text, scream: 'a'
+    # => "Paul went out and screamed: Aaaaaaaah"
+```
+
+### Files
+
+<ins>test.html</ins>
+```html
+<h1>{{title|sentence_case}}</h1>
+```
+
+```ruby
+    parsed_file = CurlyBracketParser.parse_file './test.html', title: 'WelcomeAtHome'
+    # => "<h1>Welcome at home</h1>"
+```
+
+Use `#parse_file!` instead to write the parsed string directly into the file!
+
+### Default variables
+
+You can define default variables, which will be replaced automatically without passing them by parameters, but can be overwritten with parameters.
 
-TODO
+Because of providing blocks, your variables can dynamically depend on other states (e.g. current date).
+
+```ruby
+    CurlyBracketParser.register_default_var('version') do
+      '1.0.2'
+    end
+
+    text = "You are running version {{version}}"
+    CurlyBracketParser.parse text
+    # => "You are running version 1.0.2"
+    CurlyBracketParser.parse text, version: '0.7.0'
+    # => "You are running version 0.7.0"
+```
 
 
 

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,25 +21,37 @@ 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
 
   #----------------------------------------------------------------------------------------------------
 
+  # Parse given string and replace the included variables by the given variables
+  #
   # @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
@@ -56,45 +72,178 @@ module CurlyBracketParser
 
   #----------------------------------------------------------------------------------------------------
 
-  def self.parse_file(path, variables, options = {})
-    raise "NOT IMPLEMENTED YET!"
+  # Parse the content of the file of the given path with #parse and return it.
+  # The original file keeps unmodified.
+  #
+  # @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.
+  # @return [String, UnresolvedVariablesError] parsed string
+  def self.parse_file(path, variables, unresolved_vars: :raise, replace_pattern: "##\\1##")
+    file_content = File.read path
+    parse(file_content, variables, unresolved_vars: unresolved_vars, replace_pattern: replace_pattern)
+  end
+
+  # Parse the content of the file of the given path with #parse and return it.
+  # The original file will be overwritten by the parsed content.
+  #
+  # @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.
+  # @return [String, UnresolvedVariablesError] parsed string
+  def self.parse_file!(path, variables, unresolved_vars: :raise, replace_pattern: "##\\1##")
+    parsed_file = parse_file path, variables, unresolved_vars: unresolved_vars, replace_pattern: replace_pattern
+    File.write path, parsed_file
+    parsed_file
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # Register your custom filter to the filter list
+  #
+  # @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
+  # @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.parse_file!(path, variables, options = {})
-    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.register_filter(name, function)
-    raise "NOT IMPLEMENTED YET!"
+  # 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
 
   #----------------------------------------------------------------------------------------------------
 
-  def self.register_default_variable(name, function)
-    raise "NOT IMPLEMENTED YET!"
+  # 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
 
   #----------------------------------------------------------------------------------------------------
 
-  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
+  # 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
+      message = "Invalid default variable '#{name}'. Valid registered default variables are: #{self.registered_default_vars.keys.join(' ')}"
+      raise InvalidVariableError, message
+    end
+  end
+
+  #----------------------------------------------------------------------------------------------------
+
+  # 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
-      raise "Invalid filter '#{filter}'"
+      false
     end
   end
 
   #----------------------------------------------------------------------------------------------------
 
-  def self.has_filter?(variable)
-    decode_variable(variable)[:filter] != nil
+  # 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
 
   #----------------------------------------------------------------------------------------------------
@@ -105,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)
@@ -133,12 +286,21 @@ module CurlyBracketParser
 
   #----------------------------------------------------------------------------------------------------
 
+  # Check if any variable is included in the given 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
   end
 
   #----------------------------------------------------------------------------------------------------
 
+  # Check if one of the given variable names is included in the given string
+  #
+  # @param [Array<String>] variable_names
+  # @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|
       return true if variable_names.include?(dvar[:name])

data/lib/curly_bracket_parser/version.rb

@@ -1,3 +1,3 @@
 module CurlyBracketParser
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.9.9'.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.0.1
+  version: 0.9.9
 platform: ruby
 authors:
 - Matthäus Beyrle
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-17 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