Class: Lich::Common::PathNavigator

Inherits:
Object
  • Object
show all
Defined in:
documented/common/settings/path_navigator.rb

Overview

Path navigator to encapsulate path navigation logic

This class provides methods to manage and navigate through a path structure. It interacts with a database adapter to retrieve and manipulate settings.

Examples:

Creating a path navigator

navigator = Lich::Common::PathNavigator.new(db_adapter)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(db_adapter) ⇒ PathNavigator

Returns a new instance of PathNavigator.



12
13
14
15
 
# File 'documented/common/settings/path_navigator.rb', line 12

def initialize(db_adapter)
  @db_adapter = db_adapter
  @path = []
end

Instance Attribute Details

#path ⇒ Object (readonly)

Returns the value of attribute path.



17
18
19
 
# File 'documented/common/settings/path_navigator.rb', line 17

def path
  @path
end

Instance Method Details

Navigate to the node at “path” (or @path if nil). Returns [target, root]

This method navigates through the path segments to find the target node. It can create missing containers if specified.

Examples:

Navigating to a path

target, root = navigator.navigate_to_path("my_script", true, "GS3:CharName", ["level1", "level2"])

Parameters:

  • script_name (String) —

    the script namespace (e.g., Script.current.name)

  • create_missing (Boolean) (defaults to: true) —

    whether to create intermediate containers

  • scope (String) (defaults to: ":") —

    settings scope (e.g., “GS3:CharName”)

  • path (Array, nil) (defaults to: nil) —

    path segments; integers index arrays, symbols/strings index hashes

Returns:

  • (Array(Object, Hash|Array)) —
    target_node, root_object

Raises:

  • ArgumentError if an invalid array index is encountered



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'documented/common/settings/path_navigator.rb', line 65

def navigate_to_path(script_name, create_missing = true, scope = ":", path = nil)
  work_path = path ? Array(path) : @path
  root = @db_adapter.get_settings(script_name, scope)
  return [root, root] if work_path.empty?

  target = root
  work_path.each_with_index do |key, idx|
    next_key = work_path[idx + 1]

    if target.is_a?(Hash)
      if target.key?(key)
        target = target[key]
      elsif create_missing
        target[key] = next_key.is_a?(Integer) ? [] : {}
        target = target[key]
      else
        return [nil, root]
      end

    elsif target.is_a?(Array)
      unless key.is_a?(Integer) && key >= 0
        return [nil, root] unless create_missing
        raise ArgumentError, "Array index must be a non-negative Integer (got: #{key.inspect})"
      end

      if key >= target.length
        (target.length..key).each { target << nil }
      end

      if target[key].nil? && create_missing
        target[key] = next_key.is_a?(Integer) ? [] : {}
      end
      return [nil, root] if target[key].nil? && !create_missing
      target = target[key]

    else
      # Non-container encountered mid-path; only replace if allowed.
      return [nil, root] unless create_missing
      replacement = next_key.is_a?(Integer) ? [] : {}
      target = replacement
    end
  end

  [target, root]
end

#reset_path ⇒ void

This method returns an undefined value.

Resets the current path to an empty state.

This method clears the existing path.

Examples:

Resetting the path

navigator.reset_path


36
37
38
 
# File 'documented/common/settings/path_navigator.rb', line 36

def reset_path
  @path = []
end

#reset_path_and_return(value) ⇒ Object

Resets the path and returns a specified value.

This method clears the current path and returns the provided value.

Examples:

Resetting the path and returning a value

result = navigator.reset_path_and_return("default")

Parameters:

  • value (Object) —

    The value to return after resetting the path.

Returns:

  • (Object) —

    The provided value.



47
48
49
50
 
# File 'documented/common/settings/path_navigator.rb', line 47

def reset_path_and_return(value)
  reset_path
  value
end

#set_path(new_path) ⇒ void

This method returns an undefined value.

Allow external callers to drive the effective path

This method sets the current path to the provided new path.

Examples:

Setting a new path

navigator.set_path(["level1", "level2"])

Parameters:

  • new_path (Array, Object) —

    The new path to set, can be an array or a single object.



26
27
28
 
# File 'documented/common/settings/path_navigator.rb', line 26

def set_path(new_path)
  @path = Array(new_path).dup
end