betterlog 2.1.1 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f2e9ee107c04ca121cd96cfa729d5f38ffa93ba4fcc72a0b98d9a6eff616177
-  data.tar.gz: c921b345079562a1ea1959fbe357d86ee56a54922cb4d367d8b4c8bdff719d45
+  metadata.gz: e44f75b0aa17e54401d1ecb4ad6d33d8081cae0f6f07740a762d7597e06faa58
+  data.tar.gz: e76cd7fbdd63d2f881e3b8e370135466408161d352a81ff84b839cfa5c1ab41c
 SHA512:
-  metadata.gz: 3e9527c09905b4263af1e541cc6b6c3c48f6712c50fa853b084ec07a29146da16aad4ebaed0d53d1fe6c0f95765d35a0fbdc970d78bd9b60ad105d7ca6c5ce11
-  data.tar.gz: 2155967f4c360239bd4f45b33dfc7af976a9ef302caf1cd949a103167aeaf5d1d0a632c1411b99dfa254d5498ca53d732984fb656ae519df4bb0da1c21a12aaa
+  metadata.gz: 631e02be296ef311afa02fd8eb15bb6a2c9913c07ec175bd18c767c351b2431e0ec6eb5c01a7d8638b343b13d621b3790b3c710b5aad1bd728cb550e503c6266
+  data.tar.gz: 2ecc2726e28df7efe266cac59a2d6e39b376a1c3e84d2132ffb135cc83d65cf75f523cccea8f4b48587ee5a3c84dc19b18425e067bd2ad6ade239037c944c5d1

data/CHANGES.md

@@ -1,5 +1,15 @@
 # Changes
 
+## 2025-09-03 v2.1.3
+
+- Improved documentation for the `colorize` method with detailed styling examples
+- Enhanced documentation for the `format_pattern` method with a detailed syntax guide
+- Added `doc` directory to `.gitignore` and updated `Rakefile` to include it in the ignore list
+
+## 2025-09-02 v2.1.2
+
+- Moved only `filter_severities` method to private scope
+
 ## 2025-09-02 v2.1.1
 
 - Set required Ruby version to ~> **3.2** in both `Rakefile` and

data/Rakefile

@@ -12,8 +12,8 @@ GemHadar do
   test_dir    'spec'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc',
     '.ruby-version', '.AppleDouble', 'tags', '.DS_Store', '.utilsrc',
-    '.bundle', '.byebug_history', 'errors.lst', '.yardoc', 'betterlog-server',
-    'gospace'
+    '.bundle', '.byebug_history', 'errors.lst', '.yardoc', 'doc',
+    'betterlog-server', 'gospace'
   package_ignore '.all_images.yml', '.utilsrc', '.rspec', '.tool-versions',
     '.gitignore', *Dir['.semaphore/**/*'], *Dir['.github/**/*']
   readme      'README.md'

data/VERSION

@@ -1 +1 @@
-2.1.1
+2.1.3

data/betterlog.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: betterlog 2.1.1 ruby lib
+# stub: betterlog 2.1.3 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterlog".freeze
-  s.version = "2.1.1".freeze
+  s.version = "2.1.3".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

data/bin/betterlog

@@ -119,14 +119,13 @@ module Betterlog
       exit(0)
     end
 
-    private\
     # Filters log severities based on command-line options.
     #
     # This method processes the configured severity filters from the options hash,
     # applying inclusive and exclusive selection criteria to narrow down the
     # available severity levels. It supports comparison operators for range-based
     # filtering and exact matches for specific severities.
-    def filter_severities
+    private def filter_severities
       @severities = Log::Severity.all
       if severity = @opts[?S]
         severity.each do |s|

data/lib/betterlog/log/event_formatter.rb

@@ -65,15 +65,48 @@ module Betterlog
       #
       # This method applies visual styling to a string by looking up the
       # appropriate style configuration based on the provided key and value,
-      # then applying that style using the internal apply_style method.
-      #
-      # @param key [ Object ] the lookup key for determining the style
-      # configuration
-      # @param value [ Object ] the value used to determine which specific
-      # style to apply
-      # @param string [ Object ] the string to be colorized, defaults to the
-      # key if not provided
-      # @return [ String ] the colorized string based on the configured styles
+      # then applying that style using the internal apply_style method. The
+      # colorization logic supports both static and dynamic styling based on
+      # the value being formatted.
+      #
+      # <b>Style Configuration Patterns</b>
+      #
+      # Styles can be configured in several ways:
+      #
+      # <b>Static Styles</b>
+      # - String: Single ANSI color code (e.g., "red", "bold")
+      # - Array: Multiple ANSI codes (e.g., ["red", "bold"])
+      #
+      # <b>Dynamic Styles</b>
+      # - ComplexConfig::Settings: Different styles based on value content
+      #   Example: { debug: "green", error: "red" } where the style is selected based on the value
+      #
+      # <b>Usage Examples</b>
+      #
+      # Given a configuration like:
+      #   styles:
+      #     'timestamp': [ yellow, bold ]
+      #     severity:
+      #       debug: green
+      #       info: green
+      #       warn:  yellow
+      #       error: red
+      #
+      # The method will:
+      # - Colorize "{timestamp}" with yellow/bold styling
+      # - Colorize "{severity}" with green for "debug"/"info", yellow for "warn", red for "error"
+      #
+      # @param key [Object] the lookup key for determining the style configuration
+      # @param value [Object] the value used to determine which specific style to apply
+      # @param string [Object] the string to be colorized, defaults to the key if not provided
+      # @return [String] the colorized string based on the configured styles
+      # @see Betterlog::Log::EventFormatter#apply_style
+      #
+      # @example Static styling
+      #   colorize(:timestamp, nil, "2023-12-01")  # Returns colored timestamp string
+      #
+      # @example Dynamic styling based on value
+      #   colorize(:severity, :error, "ERROR")    # Returns red-colored string
       def colorize(key, value, string = key)
         case style = cc.log.styles[key]
         when nil, String, Array
@@ -109,18 +142,54 @@ module Betterlog
         end
       end
 
-      # Formats a log event using a specified pattern with support for
-      # directives and colorization.
+      # Formats a log event using a specified pattern with support for directives and colorization.
       #
-      # This method processes a format string by replacing placeholders with
-      # actual event data, applying formatting directives for special handling
-      # of values like objects or timestamps, and optionally applying color
-      # styling based on configured styles.
+      # This method processes a format string by replacing placeholders with actual event data,
+      # applying formatting directives for special handling of values like objects or timestamps,
+      # and optionally applying color styling based on configured styles.
       #
-      # @param format [ String ] the format pattern to apply to the log event
-      # @return [ String ] the formatted string representation of the log event
+      # <b>Format Pattern Syntax</b>
+      #
+      # Format patterns use curly braces `{}` to define placeholders with optional directives:
+      #
+      # <b>Basic Key Substitution</b>
+      # - `{key}` - Substitutes the value of `@event[key]`
+      # - `{-key}` - Invisible variant; omits output when value is nil (instead of showing `{key}`)
+      #
+      # <b>Object Formatting Directives</b>
+      # - `{%O%key}` - Formats complex objects (arrays/hashes) with nested structure visualization
+      #   Example: Shows arrays with bullet points and hashes with key-value pairs
+      #
+      # <b>Timestamp Formatting Directives</b>
+      # - `{%t%key}` - Formats timestamp values with various time formats based on flag:
+      #   - `%ut%key` - UTC ISO8601 format (e.g., "2023-12-01T10:30:45.123Z")
+      #   - `%lt%key` - Local time ISO8601 format
+      #   - `%it%key` - Unix timestamp integer (e.g., "1701423425")
+      #   - `%ft%key` - Unix timestamp float (e.g., "1701423425.123")
+      #   - `%t%key` (default) - UTC ISO8601 format
+      #
+      # <b>String Formatting Directives</b>
+      # - `{%.format%key}` - Applies Ruby string formatting using the `%` operator
+      #   Example: `{%.2f%price}` formats a float to 2 decimal places
+      #
+      # <b>Colorization</b>
+      # Values are automatically colorized based on configured styles in the `styles` configuration.
+      # For example, timestamp values use yellow/bold styling, and severity levels use different colors
+      # based on their value (debug=green, warn=yellow, error=red, etc.).
+      #
+      # @param format [String] the format pattern to apply to the log event
+      # @return [String] the formatted string representation of the log event
       # @see Betterlog::Log::EventFormatter#format_object
       # @see Betterlog::Log::EventFormatter#colorize
+      #
+      # @example Basic usage with default configuration
+      #   formatter.format_pattern(format: "{%lt%timestamp} {message}")
+      #
+      # @example Complex formatting with object display
+      #   formatter.format_pattern(format: "{%O%backtrace} {message}")
+      #
+      # @example Conditional display of optional fields
+      #   formatter.format_pattern(format: "{file}{-%O%backtrace}")
       def format_pattern(format:)
         format.
           gsub('\n', "\n").

data/lib/betterlog/version.rb

@@ -1,6 +1,6 @@
 module Betterlog
   # Betterlog version
-  VERSION         = '2.1.1'
+  VERSION         = '2.1.3'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: betterlog
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.1.3
 platform: ruby
 authors:
 - betterplace Developers