RubyGems - faker_maker - Versions diffs - 3.0.0 → 4.0.0 - Mend

faker_maker 3.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6d677fff1380c1eddf6c0305b978d8b161d0f5fbb5e1752bc587a0dc10e8554
-  data.tar.gz: 7df7f5f9279c2e745842999117672e608b9d1e2302d63bcae9914429f796491a
+  metadata.gz: 4f341f27ec954b732dde7141c9ad532346c09dadbbed4ea469894b10cac652f8
+  data.tar.gz: 61919d74b140d82fba2750bcf0e1c25473ebe21e02a2b213bd1109d94f22d9e2
 SHA512:
-  metadata.gz: fe8ae2a8550b5eaf9a78eaf2bda1ab8f7f1eac1f1f557223e744111bf45ee417c5a9215aa1cd2dae5e23d90a1b3b9aa347a2bba52a5d97d7d8f53f91fd629196
-  data.tar.gz: 19290557db759839023a0a7b80b9cd2bf9f01e652a7e610f5f5cfd9f037459f2be04cc51a34eed271dead74289f9001fd15aebbf8913355e55c5004a7b466f31
+  metadata.gz: de3ae09ed6b848612d3fc23533d04f4633eaa4be42f7f7be9fc3f3938f8b86afa2a495f6928a66f38207d63233e2b37ce88897178688a4f3aa2c6c5f524b51e4
+  data.tar.gz: cdc3c4509819316bc389d2bf1857883ddfa62b14b93a8f794a043af70bd603dec46f7e0a0c37d29d8814ff447ac2762cd3d56a92fc917338bc3458b4113263c9

data/.github/workflows/ruby.yml CHANGED Viewed

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ["3.0", "3.1", "3.2", "3.3", "3.4"]
+        ruby-version: ["3.4", "4.0"]
     steps:
       - uses: actions/checkout@v3

data/.gitignore CHANGED Viewed

@@ -8,6 +8,10 @@
 /tmp/
 Gemfile.lock
+/hack/
+TODO.md
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml CHANGED Viewed

@@ -52,4 +52,5 @@ Metrics/PerceivedComplexity:
   Max: 10
 AllCops:
+  TargetRubyVersion: 4.0
   NewCops: enable

data/Gemfile CHANGED Viewed

@@ -10,3 +10,5 @@ gemspec
 gem 'bundler-audit', '~> 0.9.2'
 gem 'irb', '~> 1.15'
 gem 'rdoc', '~> 6.13'
+gem 'awesome_print', '~> 1.9'

data/MIGRATION_NOTES.md ADDED Viewed

@@ -0,0 +1,47 @@
+# Jekyll to Jackdaw Migration Notes
+## 1. Project Initialization
+* Run `jackdaw new <project_name>` to generate the standard directory structure:
+  * `site/src`: Content
+  * `site/templates`: ERB Templates
+  * `site/assets`: Static files (images, css, favicons)
+## 2. Template Conversion
+* **Layouts**: Consolidate Jekyll layouts (default, page, etc.) into `site/templates/layout.html.erb`.
+  * Replace `{{ content }}` with `<%= content %>`.
+  * Replace `{{ page.title }}` with `<%= title %>`.
+* **Partials**: Convert `{% include file.html %}` to `<%= render 'file' %>`.
+  * Rename partial files to start with an underscore (e.g., `_nav.html.erb`).
+* **Assets**:
+  * Move CSS/JS/Images to `site/assets/`.
+  * **Important**: When referencing in HTML, omit `assets/`.
+    * `site/assets/styles.css` -> `<link href="/styles.css">`
+    * `site/assets/img/logo.png` -> `<img src="/img/logo.png">`
+## 3. Content Migration Strategies
+* **File Extensions**:
+  * Regular pages: `.md` -> `.page.md`
+  * Blog posts: `.md` -> `.blog.md` (Filename must start with `YYYY-MM-DD-`)
+* **Frontmatter Handling**:
+  * Jackdaw renders the *first H1* as the page title.
+  * **Task**: Strip YAML frontmatter (`--- ... ---`) and ensure the file starts with `# Page Title`.
+* **Directory Structure**:
+  * Keep the same folder structure in `site/src` to maintain URLs.
+  * **Conflict Warning**: Do not create `topic.page.md` if you also have a folder named `topic/`. Instead, create `topic/index.page.md`.
+## 4. Automation (Ruby Script)
+For bulk migration of documentation, use a script to:
+1. Iterate through source directories.
+2. Read file content.
+3. specific YAML frontmatter values (Title).
+4. Rewrite file to destination with new header and `.page.md` extension.
+## 5. Navigation & Indices
+* Jackdaw does not automatically build navigation menus from folder structure.
+* **Manual**: Edit `site/templates/_nav.html.erb`.
+* **Auto-generated Indices**: Write scripts to generate index markdown files (e.g., "List of all Rules") if the content changes frequently.
+## 6. Styling
+* Jackdaw provides no default styling.
+* Create a robust `styles.css` using CSS Variables for theming.
+* Link fonts and stylesheets in the `<head>` of `layout.html.erb`.

data/TODO.md ADDED Viewed

@@ -0,0 +1,16 @@
+-- DONE - sorta
+2. get attributes including embedded attr -- THIS WORKS IF USING THE FACTORY PARAMETER, NOT PROC EMBEDDED FACTORIES -- NEED A CHANGE TO OSL FACTORIES
+3. What the hell is going on with @embedded factories -- why is this always nil  CHECK -- FOR THE LOVE OF GOD, WRITE DOCUMENTATION FOR THIS
+4. Factory#attribute_names line ~ 110
+-- TODO
+1. nested builds using the build method -- this is hidden at the moment, it sets the value of the key to a hash rather than recursively calling the field#field method
+5. FM[:foo].build( attributes: { does_not_exist: 1 }, raise_on_error: false ) # RAISE_ON_ERROR
+5. FM[:foo].build( attributes: { does_not_exist: 1 }, strict: false ) # RAISE_ON_ERROR
+5. FM[:foo].build( attributes: { does_not_exist: 1 }, very_strict: false ) # RAISE_ON_ERROR
+building embedded factories need to know the build options passed in to the top level build call -- e.g. is chaos on or not
+check naming strategies still work

data/faker_maker.gemspec CHANGED Viewed

@@ -43,7 +43,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'activesupport', '>= 5.2', '< 9'
-  spec.add_development_dependency 'bundler',       '~> 2'
+  spec.add_development_dependency 'bundler',       '>= 2'
   spec.add_development_dependency 'faker',         '~> 3.2'
   spec.add_development_dependency 'guard',         '~> 2.16'
   spec.add_development_dependency 'guard-bundler', '~> 3.0'

data/hack/nested.rb ADDED Viewed

@@ -0,0 +1,21 @@
+require 'faker_maker'
+require 'awesome_print'
+FM.factory :random do
+  flavour { 'blue' }
+end
+FM.factory :item do
+  name { 'toothpaste' }
+  price { 0.99 }
+end
+FM.factory :coupon do
+  discount { 0.10 }
+end
+FM.factory :basket do
+  items( factory: %i[item random] )
+end
+# { a: 1, b: { x: 2 } }

data/lib/faker_maker/attribute.rb CHANGED Viewed

@@ -3,7 +3,7 @@
 module FakerMaker
   # Attributes describe the fields of classes
   class Attribute
-    attr_reader :name, :block, :translation, :required, :optional, :optional_weighting, :embedded_factories
+    attr_reader :name, :block, :translation, :required, :optional, :optional_weighting
     DEFAULT_OPTIONAL_WEIGHTING = 0.5
@@ -25,6 +25,15 @@ module FakerMaker
       end
     end
+    # Return an array of factory instances
+    def embedded_factories
+      @embedded_factories.map { |name| FakerMaker[name] }
+    end
+    def embedded_factories?
+      @embedded_factories.any?
+    end
     def array?
       forced_array? || @array
     end

data/lib/faker_maker/base.rb CHANGED Viewed

@@ -3,12 +3,12 @@
 module FakerMaker
   # Base module for defining the DSL
   module Base
-    def factory(name, options = {}, &block)
+    def factory(name, options = {}, &)
       factory = FakerMaker.find_factory(name)
       if factory.nil?
         factory = FakerMaker::Factory.new name, options
         proxy = DefinitionProxy.new factory
-        proxy.instance_eval( &block ) if block_given?
+        proxy.instance_eval( & ) if block_given?
         FakerMaker.register_factory factory
       else
         factory

data/lib/faker_maker/definition_proxy.rb CHANGED Viewed

@@ -13,8 +13,8 @@ module FakerMaker
       @factory
     end
-    def method_missing(name, *args, &block)
-      attribute = FakerMaker::Attribute.new name, block, *args
+    def method_missing(name, *, &block)
+      attribute = FakerMaker::Attribute.new(name, block, *)
       @factory.attach_attribute attribute
     end

data/lib/faker_maker/factory.rb CHANGED Viewed

@@ -5,8 +5,26 @@ module FakerMaker
   # Factories construct instances of a fake
   class Factory
     include Auditable
     attr_reader :name, :class_name, :parent, :chaos_selected_attributes
+    # Create a new +Factory+ object.
+    #
+    # This method does not automatically register the factory,see
+    # FakerMaker#register_factory
+    #
+    # Options:
+    # - +:class_name+ - override the default class name that FakerMaker will generate.
+    #   This is useful in the case of collisions with existing classes or keywords.
+    # - +:parent+ - the parent factory from which this factory inherits attributes.
+    #   Instances built by this factory will have a class which inherits from the parent's
+    #   class.
+    # - +:naming+ - one of:
+    #   - +nil+ (default) - use field names as the method name and in JSON conversion
+    #   - +:json+ - use field names as the method name but convert when rendering JSON, e.g.
+    #     +hello_world+ becomes +helloWorld+
+    #   - +:json_capitalised+ (or +:json_capitalized+) - as +:json+ but with the first letter
+    #     captialised, e.g. +hello_world+ becomes +HelloWorld+
     def initialize( name, options = {} )
       assert_valid_options options
       @name = name.respond_to?(:to_sym) ? name.to_sym : name.to_s.underscore.to_sym
@@ -26,6 +44,7 @@ module FakerMaker
       @parent = options[:parent]
     end
+    # Get the Class of the parent for this factory
     def parent_class
       if @parent
         FakerMaker::Factory.const_get( FakerMaker[@parent].class_name )
@@ -34,6 +53,7 @@ module FakerMaker
       end
     end
+    # Attach a FakerMaker::Attribute to this Factory
     def attach_attribute( attribute )
       @attributes << attribute
     end
@@ -42,14 +62,11 @@ module FakerMaker
       @instance ||= instantiate
     end
-    def build( attributes: {}, chaos: false, **kwargs )
-      if kwargs.present?
-        validate_deprecated_build(kwargs)
-        attributes = kwargs
-      end
+    def build( attributes: {}, chaos: false )
       @instance = nil
       before_build if respond_to? :before_build
+      # TODO: make this cleverer to handle nested attributes
       assert_only_known_attributes_for_override( attributes )
       assert_chaos_options chaos if chaos
@@ -57,13 +74,19 @@ module FakerMaker
       optional_attributes
       required_attributes
-      populate_instance instance, attributes, chaos
+      populate_instance(instance, attributes, chaos:)
       yield instance if block_given?
       after_build if respond_to? :after_build
       audit(@instance) if FakerMaker.configuration.audit?
       instance
     end
+    # Construct a Class object which will become the parent type of objects built
+    # by this factory.
+    #
+    # The Class object will be created and the attributes added to it. The returned value
+    # is a Ruby Class which can be instantiated.
     def assemble
       if @klass.nil?
         @klass = Class.new parent_class
@@ -91,7 +114,7 @@ module FakerMaker
       unless @json_key_map
         @json_key_map = {}.with_indifferent_access
         @json_key_map.merge!( FakerMaker[parent].json_key_map ) if parent?
-        attributes.each_with_object( @json_key_map ) do |attr, map|
+        attributes(include_embeddings: false).each_with_object( @json_key_map ) do |attr, map|
           key = if attr.translation?
                   attr.translation
                 elsif @naming_strategy
@@ -106,29 +129,88 @@ module FakerMaker
       @json_key_map
     end
-    def attribute_names( collection = [] )
-      collection |= FakerMaker[parent].attribute_names( collection ) if parent?
-      collection | @attributes.map( &:name )
+    # Returns a transformed list of attribute names from the `attributes` array.
+    # For each item in the array:
+    # - If the item is a Hash, recursively transforms its keys and values,
+    #   replacing keys with their `name` and applying the same transformation to values.
+    # - Otherwise, replaces the item with its `name`.
+    #
+    # @return [Array] An array (possibly nested) of attribute names, with hashes' keys replaced by their `name`.
+    def attribute_names
+      transform = lambda do |arr|
+        arr.map do |item|
+          if item.is_a?(Hash)
+            item.transform_keys(&:name).transform_values { |v| transform.call(v) }
+          else
+            item.name
+          end
+        end
+      end
+      transform.call(attributes)
     end
-    def attributes( collection = [] )
+    # Returns a collection of attributes for the factory, optionally including embedded factory attributes.
+    #
+    # @param collection [Array] an optional array of attributes to start with (default: empty array)
+    # @param include_embeddings [Boolean] whether to include attributes from embedded factories (default: true)
+    # @return [Array] the collection of attributes, possibly including embedded factory attributes as hashes
+    #
+    # If the factory has a parent, its attributes are merged in. Attributes without embedded factories are added
+    # directly. If `include_embeddings` is true, attributes with embedded factories are added as hashes mapping
+    # the attribute to the flattened attributes of its embedded factories. If false, only the attribute itself
+    # is added.
+    def attributes( collection = [], include_embeddings: true )
       collection |= FakerMaker[parent].attributes( collection ) if parent?
-      collection | @attributes
+      collection |= @attributes.reject { |attr| attr.embedded_factories.any? }
+      # if there is an embedded factory(-ies) and we are including the embedded factory's
+      # fields, we are going to return a hash
+      if include_embeddings
+        @attributes.select { |attr| attr.embedded_factories.any? }.each do |attr|
+          collection << { attr => attr.embedded_factories.flat_map(&:attributes) }
+        end
+      # if there is an embedded factory(-ies) and we are not including the embedded factory's
+      # fields, just add the attribute into the set of returned fields
+      else
+        collection |= @attributes.select { |attr| attr.embedded_factories.any? }
+      end
+      collection
     end
+    # Finds and returns the first attribute matching the given name.
+    #
+    # This method searches through the attributes (excluding embeddings) and returns the first attribute
+    # whose name, translation, or the result of applying the naming strategy to its name matches the provided `name`.
+    #
+    # @param name [String] The name to search for among the attributes. Defaults to an empty string.
+    # @return [Object, nil] The first matching attribute object, or nil if no match is found.
     def find_attribute( name = '' )
-      attributes.filter { |a| [a.name, a.translation, @naming_strategy&.name(a.name)].include? name }.first
+      attributes(include_embeddings: false).filter do |a|
+        [a.name, a.translation, @naming_strategy&.name(a.name)].include? name
+      end.first
     end
     protected
-    def populate_instance( instance, attr_override_values, chaos )
-      FakerMaker[parent].populate_instance instance, attr_override_values, chaos if parent?
+    # Populates the given instance with attribute values, optionally applying chaos/randomization.
+    #
+    # @param instance [Object] The object instance to populate with attribute values.
+    # @param attr_override_values [Hash] A hash of attribute names and their override values.
+    # @param chaos [Boolean, Integer, nil] If truthy, enables chaos mode which may randomize or select a subset
+    # of attributes.
+    # @return [void]
+    #
+    # If the factory has a parent, its attributes are populated first.
+    # Each attribute is assigned a value, either from the override values or generated.
+    # The factory instance is set on the populated object for reference.
+    def populate_instance( instance, attr_override_values, chaos: false )
+      FakerMaker[parent].populate_instance(instance, attr_override_values, chaos:) if parent?
       attributes = chaos ? chaos_select(chaos) : @attributes
       attributes.each do |attribute|
-        value = value_for_attribute( instance, attribute, attr_override_values )
+        value = value_for_attribute( instance, attribute, attr_override_values, chaos: )
         instance.send "#{attribute.name}=", value
       end
       instance.instance_variable_set( :@fm_factory, self )
@@ -137,7 +219,10 @@ module FakerMaker
     private
     def assert_only_known_attributes_for_override( attr_override_values )
-      unknown_attrs = attr_override_values.keys - attribute_names
+      unknown_attrs = attr_override_values.keys - attribute_names.flat_map do |item|
+        item.is_a?(Hash) ? item.keys : item
+      end
       issue = "Can't build an instance of '#{class_name}' " \
               "setting '#{unknown_attrs.join( ', ' )}', no such attribute(s)"
       raise FakerMaker::NoSuchAttributeError, issue unless unknown_attrs.empty?
@@ -156,34 +241,44 @@ module FakerMaker
       raise FakerMaker::ChaosConflictingAttributeError, issue unless conflicting_attributes.empty?
     end
-    def attribute_hash_overridden_value?( attr, attr_override_values )
+    def overridden_value?( attr, attr_override_values )
       attr_override_values.keys.include?( attr.name )
     end
-    def value_for_attribute( instance, attr, attr_override_values )
-      if attribute_hash_overridden_value?( attr, attr_override_values )
+    def value_for_attribute( instance, attr, attr_override_values, chaos: false )
+      if !attr.embedded_factories? && overridden_value?( attr, attr_override_values )
         attr_override_values[attr.name]
       elsif attr.array?
         [].tap do |a|
           attr.cardinality.times do
-            manufacture = manufacture_from_embedded_factory( attr )
-            # if manufacture has been build and there is a block, instance_exec the block
+            manufacture = manufacture_from_embedded_factory( attr, attr_override_values[attr.name.to_sym], chaos: )
+            # if manufacture has been built and there is a block, instance_exec the block
             # otherwise just add the manufacture to the array
             a << (attr.block ? instance.instance_exec(manufacture, &attr.block) : manufacture)
           end
         end
       else
-        manufacture = manufacture_from_embedded_factory( attr )
+        manufacture = manufacture_from_embedded_factory( attr, attr_override_values[attr.name.to_sym], chaos: )
         attr.block ? instance.instance_exec(manufacture, &attr.block) : manufacture
       end
     end
-    def manufacture_from_embedded_factory( attr )
+    def manufacture_from_embedded_factory( attr, attributes = {}, chaos: false )
+      attributes ||= {}
       # The name of the embedded factory randomly selected from the list of embedded factories.
-      embedded_factory_name = attr.embedded_factories.sample
+      embedded_factory = attr.embedded_factories.sample
+      # filter out attributes for non-chosen embedded factories to avoid triggering
+      # the NoSuchAttribute exception
+      attributes = attr
+                   .embedded_factories
+                   .reject { |e| e == embedded_factory }
+                   .flat_map { |f| pp f.attributes.map(&:name) }
+                   .then { |excl| attributes.delete_if { |k, _v| excl.include?(k) } }
       # The object that is being manufactured by the factory.
       # If an embedded factory name is provided, it builds the object using FakerMaker.
-      embedded_factory_name ? FakerMaker[embedded_factory_name].build : nil
+      embedded_factory&.build(attributes:, chaos:)
     end
     def instantiate
@@ -264,13 +359,6 @@ module FakerMaker
                                 .concat(selected_attrs).uniq!
       @chaos_selected_attributes
     end
-    def validate_deprecated_build(kwargs)
-      usage = kwargs.each_with_object([]) { |kwarg, result| result << "#{kwarg.first}: #{kwarg.last}" }.join(', ')
-      warn "[DEPRECATION] `FM[:#{name}].build(#{usage})` is deprecated. " \
-           "Please use `FM[:#{name}].build(attributes: { #{usage} })` instead."
-    end
   end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/faker_maker/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module FakerMaker
-  VERSION = '3.0.0'
+  VERSION = '4.0.0'
 end

data/usefakermaker.com/pages/about/index.md ADDED Viewed

@@ -0,0 +1,20 @@
+---
+title: "About"
+layout: single
+permalink: /pages/about/
+author_profile: true
+---
+Faker Maker was designed to be a trivial way to create data factories that could throw JSON payloads at an API endpoint. It has grown well beyond that original purpose but still remains a thing for building things that give you data.
+It is much beloved by me. Although it's a personal project, it's used extensively by my employer and influenced by the needs of my colleagues. I hope it will be useful to you as well. I am very open to ideas, feedback and contributions.
+Faker Maker is licenced under the [MIT licence](https://raw.githubusercontent.com/BillyRuffian/faker_maker/refs/heads/master/LICENSE.txt). Do with it what you will and have fun.
+### What's the Billy Ruffian thing?
+HMS Bellerophon was a 74-gun third-rate ship of the line of the Royal Navy. Launched in 1786, she served during the French Revolutionary and Napoleonic Wars, mostly on blockades or convoy escort duties. She fought in three fleet actions: the Glorious First of June, the Battle of the Nile and the Battle of Trafalgar. She became famous as the ship upon which Napoleon surrendered and which transported him into exile in 1815.
+Her sailors, not being educated in the Classics, struggled to pronounce her name and so she became known as the Billy Ruffian and her crew as the "Billy Ruffians". The name stuck and was used as a nickname for the ship for the rest of her career.
+Since no one in coffee shops can spell my name, I adopted 'Billy' which turned into 'Billy Ruffian'. It's also a bloody good story.

data/usefakermaker.com.site/.gitignore ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ public/
2	+ .DS_Store

data/usefakermaker.com.site/site/assets/favicons/android-chrome-192x192.png ADDED Viewed

Binary file

data/usefakermaker.com.site/site/assets/favicons/android-chrome-512x512.png ADDED Viewed

Binary file

data/usefakermaker.com.site/site/assets/favicons/apple-touch-icon.png ADDED Viewed

Binary file

data/usefakermaker.com.site/site/assets/favicons/favicon-16x16.png ADDED Viewed

Binary file

data/usefakermaker.com.site/site/assets/favicons/favicon-32x32.png ADDED Viewed

Binary file

data/usefakermaker.com.site/site/assets/favicons/favicon.ico ADDED Viewed

Binary file

data/usefakermaker.com.site/site/assets/favicons/site.webmanifest ADDED Viewed

@@ -0,0 +1,19 @@
+{
+    "name": "FakerMaker",
+    "short_name": "FakerMaker",
+    "icons": [
+       {
+          "src": "/favicons/android-chrome-192x192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+       },
+       {
+        "src": "/favicons/android-chrome-512x512.png",
+        "sizes": "512x512",
+        "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "display": "standalone"
+ }

data/usefakermaker.com.site/site/assets/robots.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ User-agent: *
2	+ Allow: /