openapi-sourcetools 0.7.0 → 0.8.0

data/lib/openapi/sourcetools/docs.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+module OpenAPISourceTools
+  # To hold documents loaded via command-line.
+  # Provides attribute accessor methods for each document.
+  # Exposed via Gen.d to tasks.
+  class Docs
+    attr_reader :docs
+
+    def initialize
+      @docs = {}
+    end
+
+    def method_missing(method_name, *args)
+      name = method_name.to_s
+      if name.end_with?('=')
+        name = name[0...(name.size - 1)]
+        super unless @docs.key?(name)
+        @docs[name] = args.first
+        return args.first
+      end
+      super unless @docs.key?(name)
+      @docs[name]
+    end
+
+    def respond_to_missing?(method_name, *args)
+      name = method_name.to_s
+      name = name[0...(name.size - 1)] if name.end_with?('=')
+      @docs.key?(name) || super
+    end
+
+    def add(name, content)
+      return false if docs.key?(name)
+      @docs[name] = content
+      true
+    end
+  end
+end

data/lib/{gen.rb → openapi/sourcetools/gen.rb}

@@ -1,37 +1,44 @@
 # frozen_string_literal: true
 
-# Copyright © 2024 Ismo Kärkkäinen
+# Copyright © 2024-2025 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative 'task'
 require_relative 'helper'
 require_relative 'docs'
 require_relative 'output'
+require_relative 'config'
+require 'deep_merge'
 
 
+# The generation module that contains things visible to tasks.
 module Gen
   def self.add_doc(symbol, docstr)
     return if docstr.nil?
     @docsrc = [] unless instance_variable_defined?('@docsrc')
-    @docsrc.push("- #{symbol.to_s} : #{docstr}")
+    @docsrc.push("- #{symbol} : #{docstr}")
   end
+  private_class_method :add_doc
 
   def self.read_attr(symbol, default)
     return if symbol.nil?
     attr_reader(symbol)
     module_function(symbol)
-    instance_variable_set("@#{symbol.to_s}", default)
+    instance_variable_set("@#{symbol}", default)
   end
+  private_class_method :read_attr
 
   def self.mod_attr2_reader(symbol, symbol2, docstr = nil, default = nil)
     read_attr(symbol, default)
     read_attr(symbol2, default)
     add_doc(symbol, docstr)
   end
+  private_class_method :mod_attr2_reader
 
   def self.mod_attr_reader(symbol, docstr = nil, default = nil)
     mod_attr2_reader(symbol, nil, docstr, default)
   end
+  private_class_method :mod_attr_reader
 
   def self.rw_attr(symbol, default)
     attr_accessor(symbol)
@@ -40,39 +47,56 @@ module Gen
     module_function((s + '=').to_sym)
     instance_variable_set("@#{s}", default)
   end
+  private_class_method :rw_attr
 
   def self.mod_attr2_accessor(symbol, symbol2, docstr = nil, default = nil)
     rw_attr(symbol, default)
     rw_attr(symbol2, default) unless symbol2.nil?
     add_doc(symbol, docstr)
   end
+  private_class_method :mod_attr2_accessor
 
   def self.mod_attr_accessor(symbol, docstr = nil, default = nil)
     mod_attr2_accessor(symbol, nil, docstr, default)
   end
+  private_class_method :mod_attr_accessor
 
   mod_attr_reader :doc, 'OpenAPI document.'
   mod_attr_reader :outdir, 'Output directory name.'
-  mod_attr_reader :d, 'Other documents object.', Docs.new
+  mod_attr_reader :d, 'Other documents object.', OpenAPISourceTools::Docs.new
+  mod_attr_reader :wd, 'Original working directory', Dir.pwd
+  mod_attr_reader :configuration, 'Generator internal configuration'
+  mod_attr_accessor :config, 'Configuration file name for next gem or Ruby file.'
+  mod_attr_accessor :separator, 'Key separator in config file names.', nil
   mod_attr_accessor :in_name, 'OpenAPI document name, nil if stdin.'
   mod_attr_accessor :in_basename, 'OpenAPI document basename, nil if stdin.'
-  mod_attr_accessor :tasks, 'Tasks array.', []
-  mod_attr_accessor :g, 'Hash for storing values visible to all tasks.', {}
-  mod_attr_accessor :a, 'Intended for instance with defined attributes.'
+  mod_attr_reader :g, 'Hash for storing values visible to all tasks.', {}
+  mod_attr_accessor :x, 'Hash for storing values visible to tasks from processor.', {}
   mod_attr_accessor :h, 'Instance of class with helper methods.'
+  mod_attr_accessor :tasks, 'Tasks array.', []
   mod_attr2_accessor :task, :t, 'Current task instance.'
   mod_attr_accessor :task_index, 'Current task index.'
-  mod_attr_accessor :loaders, 'Array of generator loader methods.', []
-  mod_attr2_accessor :output, :o, 'Output-related methods.', Output.new
+  mod_attr_accessor :loaders, 'Array of processor loader methods.', []
+  mod_attr_accessor :output, 'Output-formatting helper.', OpenAPISourceTools::Output.new
+
+  def self.load_config(config_prefix)
+    cfg = {}
+    cfgs = OpenAPISourceTools::ConfigLoader.find_files(name_prefix: config_prefix)
+    cfgs = OpenAPISourceTools::ConfigLoader.read_contents(cfgs)
+    cfgs.each { |c| cfg.deep_merge!(c) }
+    cfg
+  end
+  private_class_method :load_config
 
-  def self.setup(document_content, input_name, output_directory)
+  def self.setup(document_content, input_name, output_directory, config_prefix)
     @doc = document_content
     @outdir = output_directory
     unless input_name.nil?
       @in_name = File.basename(input_name)
       @in_basename = File.basename(input_name, '.*')
     end
-    add_task(task: HelperTask.new)
+    @configuration = load_config(config_prefix)
+    add_task(task: OpenAPISourceTools::HelperTask.new)
   end
 
   def self.add_task(task:, name: nil, executable: false, x: nil)
@@ -85,11 +109,12 @@ module Gen
   end
 
   def self.add_write_content(name:, content:, executable: false)
-    add_task(task: WriteTask.new(name, content, executable))
+    add_task(task: OpenAPISourceTools::WriteTask.new(name, content, executable))
   end
 
   def self.add(source:, template: nil, template_name: nil, name: nil, executable: false, x: nil)
-    add_task(task: Task.new(source, template, template_name), name: name, executable: executable, x: x)
+    add_task(task: OpenAPISourceTools::Task.new(source, template, template_name),
+      name:, executable:, x:)
   end
 
   def self.document

data/lib/openapi/sourcetools/generate.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require_relative 'loaders'
+require_relative 'gen'
+
+
+module OpenAPISourceTools
+  def self.executable_bits_on(mode)
+    mode = mode.to_s(8).chars
+    mode.size.times do |k|
+      m = mode[k].to_i(8)
+      # Applies to Unix-likes. Other system, check and handle.
+      m += 1 unless 3 < mode.size - k || m.zero? || m.odd?
+      mode[k] = m
+    end
+    m = 0
+    mode.each do |v|
+      m = 8 * m + v
+    end
+    m
+  end
+
+  # Runs all tasks that generate the results.
+  # Used internally by openapi-generate.
+  class Generator
+    def initialize(document_content, input_name, output_directory, config_prefix)
+      Gen.setup(document_content, input_name, output_directory, config_prefix)
+      Gen.loaders = Loaders.loaders
+    end
+
+    def context_binding
+      binding
+    end
+
+    def load(generator_names)
+      generator_names.each do |name|
+        idx = Gen.loaders.index { |loader| loader.call(name) }
+        return Common.aargh("No loader could handle #{name}", 2) if idx.nil?
+      end
+      0
+    rescue StandardError => e
+      Common.aargh(e.to_s, 2)
+    end
+
+    def generate(t)
+      t.generate(context_binding)
+    rescue Exception => e
+      Common.aargh(e.to_s, 4)
+    end
+
+    def output_name(t, index)
+      name = t.output_name
+      name = "#{index}.txt" if name.nil?
+      File.join(Gen.outdir, name)
+    end
+
+    def save(name, contents, executable)
+      d = File.dirname(name)
+      FileUtils.mkdir_p(d) unless File.directory?(d)
+      f = File.new(name, File::WRONLY | File::CREAT | File::TRUNC)
+      s = executable ? f.stat : nil
+      f.write(contents)
+      f.close
+      return unless executable
+      mode = OpenAPISourceTools.executable_bits_on(s.mode)
+      File.chmod(mode, name) unless mode == s.mode
+    end
+
+    def run
+      # This allows tasks to be added while processing.
+      # Not intended to be done but might prove handy.
+      # Also exposes current task index in case new task is added in the middle.
+      Gen.task_index = 0
+      while Gen.task_index < Gen.tasks.size
+        Gen.t = Gen.tasks[Gen.task_index]
+        Gen.task = Gen.t
+        out = generate(Gen.t)
+        Gen.task_index += 1
+        return out if out.is_a?(Integer)
+        next if Gen.t.discard || out.empty?
+        name = output_name(Gen.t, Gen.task_index - 1)
+        begin
+          save(name, out, Gen.t.executable)
+        rescue StandardError => e
+          return Common.aargh("Error writing output file: #{name}\n#{e}", 3)
+        end
+      end
+      0
+    end
+  end
+end

data/lib/openapi/sourcetools/helper.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+
+module OpenAPISourceTools
+  # Helper class supposed to contain helpful methods.
+  # Exposed as Gen.h if HelperTask has been run. It is automatically
+  # added as the first task but later tasks can remove it.
+  class Helper
+    attr_reader :doc, :parents
+    attr_accessor :parent_parameters
+
+    # Stores the nearest Hash for each Hash.
+    def store_parents(obj, parent = nil)
+      if obj.is_a?(Hash)
+        @parents[obj] = parent
+        obj.each_value do |v|
+          store_parents(v, obj)
+        end
+      elsif obj.is_a?(Array)
+        obj.each do |v|
+          store_parents(v, parent)
+        end
+      end
+    end
+
+    def initialize(doc)
+      @doc = doc
+      @parents = {}.compare_by_identity
+      store_parents(@doc)
+    end
+
+    def parent(object)
+      @parents[object]
+    end
+
+    COMPONENTS = '#/components/'
+
+    def category_and_name(ref_or_obj)
+      ref = ref_or_obj.is_a?(Hash) ? ref_or_obj['$ref'] : ref_or_obj
+      return nil unless ref.is_a?(String)
+      return nil unless ref.start_with?(Helper::COMPONENTS)
+      idx = ref.index('/', Helper::COMPONENTS.size)
+      return nil if idx.nil?
+      category = ref[Helper::COMPONENTS.size...idx]
+      [ category, ref[(idx + 1)...ref.size] ]
+    end
+
+    def dereference(ref_or_obj)
+      cn = category_and_name(ref_or_obj)
+      return nil if cn.nil?
+      cs = @doc.dig('components', cn.first) || {}
+      cs[cn.last]
+    end
+
+    def basename(ref_or_obj)
+      cn = category_and_name(ref_or_obj)
+      return nil if cn.nil?
+      cn.last
+    end
+
+    def parameters(operation_object, empty_unless_local = false)
+      return [] if empty_unless_local && !operation_object.key?('parameters')
+      cps = @doc.dig('components', 'parameters') || {}
+      uniqs = {}
+      path_item_object = parent(operation_object)
+      [path_item_object, operation_object].each do |p|
+        p.fetch('parameters', []).each do |param|
+          r = basename(param)
+          r = cps[r] if r.is_a?(String)
+          uniqs["#{r['name']}:#{r['in']}"] = param
+        end
+      end
+      uniqs.keys.sort!.map { |k| uniqs[k] }
+    end
+  end
+
+  # Task class to add an Helper instance to Gen.h, for convenience.
+  class HelperTask
+    include OpenAPISourceTools::TaskInterface
+
+    def generate(_context_binding)
+      Gen.h = Helper.new(Gen.doc) if Gen.h.nil?
+    end
+
+    def discard
+      true
+    end
+  end
+end

data/lib/openapi/sourcetools/loaders.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+
+
+# Original loader functions. These are accessible via Gen.loaders. New loaders
+# should be added there.
+module OpenAPISourceTools
+  # Loaders used to load gems and files and set config etc.
+  # Exposed as Gen.loaders if you need to modify the array.
+  module Loaders
+    # Prefix etc. and loader pairs for all loaders.
+
+    REQ_PREFIX = 'req:'
+
+    def self.req_loader(name)
+      return false unless name.downcase.start_with?(REQ_PREFIX)
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        base = name.slice(REQ_PREFIX.size...name.size)
+        require(base)
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      true
+    end
+
+    REREQ_PREFIX = 'rereq:'
+
+    def self.rereq_loader(name)
+      return false unless name.downcase.start_with?(REREQ_PREFIX)
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        code = name.slice(REREQ_PREFIX.size...name.size)
+        eval(code)
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require again #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      true
+    end
+
+    RUBY_EXT = '.rb'
+
+    def self.ruby_loader(name)
+      return false unless name.downcase.end_with?(RUBY_EXT)
+      origwd = Dir.pwd
+      d = File.dirname(name)
+      Dir.chdir(d) unless d == '.'
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        base = File.basename(name)
+        Gen.config = base[0..-4] if Gen.config.nil?
+        require(File.join(Dir.pwd, base))
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      Dir.chdir(origwd) unless d == '.'
+      true
+    end
+
+    YAML_PREFIX = 'yaml:'
+    YAML_EXTS = [ '.yaml', '.yml' ].freeze
+
+    def self.yaml_loader(name)
+      d = name.downcase
+      if d.start_with?(YAML_PREFIX)
+        name = name.slice(YAML_PREFIX.size...name.size)
+      elsif (YAML_EXTS.index { |s| d.end_with?(s) }).nil?
+        return false
+      end
+      n, _sep, f = name.partition(':')
+      raise StandardError, 'No name given.' if n.empty?
+      raise StandardError, 'No filename given.' if f.empty?
+      doc = YAML.safe_load_file(f)
+      raise StandardError, "#{name} #{n} exists already." unless Gen.d.add(n, doc)
+      true
+    rescue Errno::ENOENT
+      raise StandardError, "Not found: #{f}\n#{e}"
+    rescue Exception => e # Whatever was raised, we want it.
+      raise StandardError, "Failed to read as YAML: #{f}\n#{e}"
+    end
+
+    BIN_PREFIX = 'bin:'
+
+    def self.bin_loader(name)
+      return false unless name.downcase.start_with?(BIN_PREFIX)
+      n, _sep, f = name.slice(BIN_PREFIX.size...name.size).partition(':')
+      raise StandardError, 'No name given.' if n.empty?
+      raise StandardError, 'No filename given.' if f.empty?
+      doc = File.binread(f)
+      raise StandardError, "#{name} #{n} exists already." unless Gen.d.add(n, doc)
+      true
+    rescue Errno::ENOENT
+      raise StandardError, "Not found: #{f}\n#{e}"
+    rescue Exception => e # Whatever was raised, we want it.
+      raise StandardError, "Failed to read #{f}\n#{e}"
+    end
+
+    CONFIG_PREFIX = 'config:'
+
+    def self.config_loader(name)
+      return false unless name.downcase.start_with?(CONFIG_PREFIX)
+      raise StandardError, "Config name remains: #{Gen.config}" unless Gen.config.nil?
+      n = name.slice(CONFIG_PREFIX.size...name.size)
+      raise StandardError, 'No name given.' if n.empty?
+      # Interpretation left completely to config loading.
+      Gen.config = n
+      true
+    end
+
+    SEPARATOR_PREFIX = 'separator:'
+
+    def self.separator_loader(name)
+      return false unless name.downcase.start_with?(SEPARATOR_PREFIX)
+      n = name.slice(SEPARATOR_PREFIX.size...name.size)
+      n = nil if n.empty?
+      Gen.separator = n
+      true
+    end
+
+    def self.loaders
+      [
+        method(:req_loader),
+        method(:rereq_loader),
+        method(:ruby_loader),
+        method(:yaml_loader),
+        method(:bin_loader),
+        method(:config_loader),
+        method(:separator_loader)
+      ]
+    end
+
+    def self.document
+      <<EOB
+- #{Loaders::REQ_PREFIX}req_name : requires the gem.
+- #{Loaders::REREQ_PREFIX}code : runs code to add gem tasks again.
+- ruby_file#{Loaders::RUBY_EXT} : changes to Ruby file directory and requires the file.
+- #{Loaders::YAML_PREFIX}name:filename : Loads YAML file into Gen.d.name.
+- name:filename.{#{(Loaders::YAML_EXTS.map { |s| s[1...s.size] }).join('|')}} : Loads YAML file into Gen.d.name.
+- #{Loaders::BIN_PREFIX}name:filename : Loads binary file into Gen.d.name.
+- #{Loaders::CONFIG_PREFIX}name : Sets Gen.config for next gem/Ruby file configuration loading.
+- #{Loaders::SEPARATOR_PREFIX}string : Sets Gen.separator to string.
+EOB
+    end
+  end
+end

data/lib/openapi/sourcetools/output.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+
+module OpenAPISourceTools
+  # Output configuration settings for easy storage.
+  # You can have it in configuration and pass hash to initialize.
+  class OutputConfiguration
+    attr_reader :indent_character, :indent_step
+    attr_reader :tab, :tab_replaces_count
+
+    def initialize(cfg = {})
+      @indent_character = cfg['indent_character'] || ' '
+      @indent_step = cfg['indent_step'] || 4
+      @tab = cfg['tab'] || "\t"
+      @tab_replaces_count = cfg['tab_replaces_count'] || 0
+    end
+  end
+
+  # Output indentation helper class.
+  # Exposed as Gen.output for use from templates.
+  class Output
+    attr_reader :config
+    attr_accessor :last_indent
+
+    def initialize(cfg = OutputConfiguration.new)
+      @config = cfg
+      @last_indent = 0
+    end
+
+    def config=(cfg)
+      cfg = OutputConfiguration.new(cfg) if cfg.is_a?(Hash)
+      raise ArgumentError, "Expected OutputConfiguration or Hash, got #{cfg.class}" unless cfg.is_a?(OutputConfiguration)
+      @config = cfg
+      @last_indent = 0
+    end
+
+    # Takes an array of code blocks/lines or integers/booleans and produces
+    # indented output using the separator character.
+    # Set class attributes to obtain desired outcome.
+    def join(blocks, separator = "\n")
+      indented = []
+      blocks.flatten!
+      indent = 0
+      blocks.each do |block|
+        if block.nil?
+          indent = 0
+        elsif block.is_a?(Integer)
+          indent += block
+        elsif block.is_a?(TrueClass)
+          indent += @config.indent_step
+        elsif block.is_a?(FalseClass)
+          indent -= @config.indent_step
+        else
+          block = block.to_s unless block.is_a?(String)
+          if block.empty?
+            indented.push('')
+            next
+          end
+          if indent.zero?
+            indented.push(block)
+            next
+          end
+          if @config.tab_replaces_count.positive?
+            tabs = @config.tab * (indent / @config.tab_replaces_count)
+            chars = @config.indent_character * (indent % @config.tab_replaces_count)
+          else
+            tabs = ''
+            chars = @config.indent_character * indent
+          end
+          lines = block.lines(chomp: true)
+          lines.each do |line|
+            indented.push("#{tabs}#{chars}#{line}")
+          end
+        end
+      end
+      @last_indent = indent
+      indented.join(separator)
+    end
+  end
+end