freyia 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d18d6f5e341842b0cd67728fdbec92ac6525b02878806f3b91b1ec60dbcf664b
-  data.tar.gz: c5c1b224a6894a51a5a2b3ddd95fa4b6ac766273a5c57445243e659bf003a3c3
+  metadata.gz: 9ae683b60c6522f6af8b51b15e78a0cf656c6eb6030762a41e6c68c2490468c0
+  data.tar.gz: 66e517e9380662a71abaa0c89e1655a2b165802fb133dc93f29dcf09102e0738
 SHA512:
-  metadata.gz: 042d8ddfa2963c03cd7b52df4b9a7ef1fc77cad9e5e7e671d3dd3a223f7bb5ff94f65af8b9197329cd3c31205b743745caf4d172659d485480459bd4b9873b4c
-  data.tar.gz: 2a6974c2881e98b4580a175be710567a4a5b82468620f3758a910817d7d746a73e4783d2a1b5e436d300cf7c047d075c595dd8ccd04eeb05b99d6d31daf3dde0
+  metadata.gz: 16089e296d6588fc4d622fef87d272bf03e760e23042deac1868942ae0740eb9d82317172b6abf7b01943eca3156ac5202bb7c9dfd0daf859e8a6c61d74178f9
+  data.tar.gz: 8a1bead727f8f79ac8470935a76a4e21492928e4d6a92786b176aaa7dd51ead9d961dcf4b3d1ff2d44beec52352f14fdc6dc4be7a183d7942411b1f408196ac0

data/CHANGELOG.md

@@ -1,5 +1,16 @@
+# Changelog
+
 ## [Unreleased]
 
+.
+
+## [0.6.0] - 2025-12-14
+
+- Add support for Serbea-based templates (alternative to ERB)
+- Refactor all `params = {}` to real keyword arguments
+- Handle ANSI codes in columnar calculations (for `print_table`)
+- Use yarddoc syntax for all doc comments
+
 ## [0.5.3] - 2025-11-21
 
 - Fix syntax error

data/README.md

@@ -15,6 +15,10 @@ bundle add freyia
 
 ## Usage
 
+Freyia is centered around the idea of running an "automation script". This is kicked off using a base instance, but that instance can incorporate other automation scripts using `apply` and those scripts don't need to include any of the typical Ruby class ceremony (everything in those scripts are run as if it were written to execute in the base instance via the magic of `instance_exec`).
+
+An example using the standard Freya base:
+
 ```ruby
 class TestAutomation < Freyia::Base
   def call(external_file)
@@ -42,13 +46,49 @@ end
 
 class MyLatestAutomation < MyAutomationSuperclass
   def call
-    # ...automation statements here
+    # ...automation script here
   end
 end
 ```
 
 Note that the use of `call` here is simply a convention…you can write automations in any method or architecture you prefer.
 
+> [!NOTE]
+> Freyia file automations are generally in line with prior Thor actions, but one big difference: the template extension is now `.tmpl`, not `.tt`. In addition, we are phasing out "reversable actions". Automations are generally understood to be run on Git-backed repos which offer their own form of reverting changes.
+
+Most of the Freyia documentation as at the [API level which you can read here](https://www.rubydoc.info/gems/freyia). Most important resources:
+
+* [Freyia::Automations](https://www.rubydoc.info/gems/freyia/Freyia/Automations)
+* [Freyia::Shell::Basic](https://www.rubydoc.info/gems/freyia/Freyia/Shell/Basic)
+
+All of the automations listed there, such as `say_status`, `inject_into_file`, `template`, etc. are available to you within automation scripts.
+
+## Template Types
+
+The `template` automation lets you create files based on templates you define in either ERB or [Serbea](https://www.serbea.dev) syntax. The default is ERB, but you override the default for a Freyia base using the `template_type` class method:
+
+```ruby
+class TestAutomation < Freyia::Base
+  template_type :serbea
+end
+```
+
+You can also override the base default on a per-call basis using the `type` keyword argument:
+
+```ruby
+template "configuration.yaml", type: :serbea
+```
+
+This would process a `configuration.yaml.tmpl` in your source folder to output a `configuration.yaml` file to the destination, like so:
+
+```yaml
+---
+current_ruby_version: {{ RUBY_VERSION | to_json }}
+```
+
+> [!NOTE]
+> Freyia doesn't ship with a Serbea dependency, so you will also need to `bundle add serbea` or reference it in a `.gemspec` file if you want to use Serbea-based templates.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/freyia/automations/create_file.rb

@@ -7,42 +7,36 @@ module Freyia
     # Create a new file relative to the destination root with the given data,
     # which is the return value of a block or a data string.
     #
-    # ==== Parameters
-    # destination<String>:: the relative path to the destination root.
-    # data<String|NilClass>:: the data to append to the file.
-    # config<Hash>:: give :verbose => false to not log the status.
-    #
-    # ==== Examples
+    # @param destination [String] the relative path to the destination root.
+    # @param data [String|NilClass] the data to append to the file.
+    # @param config [Hash] give `verbose: false` to not log the status.
     #
+    # @example Creating a file using a block
     #   create_file "lib/fun_party.rb" do
     #     hostname = ask("What is the virtual hostname I should use?")
     #     "vhost.name = #{hostname}"
     #   end
     #
+    # @example Creating a file using a string
     #   create_file "config/apache.conf", "your apache config"
-    #
-    def create_file(destination, *args, &block)
-      config = args.last.is_a?(Hash) ? args.pop : {}
-      data = args.first
-      CreateFile.new(self, destination, block || data.to_s, config).()
+    def create_file(destination, data = nil, **config, &block)
+      CreateFile.new(self, destination, block || data.to_s, **config).()
     end
     alias_method :add_file, :create_file
 
     # CreateFile is a subset of Template, which instead of rendering a file with
     # ERB, it gets the content from the user.
-    #
-    class CreateFile < EmptyDirectory #:nodoc:
+    class CreateFile < EmptyDirectory
       attr_reader :data
 
-      def initialize(base, destination, data, config = {})
+      def initialize(base, destination, data, **config)
         @data = data
-        super(base, destination, config)
+        super(base, destination, **config)
       end
 
       # Checks if the content of the file at the destination is identical to the rendered result.
       #
-      # ==== Returns
-      # Boolean:: true if it is identical, false otherwise.
+      # @return [Boolean] true if it is identical, false otherwise.
       #
       def identical?
         # binread uses ASCII-8BIT, so to avoid false negatives, the string must use the same
@@ -52,11 +46,7 @@ module Freyia
       # Holds the content to be added to the file.
       #
       def render
-        @render ||= if data.is_a?(Proc)
-                      data.()
-                    else
-                      data
-                    end
+        @render ||= data.is_a?(Proc) ? data.() : data
       end
 
       def call

data/lib/freyia/automations/create_link.rb

@@ -4,36 +4,28 @@ require_relative "create_file"
 
 module Freyia
   module Automations
-    # Create a new file relative to the destination root from the given source.
+    # Create a new symbolic link relative to the destination root from the given source.
     #
-    # ==== Parameters
-    # destination<String>:: the relative path to the destination root.
-    # source<String|NilClass>:: the relative path to the source root.
-    # config<Hash>:: give :verbose => false to not log the status.
-    #   :: give :symbolic => false for hard link.
-    #
-    # ==== Examples
+    # @param destination [String] the relative path to the destination root.
+    # @param source [String|NilClass] the relative path to the source root.
+    # @param config [Hash] give `verbose: false` to not log the status.
+    #   give `symbolic: false` for hard link.
     #
+    # @example Creating a link
     #   create_link "config/apache.conf", "/etc/apache.conf"
-    #
-    def create_link(destination, *args)
-      config = args.last.is_a?(Hash) ? args.pop : {}
-      source = args.first
-      CreateLink.new(self, destination, source, config).()
+    def create_link(destination, source, **config)
+      CreateLink.new(self, destination, source, **config).()
     end
     alias_method :add_link, :create_link
 
     # CreateLink is a subset of CreateFile, which instead of taking a block of
     # data, just takes a source string from the user.
-    #
-    class CreateLink < CreateFile #:nodoc:
+    class CreateLink < CreateFile
       attr_reader :data
 
       # Checks if the content of the file at the destination is identical to the rendered result.
       #
-      # ==== Returns
-      # Boolean:: true if it is identical, false otherwise.
-      #
+      # @return [Boolean] true if it is identical, false otherwise.
       def identical?
         source = File.expand_path(render, File.dirname(destination))
         exists? && File.identical?(source, destination)
@@ -55,9 +47,7 @@ module Freyia
         given_destination
       end
 
-      def exists?
-        super || File.symlink?(destination)
-      end
+      def exists? = super || File.symlink?(destination)
     end
   end
 end

data/lib/freyia/automations/directory.rb

@@ -5,17 +5,17 @@ require_relative "empty_directory"
 module Freyia
   module Automations
     # Copies recursively the files from source directory to root directory.
-    # If any of the files finishes with .tt, it's considered to be a template
-    # and is placed in the destination without the extension .tt. If any
+    # If any of the files finishes with `.tmpl`, it's considered to be a template
+    # and is placed in the destination without the extension `.tmpl`. If any
     # empty directory is found, it's copied and all .empty_directory files are
-    # ignored. If any file name is wrapped within % signs, the text within
-    # the % signs will be executed as a method and replaced with the returned
+    # ignored. If any file name is wrapped within `%` signs, the text within
+    # the `%` signs will be executed as a method and replaced with the returned
     # value. Let's suppose a doc directory with the following files:
     #
     #   doc/
     #     components/.empty_directory
     #     README
-    #     rdoc.rb.tt
+    #     rdoc.rb.tmpl
     #     %app_name%.rb
     #
     # When invoked as:
@@ -31,46 +31,39 @@ module Freyia
     #     rdoc.rb
     #     blog.rb
     #
-    # <b>Encoded path note:</b> Since Freyia internals use Object#respond_to? to check if it can
-    # expand %something%, this `something` should be a public method in the class calling
-    # #directory. If a method is private, Freyia stack raises PrivateMethodEncodedError.
+    # **Encoded path note:** Since Freyia internals use Object#respond_to? to check if it can
+    # expand `%something%`, this `something` should be a public method in the class calling
+    # `#directory`.
     #
-    # ==== Parameters
-    # source<String>:: the relative path to the source root.
-    # destination<String>:: the relative path to the destination root.
-    # config<Hash>:: give :verbose => false to not log the status.
-    #                If :recursive => false, does not look for paths recursively.
-    #                If :mode => :preserve, preserve the file mode from the source.
-    #                If :exclude_pattern => /regexp/, prevents copying files that match that regexp.
-    #
-    # ==== Examples
+    # @param source [String] the relative path to the source root.
+    # @param destination [String] the relative path to the destination root.
+    # @param config [Hash]
+    #   * give `verbose: false` to not log the status.
+    #   * `recursive: false`, does not look for paths recursively.
+    #   * `mode: :preserve`, preserve the file mode from the source.
+    #   * `exclude_pattern: /regexp/`, prevents copying files that match that regexp.
     #
+    # @example Copy a directory verbatim
     #   directory "doc"
-    #   directory "doc", "docs", :recursive => false
-    #
-    def directory(source, *args, &)
-      config = args.last.is_a?(Hash) ? args.pop : {}
-      destination = args.first || source
-      Directory.new(self, source, destination || source, config, &).()
+    # @example Copy a directory using a new name and no subdirectories
+    #   directory "doc", "docs", recursive: false
+    def directory(source, destination = nil, **config, &)
+      Directory.new(self, source, destination, **config, &).()
     end
 
-    class Directory < EmptyDirectory #:nodoc:
+    class Directory < EmptyDirectory
       attr_reader :source
 
-      def initialize(base, source, destination = nil, config = {}, &block)
+      def initialize(base, source, destination = source, **config, &block)
         @source = File.expand_path(
           Dir[Automations.escape_globs(base.find_in_source_paths(source.to_s))].first
         )
         @block = block
-        super(base, destination, { recursive: true }.merge(config))
+        super(base, destination, recursive: true, **config)
       end
 
       def call
-        base.empty_directory given_destination, config
-        execute!
-      end
-
-      def revoke!
+        base.empty_directory given_destination, **config
         execute!
       end
 
@@ -93,11 +86,11 @@ module Freyia
             dirname = File.dirname(file_destination).gsub(%r{/\.$}, "")
             next if dirname == given_destination
 
-            base.empty_directory(dirname, config)
+            base.empty_directory(dirname, **config)
           when %r{#{TEMPLATE_EXTNAME}$}o
-            base.template(file_source, file_destination[0..-4], config, &@block)
+            base.template(file_source, file_destination[0..-4], **config, &@block)
           else
-            base.copy_file(file_source, file_destination, config, &@block)
+            base.copy_file(file_source, file_destination, **config, &@block)
           end
         end
       end

data/lib/freyia/automations/empty_directory.rb

@@ -4,16 +4,13 @@ module Freyia
   module Automations
     # Creates an empty directory.
     #
-    # ==== Parameters
-    # destination<String>:: the relative path to the destination root.
-    # config<Hash>:: give :verbose => false to not log the status.
-    #
-    # ==== Examples
+    # @param destination [String] the relative path to the destination root.
+    # @param config [Hash] give `verbose: false` to not log the status.
     #
+    # @example Create an empty directory
     #   empty_directory "doc"
-    #
-    def empty_directory(destination, config = {})
-      EmptyDirectory.new(self, destination, config).()
+    def empty_directory(destination, **config)
+      EmptyDirectory.new(self, destination, **config).()
     end
 
     # Class which holds create directory logic. This is the base class for
@@ -21,19 +18,18 @@ module Freyia
     #
     # This implementation is based in Templater automations, created by Jonas Nicklas
     # and Michael S. Klishin under MIT LICENSE.
-    #
-    class EmptyDirectory #:nodoc:
+    class EmptyDirectory
       attr_reader :base, :destination, :given_destination, :relative_destination, :config
 
       # Initializes given the source and destination.
       #
       # ==== Parameters
-      # base<Freyia::Base>:: A Freyia::Base instance
-      # source<String>:: Relative path to the source of this file
-      # destination<String>:: Relative path to the destination of this file
-      # config<Hash>:: give :verbose => false to not log the status.
-      #
-      def initialize(base, destination, config = {})
+      # @param base [Object<Freyia::Setup>]
+      #   A {Freyia::Base} instance (or any object with the {Freyia::Setup} mixin)
+      # @param source [String] Relative path to the source of this file
+      # @param destination [String] Relative path to the destination of this file
+      # @param config [Hash] give `verbose: false` to not log the status.
+      def initialize(base, destination, **config)
         @base = base
         @config = { verbose: true }.merge(config)
         self.destination = destination
@@ -41,9 +37,7 @@ module Freyia
 
       # Checks if the destination file already exists.
       #
-      # ==== Returns
-      # Boolean:: true if the file exists, false otherwise.
-      #
+      # @return [Boolean] true if the file exists, false otherwise.
       def exists?
         ::File.exist?(destination)
       end
@@ -55,17 +49,9 @@ module Freyia
         end
       end
 
-      def revoke!
-        say_status :remove, :red
-        require "fileutils"
-        ::FileUtils.rm_rf(destination) if !pretend? && exists?
-        given_destination
-      end
-
       protected
 
       # Shortcut for pretend.
-      #
       def pretend?
         base.options[:pretend]
       end
@@ -83,7 +69,6 @@ module Freyia
       #   destination          #=> dest/bar/baz
       #   relative_destination #=> bar/baz
       #   given_destination    #=> baz
-      #
       def destination=(destination)
         return unless destination
 
@@ -96,13 +81,12 @@ module Freyia
       #
       #   %file_name%.rb
       #
-      # It calls #file_name from the base and replaces %-string with the
-      # return value (should be String) of #file_name:
+      # It calls `#file_name` from the base and replaces %-string with the
+      # return value (should be String) of `#file_name`:
       #
       #   user.rb
       #
-      # The method referenced can be either public or private.
-      #
+      # The method referenced should be public.
       def convert_encoded_instructions(filename)
         filename.gsub(%r{%(.*?)%}) do |initial_string|
           method = ::Regexp.last_match(1).strip
@@ -112,7 +96,6 @@ module Freyia
 
       # Receives a hash of options and just execute the block if some
       # conditions are met.
-      #
       def invoke_with_conflict_check(&)
         if exists?
           on_conflict_behavior(&)
@@ -131,13 +114,11 @@ module Freyia
       end
 
       # What to do when the destination file already exists.
-      #
       def on_conflict_behavior
         say_status :exist, :blue
       end
 
       # Shortcut to say_status shell method.
-      #
       def say_status(status, color)
         base.shell.say_status status, relative_destination, color if config[:verbose]
       end