geb 0.1.11

data/lib/geb/site/template.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+#
+# This module is responsible for handling site templates, including downloading
+# and extracting templates from remote URLs.
+#
+# @title Geb - Site - Template Module
+# @author Edin Mustajbegovic <edin@actiontwelve.com>
+# @copyright 2024 Edin Mustajbegovic
+# @license MIT
+#
+# @see https://github.com/mainfram-work/geb for more information
+
+module Geb
+  class Site
+    module Template
+
+      class InvalidTemplateURL < Geb::Error
+        MESSAGE = "Invalid template URL specified. Ensure the template URL is properly accessible and packaged Gab site using geb release --with_template".freeze
+        def initialize(e = ""); super(e, MESSAGE); end
+      end # class InvalidTemplateURL < Geb::Error
+
+      class InvalidTemplateSpecification < Geb::Error
+        MESSAGE = "Template has no template paths defined in geb.config.yml".freeze
+        def initialize(e = ""); super(e, MESSAGE); end
+      end # class InvalidTemplateSpecification < Geb::Error
+
+      # copy the template from the specified path to the site path. It uses template_paths from the configuration
+      # file to find the template. If the template is not found, it raises an error.
+      # @raise UnvalidatedSiteAndTemplate if the site has not been validated
+      # @raise InvalidTemplateSpecification if the template path is not a directory or has no geb.config.yml file
+      # @raise InvalidTemplateSpecification if the resolved template paths are empty
+      # @raise InvalidTemplateSpecification if the site cannot be loaded from the template path
+      # @raise InvalidTemplateSpecification if the resolved template paths cannot be copied to the site path
+      def copy_template_from_path
+
+        # raise an error if the site has not been validated
+        raise UnvalidatedSiteAndTemplate.new unless @validated
+
+        # check if the template path is a directory
+        raise InvalidTemplateSpecification.new("Template path [#{@template_path}] is not a directory") unless File.directory?(@template_path)
+
+        # check if the template path has a geb.config.yml file
+        raise InvalidTemplateSpecification.new("Template path [#{@template_path}] has no geb.config.yml file") unless Geb::Config.site_directory_has_config?(@template_path)
+
+        # create a site for the template, load it and get the site configuration
+        Geb.log_start "Loading template site from path #{@template_path} ... "
+        template_site = Geb::Site.new
+        Geb.no_log { template_site.load(@template_path) } # suppress logging for loading the template site
+        Geb.log "done."
+
+        # resolve template paths to directories and files to be copied
+        Geb.log_start "Resolving directories and files from template site to copy ... "
+        resolved_template_paths = template_site.site_config.template_paths.flat_map do |template_file_path|
+          Dir.glob(File.join(template_site.site_path, template_file_path))
+        end
+        Geb.log "done. Found #{resolved_template_paths.count} directories and files."
+
+        # if the resolved template paths are empty, raise an error
+        raise InvalidTemplateSpecification.new("Failed to load site from [#{template_site.site_path}]") if resolved_template_paths.empty?
+
+        # copy the resolved template paths to the site path
+        Geb.copy_paths_to_directory(template_site.site_path, resolved_template_paths, @site_path)
+
+      end # def copy_template_from_path
+
+      # bundle the site as a template archive
+      # @raise SiteNotFoundError if the site is not loaded
+      # @raise InvalidTemplateSpecification if the template paths are not specified
+      # @raise InvalidTemplateSpecification if the resolved template paths are empty
+      # @raise InvalidTemplateSpecification if the template archive cannot be created
+      def bundle_template
+
+        # raise an error if the site is not loaded
+        raise Geb::Site::SiteNotFoundError.new("Site not loaded") unless @loaded
+
+        # resolve template paths to directories and files to be copied
+        Geb.log_start "Resolving directories and files to include in the template archive ... "
+        resolved_template_paths = @site_config.template_paths.flat_map do |template_file_path|
+          Dir.glob(File.join(@site_path, template_file_path))
+        end
+        Geb.log "done. Found #{resolved_template_paths.count} directories and files."
+
+        # if the resolved template paths are empty, raise an error
+        raise InvalidTemplateSpecification.new("Config template_paths not specified.") if resolved_template_paths.empty?
+
+        # create a temporary directory for the site template
+        tmp_archive_directory = Dir.mktmpdir
+
+        # copy the resolved paths to the temporary directory
+        Geb.log "Copying directories and files to the template archive directory #{tmp_archive_directory}"
+        Geb.copy_paths_to_directory(@site_path, resolved_template_paths, tmp_archive_directory)
+        Geb.log "Done copying directories and files to the template archive directory."
+
+        # create a template archive with files from the temporary directory into the release directory
+        output_archive_filename = File.join(@site_path, @site_config.output_dir, Geb::Defaults::RELEASE_OUTPUT_DIR, Geb::Defaults::TEMPLATE_ARCHIVE_FILENAME)
+        Geb.log_start "Creating template archive in [#{output_archive_filename}] ... "
+        Open3.capture3("tar", "-czvf", output_archive_filename, "-C", tmp_archive_directory, ".")
+        Geb.log "done."
+
+      end # def bundle_template
+
+      # validate the template URL. It checks if the URL is accessible and is a tar.gz file.
+      # if the URL is not accessible, it tries to find the template by appending TEMPLATE_ARCHIVE_FILENAME
+      # this is to facilitate specifiying a top level URL. The method returns the URL if it is valid.
+      # @param template_url [String] the URL to the template
+      # @raise InvalidTemplateURL if the URL is not accessible or is not a tar.gz file
+      # @return [String] the validated template URL
+      def validate_template_url(template_url)
+
+        # get the HTTP response for the template URL
+        Geb.log_start "Validating template URL #{template_url} ... "
+        response = fetch_http_response(template_url)
+        Geb.log "done."
+
+        # check if the URL is accessible and is a tar.gz file, if not, try to find by appending TEMPLATE_ARCHIVE_FILENAME
+        unless response.is_a?(Net::HTTPSuccess) && Geb::Defaults::HTTP_TEMPLATE_CONTENT_TYPES.include?(response['Content-Type'])
+
+          # check if the URL already has the TEMPLATE_ARCHIVE_FILENAME appended, if not, append it and try again
+          unless template_url.end_with?(Geb::Defaults::TEMPLATE_ARCHIVE_FILENAME)
+
+            # add TEMPLATE_ARCHIVE_FILENAME to the URL (handle trailing slashes)
+            template_url += '/' unless template_url.end_with?('/')
+            template_url += Geb::Defaults::TEMPLATE_ARCHIVE_FILENAME
+
+            Geb.log ("Failed. Web server returned #{response.code}, trying to re-try with url #{template_url}") unless response.is_a?(Net::HTTPSuccess)
+            Geb.log ("Specified template is not a gzip archive, trying to re-try with url #{template_url}")     unless Geb::Defaults::HTTP_TEMPLATE_CONTENT_TYPES.include?(response['Content-Type'])
+            Geb.log_start ("Trying to find geb template using URL #{template_url} ... ");
+
+            # get the HTTP response for the template URL (now modified to include the archive filename)
+            response = fetch_http_response(template_url)
+
+          end # unless
+
+        end # unless
+
+        # raise an error if the URL is not accessible and is not a tar.gz file
+        raise InvalidTemplateURL.new("Web server returned #{response.code}")      unless response.is_a?(Net::HTTPSuccess)
+        raise InvalidTemplateURL.new("Specified template is not a gzip archive")  unless Geb::Defaults::HTTP_TEMPLATE_CONTENT_TYPES.include?(response['Content-Type'])
+
+        Geb::log("Found a gzip archive at template url #{template_url}.");
+
+        return template_url
+
+      end # validate_template_url
+
+      # download the template into a temporary directory from the URl and extract it,
+      # return the path to the extracted template
+      # @param template_url [String] the URL to the template
+      # @raise InvalidTemplateURL if the template extraction fails
+      # @return [String] the path to the extracted template
+      def download_template_from_url(template_url)
+
+        # create a temporary directory
+        tmp_dir = Dir.mktmpdir
+
+        Geb.log_start "Downloading template from URL #{template_url} ... "
+
+        # download the template archive
+        File.open("#{tmp_dir}/#{Geb::Defaults::TEMPLATE_ARCHIVE_FILENAME}", "wb") do |file|
+          file.write(Net::HTTP.get(URI.parse(template_url)))
+        end
+
+        # extract the template archive using Open3
+        _, stderr, status = Open3.capture3("tar", "-xzf", "#{tmp_dir}/#{Geb::Defaults::TEMPLATE_ARCHIVE_FILENAME}", "-C", tmp_dir)
+
+        # raise an error if the template extraction failed or the geb config file is not present
+        raise InvalidTemplateURL.new("Failed to extract template archive: #{stderr}") unless status.success?
+        raise InvalidTemplateURL.new("Invalid template archive") unless File.exist?("#{tmp_dir}/geb.config.yml")
+
+        Geb.log "done. Extracted template to #{tmp_dir}."
+
+        # return the path to the extracted template
+        return tmp_dir
+
+      end # def ownload_template_from_url
+
+      # fetch the HTTP response for the URL
+      # @param url [String] the URL to fetch
+      # @raise InvalidTemplateURL if the URL is not accessible
+      # @return [Net::HTTPResponse] the HTTP response
+      def fetch_http_response(url)
+        return_response = nil
+        begin
+          return_response = Net::HTTP.get_response(URI.parse(url))
+        rescue StandardError => e
+          raise InvalidTemplateURL.new("HTTP error: #{e.message}")
+        end # begin
+        return return_response
+      end # def fetch_http_response
+
+      # check if the template directory exists
+      def template_directory_exists?(template_path)
+        File.directory?(template_path)
+      end # def template_directory_exists?
+
+      # check if the URL is a valid URL
+      def is_url?(url)
+        url =~ URI::DEFAULT_PARSER.make_regexp
+      end # def is_url?
+
+      # check if the template is a bundled template
+      def is_bundled_template?(template)
+        Geb::Defaults::AVAILABLE_TEMPLATES.include?(template)
+      end # def is_bundled_template?
+
+    end # module Template
+  end # class Site
+end # module Geb

data/lib/geb/site.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+#
+# Represents a site object, handles creation, building and management of sites.
+#
+# @title Geb - Site
+# @author Edin Mustajbegovic <edin@actiontwelve.com>
+# @copyright 2024 Edin Mustajbegovic
+# @license MIT
+#
+# @see https://github.com/mainfram-work/geb for more information
+
+# include the required libraries
+require 'uri'
+require 'net/http'
+require 'tmpdir'
+require 'open3'
+require 'shellwords'
+
+# include site modules
+require_relative 'site/core'
+require_relative 'site/build'
+require_relative 'site/release'
+require_relative 'site/template'
+require_relative 'site/remote'
+
+module Geb
+  class Site
+
+    # include site sub-modules
+    include Geb::Site::Core       # core site functionality, loading, validation and creation
+    include Geb::Site::Build      # building the site, pages, page templates, partials and assets
+    include Geb::Site::Release    # releasing the site, pages and assets
+    include Geb::Site::Template   # mostly remote template handling
+    include Geb::Site::Remote     # remote site functionality, ssh, scp, rsync, etc.
+
+    # @!attribute [r] site_path
+    #  @return [String] the site path
+    attr_reader :site_path
+
+    # @!attribute [r] site_config
+    # @return [Geb::Config] the site configuration
+    attr_reader :site_config
+
+    # @!attribute [r] template_path
+    # @return [String] the path template the site is based on
+    attr_reader :template_path
+
+    # @!attribute [r] validated
+    # @return [Boolean] true if the site is validated
+    attr_reader :validated
+
+    # @!attribute [r] loaded
+    # @return [Boolean] true if the site is loaded
+    attr_reader :loaded
+
+    # @!attribute [r] pages
+    # @return [Hash] the site pages to process
+    attr_reader :pages
+
+    # site constructor
+    # initializes the site object and attributes
+    def initialize
+
+      @validated = false
+      @loaded = false
+      @site_path = nil
+      @template_path = nil
+      @pages = {}
+
+    end # def initialize
+
+    private
+
+    # get the site name.  It either uses the configured name or the last folder in
+    # the site_path as site name.
+    # @return [String] the site name
+    def site_name
+      return  @site_config.site_name
+    end # def site_name
+
+  end # class Site
+
+end # module Geb

data/lib/geb/template.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+#
+# Represents a page template. A page template is a page file that contains
+# template definitions and insert sections. The class keeps a cache of
+# already loaded page templates.
+#
+# @title Geb - Template
+# @author Edin Mustajbegovic <edin@actiontwelve.com>
+# @copyright 2024 Edin Mustajbegovic
+# @license MIT
+#
+# @todo Make template, section and insert patterns configurable
+#
+# @see https://github.com/mainfram-work/geb for more information
+
+require 'fileutils'
+
+module Geb
+  class Template
+
+    TEMPLATE_PATTERN  = /<% template: (.*?) %>/
+    SECTION_PATTERN   = /<% start: (.*?) %>(.*?)<% end: \1 %>/m
+    INSERT_PATTERN    = /<%= insert: (.*?) %>/
+
+    class TemplateFileNotFound < Geb::Error
+      MESSAGE = "Template file not found".freeze
+      def initialize(e = ""); super(e, MESSAGE); end
+    end # class TemplateFileNotFound < Geb::Error
+
+    class TemplateFileReadFailure < Geb::Error
+      MESSAGE = "Failed to read the template file.".freeze
+      def initialize(e = ""); super(e, MESSAGE); end
+    end # class TemplateFileReadFailure < Geb::Error
+
+    # define a class level cache for loaded template objects
+    @@loaded_templates = {}
+
+    # class method to expire the template cache
+    def self.expire_cache
+      @@loaded_templates = {}
+    end # def self.expire_cache
+
+    # class method to initialise a template if it is not already loaded, otherwise, return the cached template
+    # @param template_path [String] the path to the template file
+    # @return [Geb::Template] the template object
+    def self.load(template_path)
+
+      # initialise a return template object
+      return_template = nil
+
+      # check if the template is already loaded
+      if @@loaded_templates.key?(template_path)
+
+        # return the cached template
+        Geb.log " - using cached template: #{template_path}"
+        return_template = @@loaded_templates[template_path]
+
+      else
+
+        # create a new template object
+        return_template = Template.new(template_path)
+
+        # add the template to the cache
+        @@loaded_templates[template_path] = return_template
+
+      end # if else
+
+      # return the new template object
+      return return_template
+
+    end # def self.load
+
+    # extract the template path from the page content
+    # @param page_content [String] the page content
+    # @return [String] the template path, or nil if no template path is found
+    # @note the function looks for tags like this <% template: shared/templates/_site.html %> in the page content
+    def self.extract_template_path(page_content)
+
+      # match the template pattern and return the template path
+      match = page_content.match(TEMPLATE_PATTERN)
+
+      # return the template path or nil if no match
+      return match ? match[1].strip : nil
+
+    end # def self.extract_template_path
+
+    # extract the sections for the template from the page content
+    # @param page_content [String] the page content
+    # @return [Hash] the sections for the template, key is the section name, value is the section content
+    # @note the function looks for tags like this <% start: header %> ... <% end: header %> in the page content and returns whats in between
+    def self.extract_sections_for_template(page_content)
+
+      # initialise the sections for the template hash
+      sections_for_template = {}
+
+      # scan the page content for sections and add them to the hash
+      page_content.scan(SECTION_PATTERN).each do |section|
+        sections_for_template[section[0].strip] = section[1].strip
+      end # scan
+
+      # return the sections for the template
+      return sections_for_template
+
+    end # def self.extract_sections_for_template
+
+    # @!attribute [r] path
+    # @return [String] the path to the template file
+    attr_reader :path
+
+    # @!attribute [r] content
+    # @return [String] the content of the template file
+    attr_reader :content
+
+    # Template class constructor
+    # @param template_path [String] the path to the template file
+    # @return [Geb::Template] the template object
+    def initialize(template_path)
+
+      # set the specified template path and initialise the content
+      @path = template_path
+      @content = nil
+
+      # check if the template file exists
+      raise TemplateFileNotFound.new(template_path) unless template_file_exists?()
+
+      Geb.log " - loading template: #{@path}"
+
+      # read the template file, raise an error if the file could not be read
+      begin
+        @content = File.read(template_path)
+      rescue => e
+        raise TemplateFileReadFailure.new(e.message)
+      end # begin
+
+    end # def initialize
+
+    # parse the page content sections and replace the sections in the template with the page section content
+    # @param page_content_sections [Hash] the page content sections, key is the section name, value is the section content
+    # @return [String] the parsed template content
+    # @note the function looks for tags like this <%= insert: header %> in the template content
+    def parse(page_content_sections)
+
+      # create a duplicate of the template content
+      return_content = @content.dup
+
+      # step through the page content sections and replace the insert sections in the template with the page content
+      return_content.gsub!(INSERT_PATTERN) do |match|
+        section_name = match.match(INSERT_PATTERN)[1].strip
+        page_content_sections[section_name] || match
+      end # return_content.gsub!
+
+      # return the content
+      return return_content
+
+    end # def parse
+
+    private
+
+    # check if the template file exists
+    # @return [Boolean] true if the template file exists, otherwise false
+    def template_file_exists?
+      return File.exist?(@path)
+    end # def template_file_exists?
+
+  end # class Template
+end # module Geb

data/lib/geb/utilities.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+#
+# A simple list of Geb utilities for the Geb gem
+#
+# @title Geb - Utilities
+# @author Edin Mustajbegovic <edin@actiontwelve.com>
+# @copyright 2024 Edin Mustajbegovic
+# @license MIT
+#
+# @see https://github.com/mainfram-work/geb for more information
+
+module Geb
+
+  # define the main error class
+  class Error < StandardError
+
+    # initialize the error class
+    # @param custom_error [String] the custom error message
+    # @param default_message [String] the default error message
+    # @return [Geb::Error] the error object
+    # @raise [Geb::Error] the error object
+    def initialize(custom_error = "", default_message = "")
+
+      # set the error message
+      message = custom_error.empty? ? default_message : "#{custom_error} #{default_message}"
+
+      # call the parent class constructor
+      super(message)
+
+    end # def initialize
+
+  end # class Error < StandardError
+
+  # initialise a flag for suppressing output
+  @@suppress_log_output = false
+
+  # log method for printing messages to the console
+  # @param message [String] the message to print
+  # @note this method will print a newline character at the end of the message
+  # @note this method will print the message to the console if the suppress log output flag is not set
+  def self.log(message)
+    puts message unless @@suppress_log_output
+  end # def self.log
+
+  # log method for printing messages to the console
+  # @param message [String] the message to print
+  # @note this method will not print a newline character at the end of the message
+  # @note this method will print the message to the console if the suppress log output flag is not set
+  def self.log_start(message)
+    print message unless @@suppress_log_output
+  end # def self.log
+
+  # method to suppress log output within a block
+  # @return [Object] the return value of the block
+  # @yield the block to suppress log output
+  def self.no_log
+
+    # store the original value of the suppress log output flag (just in case)
+    original_value = @@suppress_log_output
+
+    # set the suppress log output flag
+    @@suppress_log_output = true
+
+    # yield the block
+    yield
+
+  ensure
+
+    # reset the suppress log output flag
+    @@suppress_log_output = original_value
+
+  end # def self.no_log
+
+  # copy the specified file and directory paths to the destination directory
+  # @param source_path [String] the source directory
+  # @param paths [Array] the paths to copy (still full paths, but from source directory)
+  # @param destination_path [String] the destination directory
+  # @param quiet [Boolean] the flag to suppress output
+  # @raise [Geb::Error] if the any of the file operations fail
+  def self.copy_paths_to_directory(source_path, paths, destination_path, quiet = false)
+
+    # step through the resolved template paths and copy them to the site path, taking care of files vs directories
+    paths.each do |path|
+
+      # get the relative path of the resolved template path and build the destination path
+      relative_template_path = path.gsub(source_path, "")
+      destination_file_path = File.join(destination_path, relative_template_path)
+
+      # ensure the destination directory exists
+      FileUtils.mkdir_p(File.dirname(destination_path))
+
+      # copy the resolved template path to the destination path
+      if File.directory?(path)
+        Geb.log_start " - copying directory and all sub-directories from #{path} to #{destination_file_path} ... " unless quiet
+        FileUtils.cp_r(path, destination_file_path)
+      else
+        Geb.log_start " - copying file from #{path} to #{destination_file_path} ... " unless quiet
+        FileUtils.cp(path, destination_file_path)
+      end # if else
+      Geb.log "done." unless quiet
+
+    end # each
+
+  rescue Exception => e
+    raise Geb::Error.new("Failed to copy paths to directory: #{e.message}")
+
+  end # def self.copy_paths_to_directory
+
+
+end # module Geb

data/lib/geb.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+#
+# Main module definition for the Geb gem, it includes all the functionality
+# and modules for the Geb gem.
+#
+# @title Geb
+# @author Edin Mustajbegovic <edin@actiontwelve.com>
+# @copyright 2024 Edin Mustajbegovic
+# @license MIT
+#
+# @see https://github.com/mainfram-work/geb for more information
+
+# Define the main module, version and main error class
+module Geb
+
+  # define the version of the gem
+  VERSION = "0.1.11"
+
+end # module Geb
+
+# include external libraries
+require "dry/cli"
+
+# include geb libraries
+require_relative "geb/defaults"
+require_relative "geb/utilities"
+require_relative "geb/config"
+require_relative "geb/git"
+require_relative "geb/site"
+require_relative "geb/page"
+require_relative "geb/template"
+require_relative "geb/partial"
+require_relative "geb/server"
+
+# make sure geb/cli is loaded last
+require_relative "geb/cli"

data/lib/seth.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+#
+# Module with some pretty crazy things.
+# Seth is an egyption god of chaos and mischief.  This code is a tribute to him.
+# Some of the thigns here run at the very bassis of the Ruby language and change
+# how standard things work.  This is not for the faint of heart.
+#
+# @title Geb
+# @author Edin Mustajbegovic <edin@actiontwelve.com>
+# @copyright 2024 Edin Mustajbegovic
+# @license MIT
+#
+# @see https://github.com/mainfram-work/geb for more information
+
+module Seth
+
+  # Suppress warnings within the block being executed. This is useful for testing.
+  # @example
+  #
+  #   suppress_warnings do
+  #     # code that generates warnings
+  #   end
+  #   # no warnings will be printed
+  #
+  # @yield []
+  # @return [void]
+  def suppress_warnings
+
+    # save the original verbose setting
+    original_verbose = $VERBOSE
+
+    # suppress warnings
+    $VERBOSE = nil
+
+    # execute the block
+    yield
+
+  ensure
+
+    # restore the original verbose setting
+    $VERBOSE = original_verbose
+
+  end # def suppress_warnings
+
+  # can you imagine what this does? ;)
+  module_function :suppress_warnings
+
+end # module Seth
+
+puts "Seth has been loaded.  Hang on to your hats!. Seth is here: #{__FILE__}"

data/sig/geb.rbs

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