chars 0.2.1 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 744e39b682dc29231aafe96056415cc38c65e032df5c2a3aff6a5a846b38f67b
+  data.tar.gz: 47e309f42894f6d94ec2d15568d5d33df8a97600c1c227eb2366eb8fb8d56eb4
+SHA512:
+  metadata.gz: 20755db9457fda76ceed274d18919a43dbf3c850d0aaad6a38f077b0e89fcf15d7c0a79b3ac95fe158d5abef8db4e68bd0ccc6971f8989e0b4f7c918b9a282b8
+  data.tar.gz: 54bc4adfd93752f68454c475b57a1705428231f8decab3be8b8710d6c344c60715af7c466b21b7c398e7b2cc30801ff5fe77a4924e1ac34b4fa724c3f1a3adec

data/.document

@@ -1,4 +1,4 @@
 lib/**/*.rb
 - 
-ChangeLog.*
+ChangeLog.md
 LICENSE.txt

data/.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.4
+          - 2.5
+          - 2.6
+          - 2.7
+          - 3.0
+          - jruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,8 @@
+/Gemfile.lock
+/doc/
+/pkg/
+/vendor/bundle
+.DS_Store
+.yardoc
+*.swp
+*~

data/.yardopts

@@ -1 +1 @@
---markup markdown --title 'Chars Documentation' --protected --quiet --files ChangeLog.md,LICENSE.txt
+--markup markdown --title 'Chars Documentation' --protected --quiet

data/ChangeLog.md

@@ -1,3 +1,35 @@
+### 0.3.0 / 2021-10-23
+
+* Added {Chars::WHITESPACE}.
+* Added {Chars::DIGITS}.
+* Added {Chars::CharSet#each_substring_with_index}.
+* Added {Chars::CharSet#substrings_with_indexes}.
+* Added {Chars::CharSet#each_substring}.
+* Added {Chars::CharSet#substrings}.
+* Added {Chars::CharSet#each_string_of_length}.
+* Added {Chars::CharSet#strings_of_length}.
+* Added {Chars::StringEnumerator}.
+
+### 0.2.4 / 2021-10-22
+
+* Require [ruby] >= 2.0.0.
+* Added {Chars::CharSet#initialize_copy} to prevent leaking characters
+  between copied {Chars::CharSet} objects.
+
+### 0.2.3 / 2020-12-25
+
+* Change {Chars::CharSet} to inherit from `Set`, instead of `SortedSet`.
+
+### 0.2.2 / 2012-05-28
+
+* {Chars::CharSet#initialize} now raises a TypeError when given arguments
+  that were neither a `String`, `Integer` or `Enumerable`.
+* Allow {Chars::CharSet#strings_in} to yield results as they are found.
+* Improved the performance of {Chars::CharSet#strings_in} when operating on
+  small Strings.
+* Replaced ore-tasks with
+  [rubygems-tasks](https://github.com/postmodern/rubygems-tasks#readme).
+
 ### 0.2.1 / 2011-06-22
 
 * Added {Chars::CharSet.[]}
@@ -52,3 +84,4 @@
   belongs to a certain character set.
 * Supports random text generation using specific character sets.
 
+[ruby]: https://www.ruby-lang.org/

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+  gem 'rspec',          '~> 3.0'
+  gem 'kramdown'
+  gem 'yard',           '~> 0.9'
+  gem 'yard-spellcheck', require: false
+end

data/LICENSE.txt

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2009-2010 Hal Brodigan
+Copyright (c) 2009-2021 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,8 +1,10 @@
 # Chars
 
-* http://chars.rubyforge.org/
-* http://github.com/postmodern/chars/
-* Postmodern (postmodern.mod3 at gmail.com)
+[![CI](https://github.com/postmodern/chars.rb/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/chars.rb/actions/workflows/ruby.yml)
+
+* [Source](https://github.com/postmodern/chars.rb#readme)
+* [Issues](https://github.com/postmodern/chars.rb/issues)
+* [Documentation](https://rubydoc.info/gems/chars)
 
 ## Description
 
@@ -12,84 +14,162 @@ recognizing text and generating random text from specific character sets.
 ## Features
 
 * Provides character sets for:
-  * Numeric ('0' - '9')
-  * Octal ('0' - '7')
-  * Uppercase Hexadecimal ('0' - '9', 'A' - 'F')
-  * Lowercase Hexadecimal ('0' - '9', 'a' - 'f')
-  * Hexadecimal ('0' - '9', 'a' - 'f', 'A' - 'F')
-  * Uppercase Alpha ('A' - 'Z')
-  * Lowercase Alpha ('a' - 'z')
-  * Alpha ('a' - 'z', 'A' - 'Z')
-  * Alpha-numeric ('0' - '9', 'a' - 'z', 'A' - 'Z')
-  * Punctuation (' ', '\'', '"', '`', ',', ';', ':', '~', '-', '(', ')',
-    '[', ']', '{', '}', '.', '?', '!')
-  * Symbols (' ', '\'', '"', '`', ',', ';', ':', '~', '-', '(', ')',
-    '[', ']', '{', '}', '.', '?', '!', '@', '#', '$', '%', '^', '&', '*',
-    '_', '+', '=', '|', '\\', '<', '>', '/')
-  * Space (' ', '\f', '\n', '\r', '\t', '\v')
-  * Visible ('0' - '9', 'a' - 'z', 'A' - 'Z', '\'', '"', '`', ',',
-    ';', ':', '~', '-', '(', ')', '[', ']', '{', '}', '.', '?', '!', '@',
-    '#', '$', '%', '^', '&', '*', '_', '+', '=', '|', '\\', '<', '>', '/',)
-  * Printable ('0' - '9', 'a' - 'z', 'A' - 'Z', ' ', '\'', '"', '`', ',',
-    ';', ':', '~', '-', '(', ')', '[', ']', '{', '}', '.', '?', '!', '@',
-    '#', '$', '%', '^', '&', '*', '_', '+', '=', '|', '\\', '<', '>', '/',
-    '\f', '\n', '\r', '\t', '\v')
-  * Control ('\x00' - '\x1f', '\x7f')
-  * Signed ASCII ('\x00' - '\x7f')
-  * ASCII ('\x00' - '\xff')
+  * Numeric: `0` - `9`
+  * Octal: `0` - `7`
+  * Uppercase Hexadecimal: `0` - `9`, `A` - `F`
+  * Lowercase Hexadecimal: `0` - `9`, `a` - `f`
+  * Hexadecimal: `0` - `9`, `a` - `f`, `A` - `F`
+  * Uppercase Alpha: `A` - `Z`
+  * Lowercase Alpha: `a` - `z`
+  * Alpha: `a` - `z`, `A` - `Z`
+  * Alpha-numeric: `0` - `9`, `a` - `z`, `A` - `Z`
+  * Punctuation: `' '`, `'`, `"`, `` ` ``, `,`, `;`, `:`, `~`, `-`, `(`, `)`, `[`, `]`, `{`, `}`, `.`, `?`, `!`
+  * Symbols: `' '`, `'`, `"`, `` ` ``, `,`, `;`, `:`, `~`, `-`, `(`, `)`, `[`, `]`, `{`, `}`, `.`, `?`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `_`, `+`, `=`, `|`, `\`, `<`, `>`, `/`
+  * Space: `' '`, `\f`, `\n`, `\r`, `\t`, `\v`
+  * Visible: `0` - `9`, `a` - `z`, `A` - `Z`, `'`, `"`, `` ` ``, `,`, `;`, `:`, `~`, `-`, `(`, `)`, `[`, `]`, `{`, `}`, `.`, `?`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `_`, `+`, `=`, `|`, `\`, `<`, `>`, `/`
+  * Printable: `0` - `9`, `a` - `z`, `A` - `Z`, `' '`, `'`, `"`, `` ` ``, `,`, `;`, `:`, `~`, `-`, `(`, `)`, `[`, `]`, `{`, `}`, `.`, `?`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, <code>*</code>, <code>_</code>, `+`, `=`, `|`, `\`, `<`, `>`, `/`, `\f`, `\n`, `\r`, `\t`, `\v`
+  * Control: `\x00` - `\x1f`, `\x7f`
+  * Signed ASCII: `\x00` - `\x7f`
+  * ASCII: `\x00` - `\xff`
 
 ## Examples
 
 Determine whether a byte belongs to a character set:
 
-    0x41.alpha?
-    # => true
+```ruby
+0x41.alpha?
+# => true
+```
 
 Determine whether a String belongs to a character set:
 
-    "22e1c0".hex?
-    # => true
-
-Find all sub-strings that belong to a character set within a String:
-
-    ls = File.read('/bin/ls')
-    Chars.printable.strings_in(ls)
-    # => ["/lib64/ld-linux-x86-64.so.2", "KIq/", "5J~!", "%L~!", ...]
+```ruby
+"22e1c0".hex?
+# => true
+```
 
 Return a random character from the set of all characters:
 
-    Chars.all.random_char
-    # => "\x94"
+```ruby
+Chars.all.random_char
+# => "\x94"
+```
 
 Return a random Array of characters from the alpha-numeric character set:
 
-    Chars.alpha_numeric.random_chars(10)
-    # => ["Q", "N", "S", "4", "x", "z", "3", "M", "F", "F"]
+```ruby
+Chars.alpha_numeric.random_chars(10)
+# => ["Q", "N", "S", "4", "x", "z", "3", "M", "F", "F"]
+```
 
 Return a random Array of a random length of unique characters from the
 visible character set:
 
-    Chars.visible.random_distinct_chars(1..10)
-    # => ["S", "l", "o", "8", "'", "q"]
+```ruby
+Chars.visible.random_distinct_chars(1..10)
+# => ["S", "l", "o", "8", "'", "q"]
+```
 
 Return a random String from the set of all characters:
 
-    Chars.all.random_string(10)
-    # => "\xc2h\xad\xccm7\x1e6J\x13"
+```ruby
+Chars.all.random_string(10)
+# => "\xc2h\xad\xccm7\x1e6J\x13"
+```
+
+Generate a secure password:
+
+```ruby
+require 'securerandom'
+Chars.visible.random_string(10..14, random: SecureRandom)
+# => ".*$X=D*XK2h8gC"
+```
 
 Return a random String with a random length between 5 and 10, from the
 set of space characters:
 
-    Chars.space.random_string(5..10)
-    # => "\r\v\n\t\n\f"
+```ruby
+Chars.space.random_string(5..10)
+# => "\r\v\n\t\n\f"
+```
+
+Find all sub-strings that belong to a character set within a String:
+
+```ruby
+ls = File.binread('/bin/ls')
+Chars.printable.substrings(ls)
+# => 
+# ["/lib64/ld-linux-x86-64.so.2",
+#  "_ITM_deregisterTMCloneTable",
+#  "__gmon_start__",
+#  "_ITM_registerTMCloneTable",
+#  ...
+# ]
+```
+
+Find all sub-strings that belong to a character set within a String, with
+indexes:
+
+```ruby
+ls = File.binread('/bin/ls')
+Chars.printable.substrings_with_indexes(ls)
+# =>
+# [["/lib64/ld-linux-x86-64.so.2", 792],
+#  ["_ITM_deregisterTMCloneTable", 4009],
+#  ["__gmon_start__", 4037],
+#  ["_ITM_registerTMCloneTable", 4052],
+#  ...
+# ]
+```
+
+Enumerate over all strings from a character set of a given length:
+
+```ruby
+passwords = Chars.visible.strings_of_length(6)
+passwords.each { |password| puts password }
+# AAAAAA
+# AAAAAB
+# AAAAAC
+# ...
+```
+
+Enumerate over all strings from a character set of lengths between 4 and 8:
+
+```ruby
+passwords = Chars.visible.strings_of_length(4..8)
+passwords.each { |password| puts password }
+# AAAA
+# AAAB
+# AAAC
+# ...
+```
 
 ## Requirements
 
-* [ruby](http://www.ruby-lang.org/) >= 1.8.7
+* [ruby](https://www.ruby-lang.org/) >= 2.0.0
 
 ## Install
 
-    $ sudo gem install chars
+    $ gem install chars
+
+### gemspec
+
+```ruby
+gem.add_dependency 'chars', '~> 0.3'
+```
+
+### Gemfile
+
+```ruby
+gem 'chars', '~> 0.3'
+```
+
+## Crystal
+
+[chars.cr] is a [Crystal] port of this library.
+
+[chars.cr]: https://github.com/postmodern/chars.cr
+[Crystal]: https://crystal-lang.org/
 
 ## License
 

data/Rakefile

@@ -1,36 +1,12 @@
 require 'rubygems'
-require 'rake'
 
-begin
-  gem 'ore-tasks', '~> 0.4'
-  require 'ore/tasks'
+require 'rubygems/tasks'
+Gem::Tasks.new
 
-  Ore::Tasks.new
-rescue LoadError => e
-  STDERR.puts e.message
-  STDERR.puts "Run `gem install ore-tasks` to install 'ore/tasks'."
-end
-
-begin
-  gem 'rspec', '~> 2.4'
-  require 'rspec/core/rake_task'
-
-  RSpec::Core::RakeTask.new
-rescue LoadError => e
-  task :spec do
-    abort "Please run `gem install rspec` to install RSpec."
-  end
-end
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
 task :test => :spec
 task :default => :spec
 
-begin
-  gem 'yard', '~> 0.6.0'
-  require 'yard'
-
-  YARD::Rake::YardocTask.new  
-rescue LoadError => e
-  task :yard do
-    abort "Please run `gem install yard` to install YARD."
-  end
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/benchmarks/compare.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path(File.join(__dir__,'..','lib')))
+
+require 'chars'
+require 'benchmark'
+
+CHARSET = Chars::ALPHA_NUMERIC
+N       = 1_000_000
+STRING  = ('A' * N) + '!'
+ENUM    = (['A', 0x42] * (N / 2)) << '!'
+
+Benchmark.bm(12) do |b|
+  b.report('String')     { CHARSET === STRING }
+  b.report('Enumerable') { CHARSET === ENUM }
+end

data/benchmarks/substrings.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path(File.join(__dir__,'..','lib')))
+
+require 'chars'
+require 'benchmark'
+
+CHARSET = Chars::ALPHA_NUMERIC
+STRING  = File.binread('/usr/bin/openssl')
+
+Benchmark.bm(41) do |b|
+  b.report('Chars::CharSet#each_substring_with_index') do
+    CHARSET.each_substring_with_index(STRING) { |string,index| }
+  end
+
+  b.report('Chars::CharSet#each_substring') do
+    CHARSET.each_substring(STRING) { |string| }
+  end
+
+  (5..20).step(5) do |n|
+    b.report("Chars::CharSet#each_substring (length=#{n})") do
+      CHARSET.strings_in(STRING, :length => n) { |offset,string| }
+    end
+  end
+end

data/chars.gemspec

@@ -2,126 +2,60 @@
 
 require 'yaml'
 
-Gem::Specification.new do |gemspec|
-  files = if File.directory?('.git')
-            `git ls-files`.split($/)
-          elsif File.directory?('.hg')
-            `hg manifest`.split($/)
-          elsif File.directory?('.svn')
-            `svn ls -R`.split($/).select { |path| File.file?(path) }
-          else
-            Dir['{**/}{.*,*}'].select { |path| File.file?(path) }
-          end
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
 
-  filter_files = lambda { |paths|
-    case paths
-    when Array
-      (files & paths)
-    when String
-      (files & Dir[paths])
-    end
-  }
-
-  version = {
-    :file => 'lib/chars/version.rb',
-    :constant => 'Chars::VERSION'
-  }
-
-  defaults = {
-    'name' => File.basename(File.dirname(__FILE__)),
-    'files' => files,
-    'executables' => filter_files['bin/*'].map { |path| File.basename(path) },
-    'test_files' => filter_files['{test/{**/}*_test.rb,spec/{**/}*_spec.rb}'],
-    'extra_doc_files' => filter_files['*.{txt,rdoc,md,markdown,tt,textile}'],
-  }
-
-  metadata = defaults.merge(YAML.load_file('gemspec.yml'))
-
-  gemspec.name = metadata.fetch('name',defaults[:name])
-  gemspec.version = if metadata['version']
-                      metadata['version']
-                    elsif File.file?(version[:file])
-                      require File.join('.',version[:file])
-                      eval(version[:constant])
-                    end
-
-  gemspec.summary = metadata.fetch('summary',metadata['description'])
-  gemspec.description = metadata.fetch('description',metadata['summary'])
-
-  case metadata['license']
-  when Array
-    gemspec.licenses = metadata['license']
-  when String
-    gemspec.license = metadata['license']
-  end
-
-  case metadata['authors']
-  when Array
-    gemspec.authors = metadata['authors']
-  when String
-    gemspec.author = metadata['authors']
-  end
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
 
-  gemspec.email = metadata['email']
-  gemspec.homepage = metadata['homepage']
+                  require 'chars/version'
+                  Chars::VERSION
+                end
 
-  case metadata['require_paths']
-  when Array
-    gemspec.require_paths = metadata['require_paths']
-  when String
-    gemspec.require_path = metadata['require_paths']
-  end
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
 
-  gemspec.files = filter_files[metadata['files']]
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
 
-  gemspec.executables = metadata['executables']
-  gemspec.extensions = metadata['extensions']
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
 
-  if Gem::VERSION < '1.7.'
-    gemspec.default_executable = gemspec.executables.first
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
   end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
 
-  gemspec.test_files = filter_files[metadata['test_files']]
-
-  unless gemspec.files.include?('.document')
-    gemspec.extra_rdoc_files = metadata['extra_doc_files']
-  end
-
-  gemspec.post_install_message = metadata['post_install_message']
-  gemspec.requirements = metadata['requirements']
-
-  if gemspec.respond_to?(:required_ruby_version=)
-    gemspec.required_ruby_version = metadata['required_ruby_version']
-  end
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
 
-  if gemspec.respond_to?(:required_rubygems_version=)
-    gemspec.required_rubygems_version = metadata['required_ruby_version']
-  end
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
 
-  parse_versions = lambda { |versions|
-    case versions
-    when Array
-      versions.map { |v| v.to_s }
-    when String
-      versions.split(/,\s*/)
-    end
-  }
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
 
-  if metadata['dependencies']
-    metadata['dependencies'].each do |name,versions|
-      gemspec.add_dependency(name,parse_versions[versions])  
-    end
-  end
+  split = lambda { |string| string.split(/,\s*/) }
 
-  if metadata['runtime_dependencies']
-    metadata['runtime_dependencies'].each do |name,versions|
-      gemspec.add_runtime_dependency(name,parse_versions[versions])  
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
     end
   end
 
-  if metadata['development_dependencies']
-    metadata['development_dependencies'].each do |name,versions|
-      gemspec.add_development_dependency(name,parse_versions[versions])  
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
     end
   end
 end

data/gemspec.yml

@@ -5,14 +5,18 @@ description:
   recognizing text and generating random text from specific character sets.
 
 license: MIT
-homepage: http://github.com/postmodern/chars
+homepage: https://github.com/postmodern/chars.rb#readme
 authors: Postmodern
 email: postmodern.mod3@gmail.com
 has_yard: true
 
-required_ruby_version: ">= 1.8.7"
+metadata:
+  documentation_uri: https://rubydoc.info/gems/chars
+  source_code_uri:   https://github.com/postmodern/chars.rb
+  bug_tracker_uri:   https://github.com/postmodern/chars.rb/issues
+  changelog_uri:     https://github.com/postmodern/chars.rb/blob/master/ChangeLog.md
+
+required_ruby_version: ">= 2.0.0"
 
 development_dependencies:
-  ore-tasks: ~> 0.4
-  rspec: ~> 2.4
-  yard: ~> 0.6.1
+  bundler: ~> 2.0