Module: FlossFunding::Poke

Defined in:
lib/floss_funding/poke.rb

Overview

Public API for including FlossFunding into your library/module.

Usage patterns:

  1. Traditional namespace (uses the including module’s name):

    module MyGemLibrary
    include FlossFunding::Poke.new(FILE)
    end

  2. Arbitrary custom namespace (can add version, or anything else):

    module MyGemLibrary
    include FlossFunding::Poke.new(FILE, namespace: “Custom::Namespace::V4”)
    end

  3. Explicitly disable config discovery (including library_name) by passing nil and wedge: true:

    module MyGemLibrary
    include FlossFunding::Poke.new(nil, wedge: true)
    end

  4. Provide an explicit config path (bypasses directory-walk search):

    module MyGemLibrary
    include FlossFunding::Poke.new(FILE, config_path: “/path/to/.floss_funding.yml”)
    end

In all cases, the first parameter should be a String file path (e.g., __FILE__) or nil to disable discovery.

Class Method Summary collapse

Class Method Details

.included(base) ⇒ Object

Hook invoked when including FlossFunding::Poke directly.

Direct inclusion is not supported; always use Poke.new(__FILE__, ...).

Parameters:

  • base (Module) —

    the target including module

Raises:



42
43
44
 
# File 'lib/floss_funding/poke.rb', line 42

def included(base)
  raise ::FlossFunding::Error, "Do not include FlossFunding::Poke directly. Use include FlossFunding::Poke.new(__FILE__, namespace: optional_namespace)."
end

.new(including_path, options = {}) ⇒ Module

Builds a module suitable for inclusion which sets up FlossFunding.

Parameters:

  • including_path (String, nil) —

    the including file path (e.g., __FILE__) or nil to disable discovery

  • options (Hash) (defaults to: {}) —

    options hash for configuration

Options Hash (options):

  • :namespace (String, nil) —

    optional custom namespace for activation key

  • :silent (Object, nil) —

    optional silence flag or callable to request global silence

  • :config_path (String, nil) —

    explicit path to a config file; bypasses directory-walk search when provided

  • :wedge (Boolean, nil) —

    explicitly disable config discovery (including library_name)

Returns:

  • (Module) —

    a module that can be included into your namespace



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/floss_funding/poke.rb', line 55

def new(including_path, options = {})
  opts = options.dup
  silent_opt = opts[:silent]

  # If this library explicitly requests boolean silence, set it so libraries loaded later will be silenced;
  # callables are deferred to at_exit.
  if !silent_opt.respond_to?(:call) && silent_opt
    # don't deal with silent again unless it is callable
    opts.delete(:silent)
    ::FlossFunding.silenced ||= true
  end

  namespace = options.delete(:namespace)
  # When including_path is nil, disable discovery, by enforcing wedge: true
  wedge = options.delete(:wedge) || including_path.nil?
  contraindicated = ::FlossFunding::ContraIndications.poke_contraindicated?

  # an anonymous module that will set up an activation key check when included
  Module.new do
    define_singleton_method(:included) do |base|
      # Always extend Fingerprint first, before any validations or short-circuits
      base.extend(::FlossFunding::Fingerprint)

      # After fingerprinting, handle short-circuits
      # In wedge mode, we still register a minimal event so at_exit summary reflects usage
      if wedge
        begin
          ::FlossFunding.debug_log { "[Poke] wedge registration for #{base.name.inspect} ns=#{(namespace || base.name).inspect}" }
          ::FlossFunding.register_wedge(base, namespace)
        rescue StandardError => e
          # never raise from wedge registration, but record and become inert
          ::FlossFunding.error!(e, "Poke#wedge_registration")
        end
        return
      end

      # Do not proceed with registration/config when contraindicated
      return if contraindicated

      FlossFunding::Inclusion.new(base, namespace, including_path, options)
    end
  end
end