scarpe-components 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2033509feb830b1bc7fa18f1275c7e1735e7ef7212808d0c4e3618873016b23
+  data.tar.gz: 1c8f7bf639f4e4b00f578263ea9be8a2be4b1773aa002457f50866e89159ad73
+SHA512:
+  metadata.gz: 7afb7e7b1e63029d673d3274f0c7b5cbe00871d2af4178863d2211f375eb222b65572adae625252da985b341c5df7e2c671df4c184b3f05fde2484a567199a72
+  data.tar.gz: 6b4b76d33119f9a1688d6614e06c07ac63fca5a9741f4a627ced93ed10bf5ff22e8d110a844f6a7a9c6badbcc88d80e709eb9cc5c51534997ff18dccee308825

data/README.md

@@ -0,0 +1,35 @@
+# Scarpe-Components
+
+Scarpe is several things. We package up the Shoes API with as few implementation details as possible (called Lacci.) We have a Webview-based display library, in both local and over-a-socket (relay) versions. We have a Wasm display library (Scarpe-Wasm) in a separate gem.
+
+And we have various default implementations of different reusable components. Scarpe's hierarchical logger isn't particularly specific to your display library or underlying GUI library, but we'd like it to be usable by multiple display libs. CatsCradle is only useful if you're trying to fix up an impedance mismatch between Ruby and an evented under-layer, but it's not really specific to Webview. Scarpe's default downloader, using Ruby's built-in HTTP libraries, is good in many cases but you might want to replace it (e.g. with Typhoeus for better parallel downloads or Hystrix for robustness to bad network connections) in some cases.
+
+Part of our solution is the Scarpe-Components gem, which lives in the same repository as Scarpe (for now?). These components can live there. Any specific display library can pick and choose what it wants or needs and handle its dependencies as it sees fit.
+
+## Dependency Hell
+
+A "gem full of optional reusable components" presents an awkward challenge for Rubygems. What are the gem's dependencies? Do you make it depend on every possible library, requiring FastImage and Nokogiri and SQLite and whatever else any component might ever require? That would be as bad as making ActiveRecord need MySQL and SQLite and Postgres and Oracle and... But if you don't give it *any* dependencies, you're going to have a harsh surprise at runtime when Bundler can't find any of the gems you need.
+
+You can break everything up into tiny pieces, like ActiveRecord having a separate adapter for certain databases. You could do the same with an activerecord-mysql and activerecord-postgres and activerecord-sqlite gem to complete the set. Or, like, ActiveRecord, you can say "declare activerecord as a dependency, and also one or more other database gems, and we'll figure out what's available at runtime." That approach can be pretty fragile and it adds extra complexity -- how do you make sure everything is required at the right time and ActiveRecord can find everything that's available? How do you balance gem dependencies that are built into ActiveRecord with those for unusual databases that get added by other gems, later? Your plugin system (like ActiveRecord's) can get extensive and fragile.
+
+Scarpe-Components kicks that problem down the road to the display libraries. Would a particular display library like to use the FastImage-based image implementation? Great! It can declare a dependency on the FastImage gem. Would it like to optionally allow the built-in Ruby downloader, but also have an optional robustified version using RestClient? Lovely. It can either create multiple gems (e.g. scarpe-gtk-rcdownload and scarpe-gtk-plaindownload) or look for RestClient being available at runtime, as it pleases. The FastImage implementation lives in Scarpe-Components, but the dependency is declared by the display library or the app.
+
+## Using an Implementation
+
+Components in Scarpe-Components are designed to be used individually. They can require each other, but they should only require components they will actually use. The whole library is designed to be used a la carte, and normally no display service will use every component.
+
+A display library will declare scarpe-components as a dependency. Then, usually from its named require file (e.g. wv_local.rb, wv_relay.rb, wasm_local.rb) it will set up those dependencies by requiring components that it wants and if necessary creating and configuring them. That way a specific display service (e.g. wv_local) can require a specific component (e.g. Logging-gem-based hierarchical logging) and configure it how it wants (e.g. ENV var pointing to a local JSON config file.)
+
+## How is this Different from Lacci?
+
+Scarpe already has a gem full of reusable components, one that every Scarpe-based application already has to use. Lacci declares the Shoes API, and is 100% required for every Scarpe-based Shoes application everywhere.
+
+So how do you tell what goes into Scarpe-Components vs what goes into Lacci?
+
+Lacci is, at heart, an API with as little implementation as possible. It declares the Shoes GUI objects, but not how to display them. Ordinarily a Shoes application will require (in the sense of Kernel#require) every part of Lacci -- it will load the entire library. Even if we add optional components (e.g. a Lacci-based Bloops API with no implementation behind it), those components will be loaded by every Shoes app that uses that part of the API.
+
+As a result, Lacci should have minimal (preferably zero) dependencies. Any code doing "real work" should be removed from Lacci completely, as soon as possible. Since *every* Shoes app is going to require Lacci, it should be possible to use it with essentially no dependencies, minimal memory footprint, minimal load time. It is a skeleton to hang functionality on, not a thing that functions for itself.
+
+Scarpe-Components is a grab bag of default implementations, intended to be replaceable. But each of them does something. Most of them have dependencies. It's fine for a Scarpe-Component implementation to depend on the Logging gem, provided it says it does. Nokogiri? 100% fair. Does it do something with a nontrivial amount of computation, like rendering HTML output? No problem. This is very different from Lacci.
+
+If a component should be reused, it's probably fine to put it into Scarpe-Components. It *might* be fine to put it in Lacci. For Scarpe-Components, ask yourself, "will more than one Scarpe display service possibly want to use this?" For Lacci, the test is more strict: "will *every* Scarpe display service want to use this? Does it have no dependencies at all, and do very little computation and take very little memory?"

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: [:test]

data/lib/scarpe/logger.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "logging"
+require "json"
+
+require "shoes/log"
+
+# Requirements: logging gem
+
+class Scarpe
+  class LogImpl
+    include Shoes::Log # for constants
+
+    def logger_for_component(component)
+      Logging.logger[component]
+    end
+
+    private
+
+    def name_to_severity(data)
+      case data
+      when "debug"
+        :debug
+      when "info"
+        :info
+      when "warn"
+        :warn
+      when "err", "error"
+        :error
+      when "fatal"
+        :fatal
+      else
+        raise "Don't know how to treat #{data.inspect} as a logger severity!"
+      end
+    end
+
+    def json_to_appender(data)
+      case data.downcase
+      when "stdout"
+        Logging.appenders.stdout layout: @custom_log_layout
+      when "stderr"
+        Logging.appenders.stderr layout: @custom_log_layout
+      when String
+        Logging.appenders.file data, layout: @custom_log_layout
+      else
+        raise "Don't know how to convert #{data.inspect} to an appender!"
+      end
+    end
+
+    def json_configure_logger(logger, data)
+      case data
+      in String
+        sev = name_to_severity(data)
+        logger.level = sev
+      in [level, *locations]
+        if logger.name != "root"
+          # The Logging gem doesn't have an additive property on the root logger
+          logger.additive = false # Don't also log to parent/root loggers
+        end
+
+        logger.appenders = locations.map { |where| json_to_appender(where) }
+
+        logger.level = name_to_severity(level)
+      else
+        raise "Don't know how to use #{data.inspect} to specify a logger!"
+      end
+    end
+
+    def freeze_log_config(log_config)
+      log_config.each do |k, v|
+        k.freeze
+        v.freeze
+        v.each(&:freeze) if v.is_a?(Array)
+      end
+      log_config.freeze
+    end
+
+    public
+
+    def configure_logger(log_config)
+      # TODO: custom coloring? https://github.com/TwP/logging/blob/master/examples/colorization.rb
+      @custom_log_layout = Logging.layouts.pattern pattern: '[%r] %-5l %c: %m\n'
+
+      if log_config.is_a?(String) && File.exist?(log_config)
+        log_config = JSON.load_file(log_config)
+      end
+
+      log_config = freeze_log_config(log_config) unless log_config.nil?
+      @current_log_config = log_config # Save a copy for later
+
+      Logging.reset # Reset all Logging settings to defaults
+      Logging.reopen # For log-reconfig (e.g. test failures), often important to *not* store an open handle to a moved file
+      return if log_config.nil?
+
+      Logging.logger.root.appenders = [Logging.appenders.stdout]
+
+      default_logger = log_config[DEFAULT_COMPONENT] || "info"
+      json_configure_logger(Logging.logger.root, default_logger)
+
+      log_config.each do |component, logger_data|
+        next if component == DEFAULT_COMPONENT
+
+        sublogger = Logging.logger[component]
+        json_configure_logger(sublogger, logger_data)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: scarpe-components
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marco Concetto Rudilosso
+- Noah Gibbs
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-08-08 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- marcoc.r@outlook.com
+- the.codefolio.guy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/scarpe/logger.rb
+homepage: https://github.com/scarpe-team/scarpe
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/scarpe-team/scarpe
+  source_code_uri: https://github.com/scarpe-team/scarpe
+  changelog_uri: https://github.com/scarpe-team/scarpe/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Reusable components for Scarpe display libraries
+test_files: []