collatz 0.0.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac3403918c8be4b788fdfab2ec298d657c29eb05437c01652f9dd91387a61290
-  data.tar.gz: 67c1ad526601163e3356d0b2318710ff9e2b7691696e08c511fe71e029d83d16
+  metadata.gz: 30d4085b4e190a4e1aaf4fdd5f4108abb26688c8223bc1725091d6976b257252
+  data.tar.gz: 3467c2848b02d28909455f092759a8cad3e67eba18583c3873e2bf74c456b11c
 SHA512:
-  metadata.gz: 5987d1636fb13b32ab6f886b4c9223eb747584e43bae7476d5ec69d7ee5515d2d38ff658ccb902690fd87442f6c7ec608c4c02d078feb134a196bd2b43d101fb
-  data.tar.gz: e0ff96c1119cc04ec3cd9c235830436e6b1dabb80b1188b731bd90eee5168d31fb3aedfa136dfdfe3b5e554a0b8afd5c80c9f1c7c81b0727f90ef5c046b01a8b
+  metadata.gz: 9e6d2e859b8cc330406d54989b4a01ee1e83d7e7da1ffad2d66b78eb588aa19e8bcd7b504bd4aeb8320710ae69eb1e2f9d6762a33a5b9b8532a2a91e0190e5f4
+  data.tar.gz: df4b8fa5f25bbc86664ea45d012db4deb07c1197c8addb5fb2f8cb3c22354a89e1612a3b0eb362c8c3bacf2c9b8792a4ba7f746fb40d43ba30066b4aebcd20d8

data/.rubocop.yml

@@ -1,10 +1,9 @@
 AllCops:
   TargetRubyVersion: 2.7.0
   UseCache: false
+  SuggestExtensions: false
   # NewCops: enable # would silence the recommendation
   # # to enable new, but would hide which ones were run
-  # SuggestExtensions: false # would silence the tips
-  # # for recommended suggested gems.
 
 Gemspec/DeprecatedAttributeAssignment:
   Enabled: true
@@ -13,12 +12,16 @@ Gemspec/RequireMFA:
 
 Naming/BlockForwarding:
   Enabled: true
+Naming/MethodParameterName:
+  MinNameLength: 1
 
 Security/CompoundHash:
   Enabled: true
 Security/IoMethods:
   Enabled: true
 
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
 Layout/LineLength:
   Max: 120
 Layout/LineContinuationLeadingSpace:
@@ -27,9 +30,28 @@ Layout/LineContinuationSpacing:
   Enabled: true
 Layout/LineEndStringConcatenationIndentation:
   Enabled: true
+Layout/MultilineHashBraceLayout:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
 Layout/SpaceBeforeBrackets:
   Enabled: true
 
+Metrics/AbcSize:
+  Enabled: false
+Metrics/BlockLength:
+  AllowedMethods: ['describe', 'context']
+Metrics/BlockNesting:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ParameterLists:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+
 Lint/AmbiguousAssignment:
   Enabled: true
 Lint/AmbiguousOperatorPrecedence:
@@ -92,10 +114,15 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+  AllowModifiersOnSymbols: false
 Style/ArgumentsForwarding:
   Enabled: true
 Style/CollectionCompact:
   Enabled: true
+Style/ConditionalAssignment:
+  Enabled: false
 Style/DocumentDynamicEvalDefinition:
   Enabled: true
 Style/EmptyHeredoc:
@@ -110,6 +137,8 @@ Style/FileRead:
   Enabled: true
 Style/FileWrite:
   Enabled: true
+Style/For:
+  Enabled: false
 Style/HashConversion:
   Enabled: true
 Style/HashExcept:
@@ -118,6 +147,8 @@ Style/IfWithBooleanLiteralBranches:
   Enabled: true
 Style/InPatternThen:
   Enabled: true
+Style/Lambda:
+  EnforcedStyle: lambda
 Style/MagicCommentFormat:
   Enabled: true
 Style/MapCompactWithConditionalBlock:
@@ -130,12 +161,16 @@ Style/NegatedIfElseCondition:
   Enabled: true
 Style/NestedFileDirname:
   Enabled: true
+Style/Next:
+  Enabled: false
 Style/NilLambda:
   Enabled: true
 Style/NumberedParameters:
   Enabled: true
 Style/NumberedParametersLimit:
   Enabled: true
+Style/NumericLiterals:
+  Enabled: false
 Style/ObjectThen:
   Enabled: true
 Style/OpenStructUse:
@@ -146,6 +181,8 @@ Style/RedundantArgument:
   Enabled: true
 Style/RedundantInitialize:
   Enabled: true
+Style/RedundantSelf:
+  Enabled: false
 Style/RedundantSelfAssignmentBranch:
   Enabled: true
 Style/SelectByRegexp:

data/Gemfile

@@ -7,6 +7,8 @@ gemspec
 
 gem "rake", "~> 13.0"
 
+gem "rdoc", "~> 6.0"
+
 gem "rspec", "~> 3.0"
 
 gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    collatz (0.0.4)
+    collatz (1.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -12,8 +12,12 @@ GEM
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
+    psych (4.0.5)
+      stringio
     rainbow (3.1.1)
     rake (13.0.6)
+    rdoc (6.4.0)
+      psych (>= 4.0.0)
     regexp_parser (2.5.0)
     rexml (3.2.5)
     rspec (3.11.0)
@@ -42,6 +46,7 @@ GEM
     rubocop-ast (1.21.0)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
+    stringio (3.0.2)
     unicode-display_width (2.2.0)
 
 PLATFORMS
@@ -50,6 +55,7 @@ PLATFORMS
 DEPENDENCIES
   collatz!
   rake (~> 13.0)
+  rdoc (~> 6.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
 

data/Makefile

@@ -1,4 +1,4 @@
-.PHONY: setup setup_github clean test build install push_rubygems push_github
+.PHONY: setup setup_github clean docs test build install push_rubygems push_github
 SHELL:=/bin/bash
 
 # Assumes `gem install bundler`
@@ -10,11 +10,17 @@ setup_github:
 
 clean:
 	bundle exec rake clean
+	bundle exec rake clobber
 	rm -f collatz-*.gem
 	rm -f pkg/collatz-*.gem
 
+docs: clean
+	bundle exec rake rdoc
+
+# default (just `rake`) is spec + rubocop, but be pedantic in case this changes.
 test: clean
-	bundle exec rake
+	bundle exec rake spec
+	bundle exec rake rubocop
 
 # We can choose from `gem build collatz.gemspec` or `bundle exec rake build`.
 # The gem build command creates a ./collatz-$VER.gem file, and the rake build

data/README.md

@@ -1,20 +1,37 @@
 # [Collatz](https://github.com/Skenvy/Collatz): [Ruby](https://github.com/Skenvy/Collatz/tree/main/ruby) 🔻💎🔻
 Functions related to [the Collatz/Syracuse/3N+1 problem](https://en.wikipedia.org/wiki/Collatz_conjecture), implemented in [Ruby](https://www.ruby-lang.org/).
 ## Getting Started
-[To install the latest from RubyGems](https://rubygems.org/); ([empty search results for collatz](https://rubygems.org/search?query=collatz))
+[To install the latest from RubyGems](https://rubygems.org/gems/collatz);
 ```sh
 gem install collatz
 ```
+[Or to install from GitHub's hosted gems](https://github.com/Skenvy/Collatz/packages/1636643);
+```sh
+gem install collatz --source "https://rubygems.pkg.github.com/skenvy"
+```
+### Add to the Gemfile
+[Add the RubyGems hosted gem](https://rubygems.org/gems/collatz);
+```ruby
+gem "collatz", ">= 0.1.0
+```
+[Add the GitHub hosted gem](https://github.com/Skenvy/Collatz/packages/1636643);
+```ruby
+source "https://rubygems.pkg.github.com/skenvy" do
+  gem "collatz", ">= 0.1.0"
+end
+```
 ## Usage
 Provides the basic functionality to interact with the Collatz conjecture.
 The parameterisation uses the same `(P,a,b)` notation as Conway's generalisations.
 Besides the function and reverse function, there is also functionality to retrieve the hailstone sequence, the "stopping time"/"total stopping time", or tree-graph. 
 The only restriction placed on parameters is that both `P` and `a` can't be `0`.
-## [<lang-docs-name> generated docs](https://skenvy.github.io/Collatz/ruby)
+## [RDoc generated docs](https://skenvy.github.io/Collatz/ruby)
 ## Developing
 ### The first time setup
 ```sh
-git clone https://github.com/Skenvy/Collatz.git && cd Collatz/ruby && <localised-setup-command>
+git clone https://github.com/Skenvy/Collatz.git && cd Collatz/ruby && make setup
 ```
 ### Iterative development
-* <list-worthwhile-recipes>
+The majority of `make` recipes for this are just wrapping a `bundle` invocation of `rake`.
+* `make docs` will recreate the RDoc docs
+* `make test` will run both the RSpec tests and the RuboCop linter.

data/Rakefile

@@ -10,3 +10,26 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+# The below recommended way to add rdoc to rake from rdoc's site has a lot of
+# things it will compain about, and wont work OotB, so use 'rdoc/task' below.
+# require 'rdoc/rdoc'
+# options = RDoc::Options.new
+# # see RDoc::Options
+# options.rdoc_include << ["lib/*.rb"]
+# rdoc = RDoc::RDoc.new
+# rdoc.document options
+# # see RDoc::RDoc
+
+# https://ruby.github.io/rdoc/RDocTask.html
+# doc is the default output location of the rdoc binary, and is the location
+# added in the standard ruby gitignore, but the rake task defaults to ./html
+# and we need to use the rdoc_dir option to change it to doc.
+
+require "rdoc/task"
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.main = "README.md" # !? README.rdoc ?!
+  rdoc.rdoc_files.include("README.md", "lib/*.rb", "lib/collatz/*.rb")
+end

data/collatz.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   Besides the function and reverse function, there is also functionality to retrieve
   the hailstone sequence, the \"stopping time\"/\"total stopping time\", or tree-graph.
   The only restriction placed on parameters is that both P and a can't be 0."
-  spec.homepage = "https://github.com/Skenvy/Collatz/tree/main/ruby"
+  spec.homepage = "https://skenvy.github.io/Collatz/ruby/"
   spec.required_ruby_version = ">= 2.7.0"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/Skenvy/Collatz/tree/main/ruby"

data/devlog.md

@@ -53,3 +53,88 @@ While the [GitHub: Working with the RubyGems registry](https://docs.github.com/e
 :github: Bearer <PAT|TOKEN>
 ```
 We can `base64 ~/.gem/credentials` the rubygems_api_key we got from the `gem signin`, add the string (without the newlines) to our github secrets, and then do something like `echo -n "$RUBYGEMS_API_KEY_BASE64" | base64 --decode > ~/.gem/credentials` to recreate the credentials. GitHub's credentials should be passable with a `echo -e "---\n:github: Bearer <PAT|TOKEN>" > ~/.gem/credentials`.
+
+With that now merged we can work on adding the functionality and setting up documentation. The two main choices for documentation generation appear to be [rdoc](https://github.com/ruby/rdoc) or [yard](https://yardoc.org/). Yard looks alright, but we're trying to stick to any "official" way of doing something, and with rdoc being put out by ruby, we'll start off with rdoc. We can [`bundle add rdoc --version "~> 6.0" --verbose`](https://bundler.io/man/bundle-add.1.html), but doing this just leads to it permanently hanging on a ""HTTP GET https://index.rubygems.org/versions" immediately after a "HTTP 416 Range Not Satisfiable https://index.rubygems.org/versions". There's quite a few hits for this or similar issues cropping up, but none with a definitive answer or cause, and none that worked to fix the issue here. It took a 20 minute wait for it to finally do anything, then kept asking for my sudo password and refusing to accept it. I retried and it succeeded much quicker, although still took 4 entries of my password to get it to successfully pass and hit that "Bundle complete! 5 Gemfile dependencies, 23 gems now installed". Following the [rdoc](https://github.com/ruby/rdoc) guide to add rdoc to the rakefile leads to a ``rake aborted! NoMethodError: undefined method `delete_if' for nil:NilClass`` which could be connected to [this issue](https://github.com/ruby/rdoc/issues/352), namely ["You haven't told RDoc to document any files"](https://github.com/ruby/rdoc/issues/352#issuecomment-110185993). We can avoid this issue if we use the [rdoc task](https://ruby.github.io/rdoc/RDocTask.html) instead.
+
+As we start to add the first few lines to the main rb file, we've run into yet another rubocop yelling about something inconsequential (Style/NumericLiterals isn't even listed in our rubocop yaml, so we'll have to add it to disable it);
+```
+lib/collatz.rb:19:20: C: [Correctable] Style/NumericLiterals: Use underscores(_) as thousands separator and separate every 3 digits with them.
+VERIFIED_MAXIMUM = 295147905179352825856
+                   ^^^^^^^^^^^^^^^^^^^^^
+```
+We'll also have to add the cop `Naming/MethodParameterName: MinNameLength: 1` to stop it from complaining about all our uses of `"P"`, `"a"`, and `"b"`. Also worth mentioning is that, unlike other implementations, in ruby we can't use a capital letter to start a non-constant value, so we have to swap all capital `"P"` for lowercase `"p"`'s, lest we get the `"Formal argument cannot be a constant"` error. I'm also cautious of `Style/RedundantReturn` -- I'd like to try and stick to the normal ruby style, but it relies on the novel awareness that the last line of a function without an explicit return is returned. I'll have to simply remember that for later. Another cop is complaining about `Lint/AmbiguousOperatorPrecedence: Wrap expressions with varying precedence with parentheses to avoid ambiguity.`, which seems absurd. After fixing some of these, my line `if n%p == 0 then n/p else ((a*n)+b) end` is still generating the following errors;
+```
+lib/collatz.rb:96:3: C: [Correctable] Style/OneLineConditional: Favor the ternary operator (?:) or multi-line constructs over single-line if/then/else/end constructs.
+  if n%p == 0 then n/p else ((a*n)+b) end
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+lib/collatz.rb:96:6: C: [Correctable] Style/NumericPredicate: Use (n%p).zero? instead of n%p == 0.
+  if n%p == 0 then n/p else ((a*n)+b) end
+     ^^^^^^^^
+```
+Rubocop is happy if we replace it with `(n%p).zero? ? (n/p) : ((a*n)+b)`, which feels so much less readable, and absurd than anyone would consider that more "readable" than the verbose `if/then/else/end`. Another odd ambiguity is that an error can be raised either with `raise StandardError, 'message'` or `raise StandardError.new('message')` or `raise StandardError.new 'message'`, but the `Style/RaiseArgs` cop has a preference for `raise StandardError, 'message'`. Now we just have to configure the `Metrics/BlockLength` cop which doesn't like all the lines in the spec test. A good suggestion is to set `IgnoredMethods: ['describe', 'context']` according to the docs, which does silence the error, but now returns ``Warning: obsolete parameter `IgnoredMethods` (for `Metrics/BlockLength`) found in .rubocop.yml `IgnoredMethods` has been renamed to `AllowedMethods` and/or `AllowedPatterns`.``. So why are they not mentioned as such on the [rubocop docs](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsblocklength). It feels like a lot of the problems we've run into so far with ruby have been the same as those with go, where it's been historically developed at a pace greater than which it is then adopted, leading to a fragmented ecosystem, although not as badly as it is in go, with solutions to circumvent the at times antithetical expectations easier to find than they were for go. Although a large portion of these issues have been with rubocop. It might be useful, but it adds a lot of noise that needs to be hushed while trying to learn ruby for the first time, even if its suggestions might be temporarily useful. I will say though that setting up the gem deployment was much easier than the maven deployment for java, so all in all it's not too much of a hassle.
+
+The last thing worth mentioning before trying to release 0.1.0 with the function and reverse function, is that there seems to be a bit of a difference in how to provide "kwargs" than in python. In python kwargs are listed as `some_arg_name = some_default_value`, and can then be referenced by name in the function invocation, or supplied positionally, and without specifying a `**kwargs` to splatter additionl inputs, any name supplied that is not specified as an input will cause an error. In ruby, kwargs are listed as `some_arg_name: some_default_value`, and like python, an error will be thrown if a named kwarg is provided on invocation that isn't specified in the function inputs, however it **can only** be supplied to the invocation per its keyword name, it can't be supplied positionally. Meanwhile, "optional" args in ruby that are specified in the function inputs via `some_arg_name = some_default_value` aren't kwargs, but rather positional args that happen to have default values; they can't be supplied to a function invocation by name, only by position, and a quirk of testing how to assign them to learn the difference between ruby and python demonstrates that while specifying `**kwargs` to splatter inputs in python means parameters can be supplied to the invocation by name that weren't specified in the input, attempting to see how "optional args" affect splattering in ruby leads to a false positive of demonstrating something akin to, but not exactly splattering. That is, if some `some_other_arg_name = some_other_value` is supplied to a function invocation in ruby as the input to an "optional arg", this is not splatting the differently named inputs, rather, it is assigning the value to the name as a variable, and providing that value as the input to the positional optional args. So to achieve true "kwargs" in ruby, we need to use `some_arg_name: some_default_value`, and specify them by name in the invocations.
+
+We're now ready to add once again create an empty orphan branch;
+1. `git checkout --orphan gh-pages-ruby`
+1. `rm .git/index ; git clean -fdx`
+1. `git commit -m "Initial empty orphan" --allow-empty`
+1. `git push --set-upstream origin gh-pages-ruby`
+
+Well, v0.1.0 has been released, with the function and reverse function. The ruby discord has been very helpful, and has a "Community: code review" channel dedicated for requests for feedback on code samples, so I've asked on there for a review, and gotten some feedback! I want to try and make it more ruby-esque before working on the hailstone and tree graph functions, so that they are made right from the start. The feedback is as thus;
+1. It's odd to have all the code in the central `~/collatz.rb` file with a separate `~/collatz/version.rb`, with the suggestion seeming to be to either do away with having a subfolder that contains `example.rb` files that are then included in the main file via `require_relative "collatz/example"`, or move all the contents of the main file into other `*.rb` files that are then required into the main file. The version file was part of what was auto generated by bundler, and I like having the version on its own in its own file, as it makes setting the version file, and reading the version from it in the workflow, much easier.
+1. The next piece of feedback, and something I wondered why bundler didn't do from the beginning honestly, is to put _**everything**_ inside a `Collatz` module. I assumed when I first saw that this wasn't done automatically by bundler that the contents of a gem that would then be required into a script would set up the namespace similar to python, and disregarded the fact that it appeared not to do that while setting up the RSpec tests. So moving everything into a top level module to unclobber the "public"`?` namespace.
+1. Change `unless p != 0` to `if p.zero?`. I vaguely recall trying something along the lines of inline conditionals when first setting that up, and thought a rubocop had complained about it _not_ being an "unless" clause, but it might have been some other part of the inlining of the conditional, so will definitely try this change, as it certainly is much more readable.
+1. In the `reverse_function` rather than do a `pre_values +=`, use the array's `.push` method. Although another user suggest using `<<` instead? It was finally suggested to instead just settle for a multi line if, which isn't _not_ a reasonable suggestion, even if my preference happens to be for flatter lines. It was also made apparent that similar to the `.zero?` function, there is a `.nonzero?` function that can be used instead of the negated assertion of `.zero?`.
+1. Instead of setting methods to private with `private :stopping_time_terminus` following the method declaration, simply add `private` before the def (e.g. `private def stopping_time_terminus`). A few sites indicated the same concern another user noted that doing so would make all the methods declared after it also private, however this concern was dissuaded with the assurance that it would not behave that way, instead asserting that the `def something` would return a `Symbol`, which would make `private def something` the same as subsequently passing the symbol of the method to the private modifier.
+1. The abuse of `NotImplementedError`, which is meant to be ruby internal only, was mentioned. I was aware of this ahead of time, and probably could have done without adding the function headers before implementing them.
+1. On the `KNOWN_CYCLES`, rather than apply the `.freeze` to all elements in the list individually, set `.each(&:freeze).freeze` on the final outer closing bracket `]` of the whole list.
+
+I've fixed most of the above, although some aren't operable at the moment. Setting methods private via `private def method_name` instead of `private :method_name` after the method declaration is causing rubocop to break. I'll get an error message `An error occurred while Style/AccessModifierDeclarations cop was inspecting /mnt/c/Workspaces/GitHub_Skenvy/Collatz/ruby/lib/collatz.rb:71:0.` for both lines, which is then followed by this stack trace.
+```
+uninitialized constant RuboCop::Version::Server
+Did you mean?  TCPServer
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/version.rb:22:in `version'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:82:in `display_error_summary'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:58:in `display_summary'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:27:in `block in execute_runner'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:52:in `with_redirect'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:25:in `execute_runner'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:17:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command.rb:11:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/environment.rb:18:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli.rb:72:in `run_command'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli.rb:79:in `execute_runners'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli.rb:48:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/rake_task.rb:51:in `run_cli'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/rake_task.rb:26:in `block (2 levels) in initialize'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/file_utils_ext.rb:58:in `verbose'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/rake_task.rb:24:in `block in initialize'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:281:in `block in execute'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:281:in `each'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:281:in `execute'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:219:in `block in invoke_with_call_chain'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:199:in `synchronize'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:199:in `invoke_with_call_chain'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:188:in `invoke'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:160:in `invoke_task'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:116:in `block (2 levels) in top_level'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:116:in `each'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:116:in `block in top_level'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:125:in `run_with_threads'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:110:in `top_level'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:83:in `block in run'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:186:in `standard_exception_handling'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:80:in `run'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/exe/rake:27:in `<top (required)>'
+/usr/local/bin/rake:23:in `load'
+/usr/local/bin/rake:23:in `<main>'
+RuboCop failed!
+```
+It appears though that this error may have already had a bug raised and fixed at [rubocop/issues/10994](https://github.com/rubocop/rubocop/issues/10994). It appears in the meantime however that the `Style/AccessModifierDeclarations` cop isn't working as intended. Setting the below does not cause it to error on the `private :method_name` after the method declaration, which is what `AllowModifiersOnSymbols: false` is supposed to disallow.
+```yaml
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+  AllowModifiersOnSymbols: false
+```
+Even though it is not causing it to throw a cop error on the modifier on symbol pattern `private :method_name`, having the above config _is_ preventing it from throwing the hard error above `uninitialized constant RuboCop::Version::Server` that stopped the whole rubocop process, and indeed it passes with `no offenses detected`.

data/lib/collatz/constants.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Collatz
+  # The four known cycles for the standard parameterisation.
+  KNOWN_CYCLES = [
+    [1, 4, 2], [-1, -2], [-5, -14, -7, -20, -10],
+    [-17, -50, -25, -74, -37, -110, -55, -164, -82, -41, -122, -61, -182, -91, -272, -136, -68, -34]
+  ].each(&:freeze).freeze
+  # The current value up to which the standard parameterisation has been verified.
+  VERIFIED_MAXIMUM = 295147905179352825856
+  # The current value down to which the standard parameterisation has been verified.
+  VERIFIED_MINIMUM = -272 # TODO: Check the actual lowest bound.
+end

data/lib/collatz/function.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "utilities"
+
+module Collatz # rubocop:disable Style/Documentation
+  module_function # rubocop:disable Style/AccessModifierDeclarations
+
+  # Handles the sanity check for the parameterisation (p,a,b)
+  # required by both the function and reverse function.
+  #
+  # @raise FailedSaneParameterCheck If p or a are 0.
+  #
+  # @param +Integer+ p Modulus used to devide n, iff n is equivalent to (0 mod p)
+  #
+  # @param +Integer+ a Factor by which to multiply n.
+  #
+  # @param +Integer+ b Value to add to the scaled value of n.
+  private def assert_sane_parameterisation(p, a, _b) # :nodoc:
+    # Sanity check (p,a,b) ~ p absolutely can't be 0. a "could" be zero
+    # theoretically, although would violate the reversability (if ~a is 0 then a
+    # value of "b" as the input to the reverse function would have a pre-emptive
+    # value of every number not divisible by p). The function doesn't _have_ to
+    # be reversable, but we are only interested in dealing with the class of
+    # functions that exhibit behaviour consistant with the collatz function. If
+    # _every_ input not divisable by p went straight to "b", it would simply
+    # cause a cycle consisting of "b" and every b/p^z that is an integer. While
+    # p in [-1, 1] could also be a reasonable check, as it makes every value
+    # either a 1 or 2 length cycle, it's not strictly an illegal operation.
+    # "b" being zero would cause behaviour not consistant with the collatz
+    # function, but would not violate the reversability, so no check either.
+    # " != 0" is redundant for python assertions.
+    raise FailedSaneParameterCheck, SaneParameterErrMsg::SANE_PARAMS_P if p.zero?
+    raise FailedSaneParameterCheck, SaneParameterErrMsg::SANE_PARAMS_A if a.zero?
+  end
+
+  # Returns the output of a single application of a Collatz-esque function.
+  #
+  # @raise FailedSaneParameterCheck If p or a are 0.
+  #
+  # @param +Integer+ *n:* The value on which to perform the Collatz-esque function.
+  #
+  # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+  #
+  # @param +Integer+ *a:* Factor by which to multiply n.
+  #
+  # @param +Integer+ *b:* Value to add to the scaled value of n.
+  #
+  # @return +Integer+ The result of the function
+  def function(n, p: 2, a: 3, b: 1)
+    assert_sane_parameterisation(p, a, b)
+    (n%p).zero? ? (n/p) : ((a*n)+b)
+  end
+
+  # Returns the output of a single application of a Collatz-esque reverse function. If
+  # only one value is returned, it is the value that would be divided by p. If two values
+  # are returned, the first is the value that would be divided by p, and the second value
+  # is that which would undergo the multiply and add step, regardless of which is larger.
+  #
+  # @raise FailedSaneParameterCheck If p or a are 0.
+  #
+  # @param +Integer+ *n:* The value on which to perform the reverse Collatz function.
+  #
+  # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+  #
+  # @param +Integer+ *a:* Factor by which to multiply n.
+  #
+  # @param +Integer+ *b:* Value to add to the scaled value of n.
+  #
+  # @return +List<Integer>+ The values that would return the input if given to the function.
+  def reverse_function(n, p: 2, a: 3, b: 1)
+    assert_sane_parameterisation(p, a, b)
+    if ((n-b)%a).zero? && ((n-b)%(p*a)).nonzero?
+      [p*n, (n-b)/a]
+    else
+      [p*n]
+    end
+  end
+end

data/lib/collatz/hailstone_sequence.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "utilities"
+require_relative "function"
+
+module Collatz # rubocop:disable Style/Documentation
+  # Contains the results of computing a hailstone sequence via hailstone_sequence(~).
+  class HailstoneSequence
+    # The set of values that comprise the hailstone sequence.
+    attr_reader :values
+
+    # A terminal condition that reflects the final state of the hailstone sequencing,
+    # whether than be that it succeeded at determining the stopping time, the total
+    # stopping time, found a cycle, or got stuck on zero (or surpassed the max total).
+    attr_reader :terminal_condition # SequenceState
+
+    # A status value that has different meanings depending on what the terminal condition
+    # was. If the sequence completed either via reaching the stopping or total stopping time,
+    # or getting stuck on zero, then this value is the stopping/terminal time. If the sequence
+    # got stuck on a cycle, then this value is the cycle length. If the sequencing passes the
+    # maximum stopping time then this is the value that was provided as that maximum.
+    attr_reader :terminal_status
+
+    # Initialise and compute a new Hailstone Sequence.
+    #
+    # @raise FailedSaneParameterCheck If p or a are 0.
+    #
+    # @param +Integer+ initial_value The value to begin the hailstone sequence from.
+    #
+    # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+    #
+    # @param +Integer+ *a:* Factor by which to multiply n.
+    #
+    # @param +Integer+ *b:* Value to add to the scaled value of n.
+    #
+    # @param +Integer+ *max_total_stopping_time:* Maximum amount of times to iterate the function, if 1 is not reached.
+    #
+    # @param +Boolean+ *total_stopping_time:* Whether or not to execute until the "total" stopping time
+    # (number of iterations to obtain 1) rather than the regular stopping time (number
+    # of iterations to reach a value less than the initial value).
+    #
+    # @return HailstoneSequence An initialised, and computed, hailstone sequence
+    def initialize(initial_value, p, a, b, max_total_stopping_time, total_stopping_time)
+      terminate = stopping_time_terminus(initial_value, total_stopping_time)
+      if initial_value.zero?
+        # 0 is always an immediate stop.
+        @values = [0]
+        @terminal_condition = SequenceState::ZERO_STOP
+        @terminal_status = 0
+      elsif initial_value == 1
+        # 1 is always an immediate stop, with 0 stopping time.
+        @values = [1]
+        @terminal_condition = SequenceState::TOTAL_STOPPING_TIME
+        @terminal_status = 0
+      else
+        # Otherwise, hail!
+        min_max_total_stopping_time = [max_total_stopping_time, 1].max
+        pre_values = Array.new(min_max_total_stopping_time+1)
+        pre_values[0] = initial_value
+        for k in 1..min_max_total_stopping_time do
+          next_value = Collatz.function(pre_values[k-1], p: p, a: a, b: b)
+          # Check if the next_value hailstone is either the stopping time, total
+          # stopping time, the same as the initial value, or stuck at zero.
+          if terminate.call(next_value)
+            pre_values[k] = next_value
+            if next_value == 1
+              @terminal_condition = SequenceState::TOTAL_STOPPING_TIME
+            else
+              @terminal_condition = SequenceState::STOPPING_TIME
+            end
+            @terminal_status = k
+            @values = pre_values.slice(0, k+1)
+            return
+          end
+          if pre_values.include? next_value
+            pre_values[k] = next_value
+            cycle_init = 1
+            for j in 1..k do
+              if pre_values[k-j] == next_value
+                cycle_init = j
+                break
+              end
+            end
+            @terminal_condition = SequenceState::CYCLE_LENGTH
+            @terminal_status = cycle_init
+            @values = pre_values.slice(0, k+1)
+            return
+          end
+          if next_value.zero?
+            pre_values[k] = 0
+            @terminal_condition = SequenceState::ZERO_STOP
+            @terminal_status = -k
+            @values = pre_values.slice(0, k+1)
+            return
+          end
+          pre_values[k] = next_value
+        end
+        @terminal_condition = SequenceState::MAX_STOP_OUT_OF_BOUNDS
+        @terminal_status = min_max_total_stopping_time
+        @values = pre_values
+      end
+    end
+
+    # Provides the appropriate lambda to use to check if iterations on an initial
+    # value have reached either the stopping time, or total stopping time.
+    #
+    # @param +Integer+ *n:* The initial value to confirm against a stopping time check.
+    #
+    # @param +Boolean+ *total_stop:* If false, the lambda will confirm that iterations of n
+    # have reached the oriented stopping time to reach a value closer to 0.
+    # If true, the lambda will simply check equality to 1.
+    #
+    # @return +lambda<Integer>:<Boolean>+ The lambda to check for the stopping time.
+    private def stopping_time_terminus(n, total_stop)
+      if total_stop
+        lambda { |x| x == 1 }
+      elsif n >= 0
+        lambda { |x| (x < n && x.positive?) }
+      else
+        lambda { |x| (x > n && x.negative?) }
+      end
+    end
+  end
+
+  # Returns a list of successive values obtained by iterating a Collatz-esque
+  # function, until either 1 is reached, or the total amount of iterations
+  # exceeds max_total_stopping_time, unless total_stopping_time is False,
+  # which will terminate the hailstone at the "stopping time" value, i.e. the
+  # first value less than the initial value. While the sequence has the
+  # capability to determine that it has encountered a cycle, the cycle from "1"
+  # wont be attempted or reported as part of a cycle, regardless of default or
+  # custom parameterisation, as "1" is considered a "total stop".
+  #
+  # @raise FailedSaneParameterCheck If p or a are 0.
+  #
+  # @param +Integer+ *initial_value:* The value to begin the hailstone sequence from.
+  #
+  # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+  #
+  # @param +Integer+ *a:* Factor by which to multiply n.
+  #
+  # @param +Integer+ *b:* Value to add to the scaled value of n.
+  #
+  # @param +Integer+ *max_total_stopping_time:* Maximum amount of times to iterate the function, if 1 is not reached.
+  #
+  # @param +Boolean+ *total_stopping_time:* Whether or not to execute until the "total" stopping time
+  # (number of iterations to obtain 1) rather than the regular stopping time (number
+  # of iterations to reach a value less than the initial value).
+  #
+  # @return HailstoneSequence A set of values that form the hailstone sequence.
+  module_function def hailstone_sequence(initial_value, p: 2, a: 3, b: 1, max_total_stopping_time: 1000, total_stopping_time: true) # rubocop:disable Layout/LineLength
+    # Prior to starting the hailstone, which has some magic case handling,
+    # call the function to trigger any assert_sane_parameterisation flags.
+    _throwaway = function(initial_value, p: p, a: a, b: b)
+    # Return the hailstone sequence.
+    HailstoneSequence.new(initial_value, p, a, b, max_total_stopping_time, total_stopping_time)
+  end
+
+  # Returns the stopping time, the amount of iterations required to reach a
+  # value less than the initial value, or nil if max_stopping_time is exceeded.
+  # Alternatively, if total_stopping_time is true, then it will instead count
+  # the amount of iterations to reach 1. If the sequence does not stop, but
+  # instead ends in a cycle, the result will be infinity.
+  # If (p,a,b) are such that it is possible to get stuck on zero, the result
+  # will be the negative of what would otherwise be the "total stopping time"
+  # to reach 1, where 0 is considered a "total stop" that should not occur as
+  # it does form a cycle of length 1.
+  #
+  # @raise FailedSaneParameterCheck If p or a are 0.
+  #
+  # @param +Integer+ *initial_value:* The value for which to find the stopping time.
+  #
+  # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+  #
+  # @param +Integer+ *a:* Factor by which to multiply n.
+  #
+  # @param +Integer+ *b:* Value to add to the scaled value of n.
+  #
+  # @param +Integer+ *max_stopping_time:* Maximum amount of times to iterate the function, if
+  # the stopping time is not reached. IF the max_stopping_time is reached,
+  # the function will return nil.
+  #
+  # @param +Boolean+ *total_stopping_time:* Whether or not to execute until the "total" stopping
+  # time (number of iterations to obtain 1) rather than the regular stopping
+  # time (number of iterations to reach a value less than the initial value).
+  #
+  # @return +Integer+ The stopping time, or, in a special case, infinity, nil or a negative.
+  module_function def stopping_time(initial_value, p: 2, a: 3, b: 1, max_stopping_time: 1000, total_stopping_time: false) # rubocop:disable Layout/LineLength
+    # Although the "max_~_time" for hailstones is named for "total stopping" time
+    # and the "max_~_time" for this "stopping time" function is _not_ "total",
+    # they are handled the same way, as the default for "total_stopping_time"
+    # for hailstones is true, but for this, is false. Thus the naming difference.
+    # rubocop:disable Layout/HashAlignment
+    hail = hailstone_sequence(initial_value, p: p, a: a, b: b,
+                              max_total_stopping_time: max_stopping_time,
+                              total_stopping_time: total_stopping_time)
+    # rubocop:enable Layout/HashAlignment
+    # For total/regular/zero stopping time, the value is already the same as
+    # that present, for cycles we report infinity instead of the cycle length,
+    # and for max stop out of bounds, we report None instead of the max stop cap
+    { SequenceState::TOTAL_STOPPING_TIME => hail.terminal_status,
+      SequenceState::STOPPING_TIME => hail.terminal_status,
+      SequenceState::CYCLE_LENGTH => Float::INFINITY,
+      SequenceState::ZERO_STOP => hail.terminal_status,
+      SequenceState::MAX_STOP_OUT_OF_BOUNDS => nil
+    }.fetch(hail.terminal_condition, nil)
+  end
+end

data/lib/collatz/tree_graph.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "utilities"
+require_relative "function"
+
+module Collatz # rubocop:disable Style/Documentation
+  # Nodes that form a "tree graph", structured as a tree, with their own node's value,
+  # as well as references to either possible child node, where a node can only ever have
+  # two children, as there are only ever two reverse values. Also records any possible
+  # "terminal sequence state", whether that be that the "orbit distance" has been reached,
+  # as an "out of bounds" stop, which is the regularly expected terminal state. Other
+  # terminal states possible however include the cycle state and cycle length (end) states.
+  class TreeGraphNode
+    # The value of this node in the tree.
+    attr_reader :node_value
+
+    # The terminal SequenceState; nil if not a terminal node, MAX_STOP_OUT_OF_BOUNDS if the max_orbit_distance
+    # has been reached, CYCLE_LENGTH if the node's value is found to have occured previously, or
+    # CYCLE_INIT, retroactively applied when a CYCLE_LENGTH state node is found.
+    attr_accessor :terminal_sequence_state
+
+    # The "Pre N/P" TreeGraphNode child of this node that
+    # is always present if this is not a terminal node.
+    attr_reader :pre_n_div_p_node
+
+    # The "Pre aN+b" TreeGraphNode child of this node that is
+    # present if it exists and this is not a terminal node.
+    attr_reader :pre_an_plus_b_node
+
+    # Create an instance of TreeGraphNode which will yield its entire sub-tree of all child nodes.
+    #
+    # @raise FailedSaneParameterCheck If p or a are 0.
+    #
+    # @param +Integer+ *node_value:* The value for which to find the tree graph node reversal.
+    #
+    # @param +Integer+ *max_orbit_distance:* The maximum distance/orbit/branch length to travel.
+    #
+    # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+    #
+    # @param +Integer+ *a:* Factor by which to multiply n.
+    #
+    # @param +Integer+ *b:* Value to add to the scaled value of n.
+    #
+    # @param +Hash<Integer>+ *cycle_check:* A hash used to keep track of already graphed values
+    #
+    # @param +Boolean+ *create_raw:* Used to instruct the initialiser method to take 1:1 inputs, used in testing.
+    #
+    # @param SequenceState *terminal_sequence_state:*
+    #
+    # @param TreeGraphNode *pre_n_div_p_node:*
+    #
+    # @param TreeGraphNode *pre_an_plus_b_node:*
+    #
+    # @return [TreeGraphNode] A computed tree graph node
+    def initialize(node_value, max_orbit_distance, p, a, b, cycle_check: nil, create_raw: false,
+                   terminal_sequence_state: nil, pre_n_div_p_node: nil, pre_an_plus_b_node: nil)
+      @node_value = node_value
+      if create_raw
+        @terminal_sequence_state = terminal_sequence_state
+        @pre_n_div_p_node = pre_n_div_p_node
+        @pre_an_plus_b_node = pre_an_plus_b_node
+        return
+      end
+      # Handle cycle prevention for recursive calls
+      if cycle_check.nil?
+        cycle_check = { @node_value => self }
+      elsif !cycle_check[@node_value].nil?
+        # The value already exists in the cycle so this is a cyclic terminal
+        cycle_check[@node_value].terminal_sequence_state = SequenceState::CYCLE_INIT
+        @terminal_sequence_state = SequenceState::CYCLE_LENGTH
+        @pre_n_div_p_node = nil
+        @pre_an_plus_b_node = nil
+        return
+      else
+        cycle_check[@node_value] = self
+      end
+      if [0, max_orbit_distance].max.zero?
+        @terminal_sequence_state = SequenceState::MAX_STOP_OUT_OF_BOUNDS
+        @pre_n_div_p_node = nil
+        @pre_an_plus_b_node = nil
+      else
+        reverses = Collatz.reverse_function(node_value, p: p, a: a, b: b)
+        @pre_n_div_p_node = TreeGraphNode.new(reverses[0], max_orbit_distance-1, p, a, b, cycle_check: cycle_check)
+        if reverses.length == 2
+          @pre_an_plus_b_node = TreeGraphNode.new(reverses[1], max_orbit_distance-1, p, a, b, cycle_check: cycle_check)
+        else
+          @pre_an_plus_b_node = nil
+        end
+      end
+    end
+
+    # This will only confirm an equality if the whole subtree of both nodes, including
+    # node values, sequence states, and child nodes, checked recursively, are equal.
+    #
+    # @param TreeGraphNode *tgn:* The TreeGraphNode with which to compare equality.
+    #
+    # @return +Boolean+ true, if the entire sub-trees are equal.
+    def sub_tree_equals(tgn)
+      return false if self.node_value != tgn.node_value
+      return false if self.terminal_sequence_state != tgn.terminal_sequence_state
+      return false if self.pre_n_div_p_node.nil? && !tgn.pre_n_div_p_node.nil?
+      return false if !self.pre_n_div_p_node.nil? && !self.pre_n_div_p_node.sub_tree_equals(tgn.pre_n_div_p_node)
+      return false if self.pre_an_plus_b_node.nil? && !tgn.pre_an_plus_b_node.nil?
+      return false if !self.pre_an_plus_b_node.nil? && !self.pre_an_plus_b_node.sub_tree_equals(tgn.pre_an_plus_b_node)
+      true
+    end
+  end
+
+  # Contains the results of computing the Tree Graph via tree_graph(~).
+  # Contains the root node of a tree of TreeGraphNode's.
+  class TreeGraph
+    # The root node of the tree of TreeGraphNode's.
+    attr_reader :root
+
+    # Create a new TreeGraph with the root node defined by the inputs.
+    #
+    # @raise FailedSaneParameterCheck If p or a are 0.
+    #
+    # @param +Integer+ *node_value:* The value for which to find the tree graph node reversal.
+    #
+    # @param +Integer+ *max_orbit_distance:* The maximum distance/orbit/branch length to travel.
+    #
+    # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+    #
+    # @param +Integer+ *a:* Factor by which to multiply n.
+    #
+    # @param +Integer+ *b:* Value to add to the scaled value of n.
+    #
+    # @param +Boolean+ *create_raw:* Used to instruct the initialiser method to take 1:1 inputs, used in testing.
+    #
+    # @param TreeGraphNode *root:* A node that will be set to the root of this tree
+    #
+    # @return [TreeGraph] A tree graph, with a computed root node.
+    def initialize(node_value, max_orbit_distance, p, a, b, create_raw: false, root: nil)
+      if create_raw && !root.nil?
+        @root = root
+      else
+        @root = TreeGraphNode.new(node_value, max_orbit_distance, p, a, b)
+      end
+    end
+
+    # The equality between TreeGraph's is determined by the equality check on
+    # subtrees. A subtree check will be done on both TreeGraph's root nodes.
+    #
+    # @param TreeGraph
+    #
+    # @return +Boolean+ true, if both are TreeGraph, with the entire root's sub-trees being equal.
+    def ==(other)
+      # Generic checks
+      return false if other.nil?
+      return false unless other.is_a?(self.class)
+      # Actual check
+      self.root.sub_tree_equals(other.root)
+    end
+  end
+
+  # Returns a directed tree graph of the reverse function values up to a maximum
+  # nesting of max_orbit_distance, with the initial_value as the root.
+  #
+  # @raise FailedSaneParameterCheck If p or a are 0.
+  #
+  # @param +Integer+ *initial_value:* The root value of the directed tree graph.
+  #
+  # @param +Integer+ *max_orbit_distance:* Maximum amount of times to iterate the reverse
+  # function. There is no natural termination to populating the tree graph, equivalent
+  # to the termination of hailstone sequences or stopping time attempts, so this is not
+  # an optional argument like max_stopping_time / max_total_stopping_time, as it is the
+  # intended target of orbits to obtain, rather than a limit to avoid uncapped computation.
+  #
+  # @param +Integer+ *p:* Modulus used to devide n, iff n is equivalent to (0 mod p).
+  #
+  # @param +Integer+ *a:* Factor by which to multiply n.
+  #
+  # @param +Integer+ *b:* Value to add to the scaled value of n.
+  #
+  # @return TreeGraph The branches of the tree graph as determined by the reverse function.
+  module_function def tree_graph(initial_value, max_orbit_distance, p: 2, a: 3, b: 1)
+    # Prior to starting the tree graph, which has some magic case handling, call
+    # the reverse_function to trigger any assert_sane_parameterisation flags.
+    _throwaway = reverse_function(initial_value, p: p, a: a, b: b)
+    TreeGraph.new(initial_value, max_orbit_distance, p, a, b)
+  end
+end

data/lib/collatz/utilities.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Collatz
+  # Error message constants, to be used as input to the FailedSaneParameterCheck.
+  module SaneParameterErrMsg
+    # Message to print in the FailedSaneParameterCheck if p, the modulus, is zero.
+    SANE_PARAMS_P = "'p' should not be 0 ~ violates modulo being non-zero."
+    # Message to print in the FailedSaneParameterCheck if a, the multiplicand, is zero.
+    SANE_PARAMS_A = "'a' should not be 0 ~ violates the reversability."
+  end
+
+  # SequenceState for Cycle Control: Descriptive flags to indicate when some event occurs in the
+  # hailstone sequences or tree graph reversal, when set to verbose, or stopping time check.
+  module SequenceState
+    # A Hailstone sequence state that indicates the stopping
+    # time, a value less than the initial, has been reached.
+    STOPPING_TIME = "STOPPING_TIME"
+    # A Hailstone sequence state that indicates the total
+    # stopping time, a value of 1, has been reached.
+    TOTAL_STOPPING_TIME = "TOTAL_STOPPING_TIME"
+    # A Hailstone and TreeGraph sequence state that indicates the
+    # first occurence of a value that subsequently forms a cycle.
+    CYCLE_INIT = "CYCLE_INIT"
+    # A Hailstone and TreeGraph sequence state that indicates the
+    # last occurence of a value that has already formed a cycle.
+    CYCLE_LENGTH = "CYCLE_LENGTH"
+    # A Hailstone and TreeGraph sequence state that indicates the sequence
+    # or traversal has executed some imposed 'maximum' amount of times.
+    MAX_STOP_OUT_OF_BOUNDS = "MAX_STOP_OUT_OF_BOUNDS"
+    # A Hailstone sequence state that indicates the sequence terminated
+    # by reaching "0", a special type of "stopping time".
+    ZERO_STOP = "ZERO_STOP"
+  end
+
+  # Thrown when either p, the modulus, or a, the multiplicand, are zero.
+  class FailedSaneParameterCheck < StandardError
+    # Construct a FailedSaneParameterCheck with a message associated with the provided enum.
+    # @param [String] msg One of the SaneParameterErrMsg strings.
+    def initialize(msg = "This is a custom exception", exception_type = "FailedSaneParameterCheck")
+      @exception_type = exception_type
+      super(msg)
+    end
+  end
+end

data/lib/collatz/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Collatz
-  VERSION = "0.0.4"
+  # The current semver version.
+  VERSION = "1.0.0"
 end

data/lib/collatz.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
 require_relative "collatz/version"
+require_relative "collatz/constants"
+require_relative "collatz/utilities"
+require_relative "collatz/function"
+require_relative "collatz/hailstone_sequence"
+require_relative "collatz/tree_graph"
 
+# Provides the basic functionality to interact with the Collatz conjecture. The
+# parameterisation uses the same (p,a,b) notation as Conway's generalisations.
+# Besides the function and reverse function, there is also functionality to
+# retrieve the hailstone sequence, the "stopping time"/"total stopping time", or
+# tree-graph.
 module Collatz
-  class Error < StandardError; end
-  # Your code goes here...
+  # Using a module to proctor a namespace for the functions, none of which
+  # are instance methods. All are "class" methods, so set module_function
+  # at the head of each required file which opens this module and has defs.
+  # https://github.com/rubocop/ruby-style-guide#modules-vs-classes
+  # rubocop:disable Lint/UselessAccessModifier
+
+  module_function # rubocop:disable Style/AccessModifierDeclarations
+
+  # rubocop:enable Lint/UselessAccessModifier
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: collatz
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Nathan Levett
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-14 00:00:00.000000000 Z
+date: 2022-09-24 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Provides the basic functionality to interact with the Collatz conjecture.
@@ -34,15 +34,19 @@ files:
 - collatz.gemspec
 - devlog.md
 - lib/collatz.rb
+- lib/collatz/constants.rb
+- lib/collatz/function.rb
+- lib/collatz/hailstone_sequence.rb
+- lib/collatz/tree_graph.rb
+- lib/collatz/utilities.rb
 - lib/collatz/version.rb
-- sig/collatz.rbs
-homepage: https://github.com/Skenvy/Collatz/tree/main/ruby
+homepage: https://skenvy.github.io/Collatz/ruby/
 licenses:
 - Apache-2.0
 metadata:
-  homepage_uri: https://github.com/Skenvy/Collatz/tree/main/ruby
+  homepage_uri: https://skenvy.github.io/Collatz/ruby/
   source_code_uri: https://github.com/Skenvy/Collatz/tree/main/ruby
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -58,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.6
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Functions Related to the Collatz/Syracuse/3n+1 Problem
 test_files: []

data/sig/collatz.rbs

@@ -1,4 +0,0 @@
-module Collatz
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end