frequency-dsl 0.0.7 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 885a326a495e7ef1629d6ba950b3796f8590b9193c5aa662a53423bbb111b751
+  data.tar.gz: 1e179bb453f710beca1f720f1c5c626cb117655a64a822004fc18d249111a1c5
+SHA512:
+  metadata.gz: 895c4e9dbb8bd2393109b5b8aeb67dde7ef8d2c1142ba30bb765fbc417098d443aebafd00bf09d491238176a21c12a7d5aec7331973006904a5d7a21035fe4a4
+  data.tar.gz: 98cb4ea17df2116de1dbbcac49e4144e6bc14c7d3da2a84c99c6c19e9de9665b994f0a3542392387083b1d6692ea29eb0f919d703f92145aa750aaa7aecb59a3

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026
+
+### Changed (BREAKING)
+
+- `with_probability` is now a keyword argument: use
+  `sometimes(with_probability: 0.1) { ... }` instead of the old
+  `sometimes(:with_probability => 0.1) { ... }`. The hash form no longer works.
+- Invalid probabilities now raise `Frequency::InvalidProbabilityError`
+  (subclass of `Frequency::Error < StandardError`) instead of a bare
+  `RuntimeError`.
+- Minimum Ruby version is now 3.1.
+
+### Added
+
+- `Frequency.random=` to inject a custom `Random` instance for reproducible runs.
+- `Frequency.with_seed(seed) { ... }` to scope a seeded RNG to a block.
+- Module-function call style: `Frequency.sometimes { ... }` works without
+  `include Frequency`.
+- GitHub Actions CI matrix across Ruby 3.1–3.4.
+- GitHub Actions release workflow using RubyGems trusted publishing (OIDC).
+- RuboCop config and lint job.
+
+### Fixed
+
+- Percent-string regex was using `.` (any char) instead of `\.`, so malformed
+  inputs like `"50x5%"` silently parsed. Now properly anchored and validated.
+- Probability validation now produces a clear error type and message.
+
+### Removed
+
+- Jeweler dependency and the generated `rdoc/` directory.
+
+## [0.1.x] - 2010
+
+Initial release. See git history.

data/README.md

@@ -0,0 +1,192 @@
+# Frequency
+
+[![CI](https://github.com/peczenyj/Frequency/actions/workflows/ci.yml/badge.svg)](https://github.com/peczenyj/Frequency/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/frequency-dsl.svg)](https://rubygems.org/gems/frequency-dsl)
+
+A small Ruby DSL for executing blocks with controlled probability:
+`always`, `normally`, `sometimes`, `rarely`, `never`.
+
+Useful for sampled logging, chaos testing, demo data generation, or anywhere
+you want a side effect to fire "occasionally" without writing `rand < 0.25`
+by hand every time.
+
+```ruby
+require "frequency"
+
+Frequency.always    { metrics.flush }
+Frequency.normally  { cache.write(key, value) }
+Frequency.sometimes { logger.debug(payload) }
+Frequency.rarely    { dump_full_state }
+Frequency.never     { not_in_production }
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "frequency-dsl"
+```
+
+```sh
+bundle install
+# or, standalone:
+gem install frequency-dsl
+```
+
+Requires Ruby 3.1 or newer.
+
+## Usage
+
+Two call styles are supported — pick whichever fits your code.
+
+### Module-function style
+
+Recommended for libraries and anywhere you want explicit namespacing:
+
+```ruby
+require "frequency"
+
+Frequency.sometimes { puts "maybe" }
+Frequency.rarely(with_probability: 0.01) { puts "1% of the time" }
+Frequency.normally(with_probability: "24%") { puts "string percent" }
+```
+
+### Mixin style
+
+Convenient at the script level or inside a host class:
+
+```ruby
+require "frequency"
+
+class EventLogger
+  include Frequency
+
+  def record(event)
+    sometimes { write_to_disk(event) }
+    rarely(with_probability: "0.1%") { ship_for_audit(event) }
+  end
+end
+```
+
+### The `with_probability:` keyword
+
+`sometimes`, `normally`, and `rarely` accept an optional `with_probability:`
+keyword argument. It overrides the method's default rate. Accepted values:
+
+| Value           | Meaning              |
+| --------------- | -------------------- |
+| `0.42`          | Float in `[0, 1]`    |
+| `"42%"`         | Percent string       |
+| `"42.5%"`       | Fractional percent   |
+| `"0.42"`        | Numeric string       |
+
+The keyword is ignored by `always` (always runs) and `never` (never runs).
+
+### Defaults
+
+```ruby
+Frequency.normally  { ... }   # 75%
+Frequency.sometimes { ... }   # 50%
+Frequency.rarely    { ... }   # 25%
+Frequency.maybe     { ... }   # alias of .sometimes
+```
+
+### Reproducible runs
+
+Inject your own RNG:
+
+```ruby
+Frequency.random = Random.new(42)
+```
+
+Or scope a seed to a single block — the previous RNG is restored afterward,
+even if the block raises:
+
+```ruby
+Frequency.with_seed(42) do
+  10.times { Frequency.sometimes { puts "deterministic" } }
+end
+```
+
+This is especially useful in tests, where you want `sometimes` to behave
+predictably without mocking `Kernel.rand`.
+
+### Errors
+
+Invalid probabilities raise `Frequency::InvalidProbabilityError`
+(a subclass of `Frequency::Error < StandardError`):
+
+```ruby
+Frequency.sometimes(with_probability: "101%") { ... }
+# => Frequency::InvalidProbabilityError: probability must be in [0, 1], got 1.01
+
+Frequency.sometimes(with_probability: "50x5%") { ... }
+# => Frequency::InvalidProbabilityError: could not parse probability: "50x5%"
+
+Frequency.sometimes(with_probability: :half) { ... }
+# => Frequency::InvalidProbabilityError: unsupported probability type: Symbol
+```
+
+## Development
+
+After cloning:
+
+```sh
+bin/setup            # bundle install
+bundle exec rake     # specs + lint (Standard)
+bundle exec rspec    # specs only
+bin/console          # IRB with Frequency loaded
+```
+
+Continuous integration runs against Ruby 3.1, 3.2, 3.3, and 3.4 on every
+push and pull request — see [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+## Releasing
+
+Releases go to RubyGems via [trusted publishing][tp] — no long-lived API
+tokens stored as repository secrets. A push of a `v*` tag triggers
+[`.github/workflows/release.yml`](.github/workflows/release.yml), which
+runs specs, builds the gem, and authenticates to RubyGems via short-lived
+OIDC credentials.
+
+**One-time setup** (gem owner only):
+
+1. On <https://rubygems.org/gems/frequency-dsl>, open **Trusted publishers**
+   and create one with:
+   - Owner: `peczenyj`
+   - Repository: `Frequency`
+   - Workflow filename: `release.yml`
+   - Environment: `release`
+2. In this repo, go to **Settings → Environments** and create an environment
+   named `release`. Optional but recommended: add a required reviewer so each
+   release needs manual approval.
+
+**Cutting a release:**
+
+```sh
+# Bump Frequency::VERSION in lib/frequency.rb,
+# update CHANGELOG.md (move [Unreleased] entries under the new version),
+# then:
+git commit -am "Release v0.2.0"
+git tag v0.2.0
+git push origin master --tags
+```
+
+[tp]: https://guides.rubygems.org/trusted-publishing/
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/peczenyj/Frequency).
+
+1. Fork and create a branch
+2. Run `bin/setup`
+3. Make your change, add specs
+4. `bundle exec rake` — both specs and lint must pass
+5. Open a PR
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).
+
+Copyright © 2010–2026 Tiago Peczenyj.

data/VERSION

@@ -1 +1 @@
-0.0.7
+0.2.0

data/lib/frequency.rb

@@ -1,65 +1,117 @@
-# Module Frequency
-# A small dsl written in ruby to work with frequency events (never, sometimes, always..)
+# frozen_string_literal: true
+
+# A small DSL to execute blocks with controlled probability.
 #
+#   require "frequency"
+#
+#   # Module-function style:
+#   Frequency.sometimes { puts "maybe" }
+#   Frequency.rarely(with_probability: 0.01) { log_sample(event) }
+#   Frequency.normally(with_probability: "24%") { do_thing }
+#
+#   # Or mixin style:
+#   include Frequency
+#   sometimes { puts "maybe" }
 module Frequency
-  NORMALLY  = 0.75
-  SOMETIMES = 0.50
-  RARELY    = 0.25
-  
-  # always do something
-  # example:
-  #   always { puts "ok"}
-  def always(cond={})
+  VERSION = "0.2.0"
+
+  # Base error class. Catch this to handle any Frequency-raised error.
+  Error = Class.new(StandardError)
+
+  # Raised when the probability value is not a number/string in [0, 1].
+  InvalidProbabilityError = Class.new(Error)
+
+  DEFAULTS = {
+    normally: 0.75,
+    sometimes: 0.50,
+    rarely: 0.25
+  }.freeze
+
+  PERCENT_PATTERN = /\A-?\d+(?:\.\d+)?%\z/
+
+  # Always run the block. Returns the block's value, or nil if no block.
+  def always
     yield if block_given?
   end
-  
-  # normally (75%) do something,
-  # see sometimes method
-  # example:
-  #   normally { puts "ok"}
-  def normally(cond={})
-    execute_with_probability(cond,NORMALLY ) { yield } if block_given?
-  end
-  
-  # sometimes (50%) do something
-  # example:
-  #   sometimes do
-  #      # some code
-  #   end
-  # or adjusting the probability
-  #   sometimes :with_probability => 0.12 do
-  #     # some code
-  #   end
-  # you can use "12%" instead 0.12
-  #   sometimes(:with_probability => '13.6%') { ... }
-  def sometimes(cond={})
-    execute_with_probability(cond,SOMETIMES) { yield } if block_given?
+
+  # Never run the block. Returns nil. Ignores any arguments/block.
+  def never(*)
+    nil
   end
-  
-  # rarely (25%) do something,
-  # see sometimes method
-  # example:
-  #   rarely { puts "ok"}
-  def rarely(cond={})
-    execute_with_probability(cond,RARELY   ) { yield } if block_given?
+
+  # Run the block ~75% of the time by default.
+  def normally(with_probability: DEFAULTS[:normally], &block)
+    Frequency.__run(with_probability, &block)
   end
-  
-  # never do something
-  # example:
-  #   never { puts "ok"}  
-  def never(cond={})
-    nil
+
+  # Run the block ~50% of the time by default.
+  def sometimes(with_probability: DEFAULTS[:sometimes], &block)
+    Frequency.__run(with_probability, &block)
   end
-  
-  private
-  def execute_with_probability(conditions,default)
-    rate = conditions[:with_probability] || default
-    rate = Float(rate) rescue correct_if_string(rate)
-    raise "probability must be [0..100]%" unless 0 <= rate && rate <= 1 
-    yield if Kernel.rand() < rate
+
+  # Alias of #sometimes.
+  alias_method :maybe, :sometimes
+
+  # Run the block ~25% of the time by default.
+  def rarely(with_probability: DEFAULTS[:rarely], &block)
+    Frequency.__run(with_probability, &block)
   end
-  
-  def correct_if_string(rate)
-     Float(rate.gsub(/%$/,""))/100 if rate =~ /^-?\d+(.\d+)?%$/
+
+  # Make every public instance method also a module-level method, so both
+  # `include Frequency; sometimes { ... }` and `Frequency.sometimes { ... }`
+  # work. Unlike `module_function`, `extend self` keeps the methods public
+  # when the module is included as a mixin.
+  extend self
+
+  class << self
+    # Inject a custom Random instance for reproducible runs.
+    #   Frequency.random = Random.new(42)
+    attr_writer :random
+
+    def random
+      @random ||= Random.new
+    end
+
+    # Run a block with a temporarily-seeded RNG, then restore the previous one.
+    #   Frequency.with_seed(42) { sometimes { ... } }
+    def with_seed(seed)
+      previous = @random
+      @random = Random.new(seed)
+      yield
+    ensure
+      @random = previous
+    end
+
+    # @api private
+    def __run(probability, &block)
+      return nil unless block
+
+      rate = __coerce(probability)
+      unless (0.0..1.0).cover?(rate)
+        raise InvalidProbabilityError, "probability must be in [0, 1], got #{rate}"
+      end
+
+      block.call if random.rand < rate
+    end
+
+    private
+
+    def __coerce(value)
+      case value
+      when Numeric then value.to_f
+      when String then __parse_string(value)
+      else raise InvalidProbabilityError, "unsupported probability type: #{value.class}"
+      end
+    end
+
+    def __parse_string(str)
+      if PERCENT_PATTERN.match?(str)
+        Float(str.chomp("%")) / 100.0
+      else
+        Float(str)
+      end
+    rescue ArgumentError, TypeError
+      raise InvalidProbabilityError, "could not parse probability: #{str.inspect}"
+    end
   end
 end

metadata

@@ -1,98 +1,54 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: frequency-dsl
-version: !ruby/object:Gem::Version 
-  hash: 17
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 7
-  version: 0.0.7
+version: !ruby/object:Gem::Version
+  version: 0.2.0
 platform: ruby
-authors: 
+authors:
 - Tiago Peczenyj
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-
-date: 2010-05-19 00:00:00 -03:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :development
-  version_requirements: *id001
-description: A small dsl written in ruby to work with frequency events (never, sometimes, always..)
-email: tiago.peczenyj@gmail.com
+date: 2026-05-14 00:00:00.000000000 Z
+dependencies: []
+description: Frequency is a small DSL written in Ruby to work with frequency events
+  (never, sometimes, always, ...).
+email:
+- tiago.peczenyj@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
 - LICENSE
-- README.rdoc
-files: 
-- LICENSE
-- README.rdoc
-- Rakefile
+- README.md
 - VERSION
-- frequency-dsl.gemspec
 - lib/frequency.rb
-- rdoc/classes/Frequency.html
-- rdoc/created.rid
-- rdoc/files/README_rdoc.html
-- rdoc/files/lib/frequency_rb.html
-- rdoc/fr_class_index.html
-- rdoc/fr_file_index.html
-- rdoc/fr_method_index.html
-- rdoc/index.html
-- rdoc/rdoc-style.css
-- spec/frequency_spec.rb
-- spec/spec_helper.rb
-has_rdoc: true
-homepage: http://github.com/peczenyj/Frequency
-licenses: []
-
-post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
-require_paths: 
+homepage: https://github.com/peczenyj/Frequency
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/peczenyj/Frequency
+  source_code_uri: https://github.com/peczenyj/Frequency
+  bug_tracker_uri: https://github.com/peczenyj/Frequency/issues
+  changelog_uri: https://github.com/peczenyj/Frequency/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
   - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
   - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: 
-rubygems_version: 1.3.7
-signing_key: 
-specification_version: 3
-summary: A small dsl written in ruby to work with frequency events
-test_files: 
-- spec/frequency_spec.rb
-- spec/spec_helper.rb
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A small DSL for probabilistic event execution
+test_files: []

data/README.rdoc

@@ -1,41 +0,0 @@
-= Frequency
-
-Frequency is a small dsl written in ruby to work with frequency events (never, sometimes, always..)
-
-== Examples
-
-Frequency is easy... 
-
- 	require 'rubygems'
-	require 'frequency'
-
-	include Frequency
-
-	sometimes do
-	  puts "sometimes you can see this times, sometimes not"
-	end
-
-	never do
-	  puts "this line never will be print"
-	end
-
-	rarely :with_probability => 0.01 do
-	  puts "ok, its very rare..."
-	end
-	
-	normally :with_probability => '24%' do
-          puts "you can use strings instead float numbers"
-        end
-
-        always do
-          puts "bye" 
-        end
-
-the option with_probability does not work with never and always.
-
-== Install
- [sudo] gem install frequency-dsl
-
-== Copyright
-
-Copyright (c) 2010 Tiago Peczenyj. See LICENSE for details.

data/Rakefile

@@ -1,51 +0,0 @@
-require 'rubygems'
-require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "frequency-dsl"
-    gem.summary = %Q{A small dsl written in ruby to work with frequency events}
-    gem.description = %Q{A small dsl written in ruby to work with frequency events (never, sometimes, always..)}
-    gem.email = "tiago.peczenyj@gmail.com"
-    gem.homepage = "http://github.com/peczenyj/Frequency"
-    gem.authors = ["Tiago Peczenyj"]
-    gem.add_development_dependency "rspec"
-    # gem is a Gem::Specification...
-    # See http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end
-
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
-end
-
-Spec::Rake::SpecTask.new(:rcov) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
-task :spec => :check_dependencies
-
-task :default => :spec
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION')
-    version = File.read('VERSION')
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "frequency #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-