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

In all cases, the first parameter must be a String file path (e.g., __FILE__).

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:



30
31
32
 
# File 'lib/floss_funding/poke.rb', line 30

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) —

    the including file path (e.g., __FILE__)

  • 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

Returns:

  • (Module) —

    a module that can be included into your namespace



41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/floss_funding/poke.rb', line 41

def new(including_path, options = {})
  # Global silencer: short-circuit and do nothing when globally silenced.
  return Module.new if ::FlossFunding::Constants::SILENT

  namespace = options[:namespace]
  silent_opt = options[:silent]
  # an anonymous module that will set up an activation key Check when included
  Module.new do
    define_singleton_method(:included) do |base|
      FlossFunding::Poke.setup_begging(base, namespace, including_path, silent_opt)
    end
  end
end

.setup_begging(base, custom_namespace, including_path, silent_opt = nil) ⇒ void

This method returns an undefined value.

Performs common setup: extends the base with Check, computes the
namespace and ENV var name, loads configuration, and initiates begging.

Parameters:

  • base (Module) —

    the module including the returned Poke module

  • custom_namespace (String, nil) —

    custom namespace or nil to use base.name

  • including_path (String) —

    source file path of base (e.g., __FILE__)

  • silent_opt (Object, nil) (defaults to: nil) —

    optional silence flag or callable stored under “silent” in config

Raises:



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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/floss_funding/poke.rb', line 65

def setup_begging(base, custom_namespace, including_path, silent_opt = nil)
  unless including_path.is_a?(String)
    raise ::FlossFunding::Error, "including_path must be a String file path (e.g., __FILE__), got #{including_path.class}"
  end
  unless base.respond_to?(:name) && base.name && base.name.is_a?(String)
    raise ::FlossFunding::Error, "base must have a name (e.g., MyGemLibrary), got #{base.inspect}"
  end

  require "floss_funding/check"
  # Extend the base with the checker module first
  base.extend(::FlossFunding::Check)

  # Load configuration from .floss_funding.yml if it exists
  config = ::FlossFunding::Config.load_config(including_path)

  # Three data points needed:
  # 1. namespace (derived from the base class name, config, or param)
  # 2. ENV variable name (derived from namespace)
  # 3. activation key (derived from ENV variable)
  namespace =
    if custom_namespace && !custom_namespace.empty?
      custom_namespace
    else
      base.name
    end

  # Track both the effective base namespace and the custom namespace (if provided)
  config["namespace"] ||= []
  config["namespace"] << base.name
  config["custom_namespaces"] ||= []
  config["custom_namespaces"] << custom_namespace if custom_namespace && !custom_namespace.empty?
  # Deduplicate
  config["namespace"] = config["namespace"].flatten.uniq
  config["custom_namespaces"] = config["custom_namespaces"].flatten.uniq

  env_var_name = ::FlossFunding::UnderBar.env_variable_name(
    {
      :namespace => namespace,
    },
  )
  activation_key = ENV.fetch(env_var_name, "")

  # Apply silent option if provided, storing into configuration under this library
  unless silent_opt.nil?
    config["silent"] ||= []
    config["silent"] << silent_opt
  end

  # Store configuration and ENV var name under the effective namespace
  ::FlossFunding.set_configuration(namespace, config)
  ::FlossFunding.set_env_var_name(namespace, env_var_name)

  # Now call the begging method after extending
  base.floss_funding_initiate_begging(activation_key, namespace, env_var_name)
end