lamian 0.3.3 → 1.0.0alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d930fc16394a1bd7581075c1954e1d88856e8ae
-  data.tar.gz: 0e8748b7f588666c1b691f367ff8420a723c3108
+  metadata.gz: ce288b47c40d6a1f17839187b23d82035175c4af
+  data.tar.gz: fbc768abd2f211ba6a4ad617aa3ea74c5876a26a
 SHA512:
-  metadata.gz: 6986d58f6a9e1c3b4d99fbf879ddbb0995b93af1212e4ac8c6a20068cba411754cb40ef4c277cb50a84b0acd239c8a7c05dc077ba5f32e0c69cd9b698088b1fa
-  data.tar.gz: 44a3f5301eb75d07010548ec272ddca4ac155bcca5ab1d1c4f64ee59d3acb0cc5571f7067293c6c47ff12cbf260271ad609ff84be0b2ed0f29668312811a9342
+  metadata.gz: '027578767295a91366fca4de695f6de44111fdce461fece1ad13fe0fb187dcaaff172988bc42dd57c60036c41f2122e861d1a153947f8a75b8a67a2185675f3c'
+  data.tar.gz: 3e577960fe820800fe8f2925eec5e2733b94a02c3571a7d50ed909dec45e5f44c41628928057328778c27b85f31b8a91590417451f26bfc89d91057a4ac96390

data/lib/lamian.rb

@@ -1,15 +1,27 @@
 # frozen_string_literal: true
 
+# Lamian is an in-memory logger, which content could be released
+# for error messages.
+# It is designed to work in pair with `exception_notification` gem inside
+# rails aplications
 module Lamian
-  autoload :VERSION, 'lamian/version'
-  autoload :Config, 'lamian/config'
-  autoload :Logger, 'lamian/logger'
-  autoload :LoggerExtension, 'lamian/logger_extension'
-  autoload :Middleware, 'lamian/middleware'
+  autoload :VERSION, "lamian/version"
+  autoload :Config, "lamian/config"
+  autoload :Logger, "lamian/logger"
+  autoload :LoggerExtension, "lamian/logger_extension"
+  autoload :Middleware, "lamian/middleware"
 
-  require 'lamian/engine'
+  require "lamian/engine"
 
   class << self
+    # Yields curent configuration if block given
+    # @example
+    #   Lamian.configure do |config|
+    #     config.formatter = MyFormatter.new
+    #   end
+    # @yield [config] current configuration
+    # @yieldparam config [Lamian::Config]
+    # @return [Lamian::Config] current configuration
     def configure
       @config ||= Config.new
       yield(@config) if block_given?
@@ -17,18 +29,30 @@ module Lamian
     end
     alias config configure
 
+    # Extends logger instance to tee it's output to Lamian logger
+    # @param other_logger [Logger] logger to extend
     def extend_logger(other_logger)
       other_logger.extend(Lamian::LoggerExtension)
     end
 
+    # @api private
+    # Gives access to current logger
+    # @return [Lamian::Logger] current logger
     def logger
       Lamian::Logger.current
     end
 
+    # Collects logs sent inside block
     def run
       logger.run { yield }
     end
 
+    # Dumps log collected in this run
+    # @option format [Symbol]
+    #   requested format of log. At this point, returns raw log if falsey
+    #   or log without controll sequences (such as '[23m') if truthy
+    #   value given (for now)
+    # @return formatted log (String by default)
     def dump(format: nil)
       logger.dump(format: format)
     end

data/lib/lamian/config.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
-require 'logger'
+
+require "logger"
 
 module Lamian
+  # General lamian configuration class
+  # @attr formatter [Logger::Foramtter]
+  #   formatter to use in lamian, global
   Config = Struct.new(:formatter) do
     def initialize
       self.formatter = ::Logger::Formatter.new

data/lib/lamian/engine.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
-require 'rails'
-require 'exception_notification'
-require 'exception_notification/rails'
+
+require "rails"
+require "exception_notification"
+require "exception_notification/rails"
 
 module Lamian
+  # Rails engine, which injects middleware and appends
+  # lamian views to rails library.
+  # Lamian views are used in exception_notifier to provide
+  # request_log section
   class Engine < ::Rails::Engine
     config.app_middleware.insert_before(
       ExceptionNotification::Rack,
-      ::Lamian::Middleware
+      ::Lamian::Middleware,
     )
 
-    paths['app/views'] << 'lib/lamian/rails_views'
+    paths["app/views"] << "lib/lamian/rails_views"
   end
 end

data/lib/lamian/logger.rb

@@ -1,9 +1,21 @@
 # frozen_string_literal: true
 
-require 'logger'
+require "logger"
 
 module Lamian
+  # @api private
+  # Provides thread-local loggers to catch teed messages from
+  # regular loggers.
+  # Uses :__lamian_logger thread variable
+  # @attr level [Int]
+  #   current log level, implicitly set to zero
+  # @attr logdevs [Array(StringIO)]
+  #   stack of log devices used to store logs
+  # @attr formatter [Logger::Formatter]
+  #   formatter, inherited from Lamian.config
   class Logger < ::Logger
+    # Provides access to logger bound to curent thread
+    # @return [Lamian::Logger] current logger
     def self.current
       Thread.current[:__lamian_logger] ||= new
     end
@@ -14,6 +26,8 @@ module Lamian
       self.formatter = Lamian.config.formatter
     end
 
+    # @see Lamian.run
+    # Collects logs sent inside block
     def run
       push_logdev(StringIO.new)
       yield
@@ -21,10 +35,19 @@ module Lamian
       pop_logdev
     end
 
+    # Part of Logger api, entry point for all logs
+    # extened to run on each log device in stack
     def add(*args, &block)
       each_logdev { super(*args, &block) }
     end
 
+    # @see Lamian.dump
+    # Dumps log collected in this run
+    # @option format [Symbol]
+    #   requested format of log. At this point, returns raw log if falsey
+    #   or log without controll sequences (such as '[23m') if truthy
+    #   value given (for now)
+    # @return formatted log (String by default)
     def dump(format: nil)
       result = logdevs[-1]&.string&.dup
       apply_format!(format, result)
@@ -35,20 +58,34 @@ module Lamian
 
     attr_accessor :level, :logdevs, :formatter
 
-    def apply_format!(format, result)
+    # Formats string using given format
+    # @todo create `formatters` interface to allow real format selection
+    # @note
+    #   `format` is now checked only for thruthyness. Please, use
+    #   `:text` format to keep it same after `formatters` interface integration
+    # @param format [Symbol] requested format, e.g. `:text`
+    # @param string [String] string to be changed
+    # @return avoid return value usage
+    def apply_format!(format, string)
       return unless format
-      return unless result
-      result.gsub!(/\[\d{1,2}m/, '')
+      return unless string
+      string.gsub!(/\[\d{1,2}m/, "")
     end
 
+    # Pushes new logdev in the start of #run call
+    # @param logdev [StringIO] new StringIO
     def push_logdev(logdev)
       logdevs << logdev
     end
 
+    # Pops logdev in the end of #run call
+    # @return [StringIO] logdev
     def pop_logdev
       logdevs.pop
     end
 
+    # Runs specific block with all logdevs in stack to
+    # populate them all
     def each_logdev
       logdevs.each do |logdev|
         @logdev = logdev

data/lib/lamian/logger_extension.rb

@@ -1,9 +1,20 @@
 # frozen_string_literal: true
+
 module Lamian
+  # Provides extension to loggers, which should be teed to lamian
   module LoggerExtension
+    # @api stdlib
+    # Add is a single entry point for ::Logger.{debug,info,..}
     def add(*args, &block)
       Logger.current.add(*args, &block)
       super
     end
+
+    # @api stdlib
+    # log is an alis for add and should also be prepended
+    def log(*args, &block)
+      Logger.current.add(*args, &block)
+      super
+    end
   end
 end

data/lib/lamian/middleware.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
+
 module Lamian
+  # Provides rack middleware, which allows to colelct request logs
+  # @attr app [Proc] stored application
   class Middleware
+    # @param app [Proc] stored application
     def initialize(app)
       self.app = app
     end
 
+    # wraps application inside lamian context and calls it
+    # @param env [Hash] left intact
+    # @return result of app.call
     def call(env)
       Lamian.run { app.call(env) }
     end

data/lib/lamian/version.rb

@@ -1,4 +1,17 @@
 # frozen_string_literal: true
+
 module Lamian
-  VERSION = '0.3.3'
+  # Current lamian vewrsion
+  #
+  # format: 'a.b.c' with possible suffixes such as alpha
+  # * a is for major version, it is guaranteed to be changed
+  #   if back-compatibility of public API is broken
+  # * b is for minor version, it is guaranteed to be changed
+  #   on public API changes and also if private API
+  #   back-compatibility is broken
+  # * c is for incremental version, it is updated in other cases
+  # According to this, it is enought to specify '~> a.b'
+  # if private API was not used and to specify '~> a.b.c' if it was
+
+  VERSION = "1.0.0alpha"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lamian
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 1.0.0alpha
 platform: ruby
 authors:
 - JelF
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-22 00:00:00.000000000 Z
+date: 2017-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -81,19 +81,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: rubocop-config-umbrellio
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.45'
+        version: 0.49.1.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.45'
+        version: 0.49.1.4
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +122,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: launchy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.3
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.0
 description: Add logs to your error messages, using exception_notifier or smth like
   it
 email:
@@ -153,12 +195,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: Add logs to your error messages