Class: Confoog::Settings

Inherits:
Object
  • Object
show all
Defined in:
lib/confoog.rb

Overview

Provide an encapsulated class to access a YAML configuration file.

Examples:

require 'confoog'
settings = Confoog::Settings.new
settings[:var] = value
settings[:array] = [1, 2, 3, 4]
settings[42] = "Meaning of life"
settings[:urls] = ["https://www.mywebsite.com", "https://www.anothersite.com/a/page.html"]

settings[:urls].each do |url|
  puts url
end
# https://www.mywebsite.com
# https://www.anothersite.com/a/page.html
# => ["https://www.mywebsite.com", "https://www.anothersite.com/a/page.html"]

settings[:dont_exist]
# => nil

a_variable = 50
settings[a_variable] = {:one => "for the money", :two => "for the show", :three => "to get ready"}
settings[50]
# => {:one => "for the money", :two => "for the show", :three => "to get ready"}
settings[50][:two]
# => "for the show"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Settings

Setup the class with specified parameters or default values if any or all are absent. All parameters are optional.

Parameters:

  • options (Hash) (defaults to: {}) —

    Hash value containing any passed parameters.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/confoog.rb', line 64

def initialize(options = {})
  # merge default options to avoid ambiguity
  @options = DEFAULT_OPTIONS.merge(options)
  # set all other unset options to return false instead of Nul.
  @options.default = false

  # Hash containing any error or return from methods
  @status = Status.new(@options[:quiet], @options[:prefix])
  @location = @options[:location]
  @filename = @options[:filename]

  @config = {}

  # clear the error condition as default.
  @status.clear_error
  # make sure the file exists or can be created...
  check_exists(options)

  # if auto_load is true, automatically load from file
  load unless @options[:autoload] == false
end

Instance Attribute Details

#filename ⇒ String

Returns The configuration filename in use.

Returns:

  • (String) —

    The configuration filename in use.



55
56
57
58
59
60
61
62
63
64
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/confoog.rb', line 55

class Settings
  attr_reader :filename, :location, :status

  # rubocop:enable LineLength

  # Setup the class with specified parameters or default values if any or all
  # are absent.
  # All parameters are optional.
  # @param options [Hash] Hash value containing any passed parameters.
  def initialize(options = {})
    # merge default options to avoid ambiguity
    @options = DEFAULT_OPTIONS.merge(options)
    # set all other unset options to return false instead of Nul.
    @options.default = false

    # Hash containing any error or return from methods
    @status = Status.new(@options[:quiet], @options[:prefix])
    @location = @options[:location]
    @filename = @options[:filename]

    @config = {}

    # clear the error condition as default.
    @status.clear_error
    # make sure the file exists or can be created...
    check_exists(options)

    # if auto_load is true, automatically load from file
    load unless @options[:autoload] == false
  end

  # Return the value of the 'autosave' option.
  # @example
  #   autosave_status = settings.autosave
  #   => true
  # @param [None]
  # @return [Boolen] true if we are autosaving on change or addition.
  def autosave
    @options[:autosave]
  end

  # Change the 'autosave' option.
  # @example
  #   settings.autosave = false
  #   => false
  # @return [Boolean] The new value [true | false]
  # @param autosave [Boolean] True to send messages to console for errors.
  def autosave=(autosave)
    @options[:autosave] = autosave
  end

  # Return the value of the 'quiet' option.
  # @example
  #   is_quiet = settings.quiet
  # @param [None]
  # @return [Boolean] True if we are not writing to the console on error
  def quiet
    @status.quiet
  end

  # Change the 'quiet' option.
  # @example
  #   settings.quiet = true
  # @return [Boolean] The new value [true | false]
  # @param quiet [Boolean] True to send messages to console for errors.
  def quiet=(quiet)
    @status.quiet = quiet
  end

  # Save the entire configuration (@config) to the YAML file.
  # @example
  #   settings.save
  # @param [None]
  # @return Unspecified
  def save
    if @config.count > 0
      save_to_yaml
    else
      @status.set(errors: Status::ERR_NOT_WRITING_EMPTY_FILE)
    end
  end

  # Populate the configuration (@config) from the YAML file.
  # @param [None]
  # @example
  #   settings.load
  # @return Unspecified
  def load
    @config = YAML.load_file(config_path)
    @status.set(errors: Status::INFO_FILE_LOADED)
    if @config == false
      # console_output("Configuration file #{config_path} is empty!",
      #                OUTPUT_SEVERITY[:WARN])
      @status.set(errors: Status::ERR_NOT_LOADING_EMPTY_FILE)
    end
  rescue
    @status.set(errors: Status::ERR_CANT_LOAD)
  end

  # dummy method currently to stop changing location by caller once created,
  # @return [hash] an error flag in the ':status' variable.
  # @param [Optional] Parameter is ignored
  def location=(*)
    @status.set(errors: Status::ERR_CANT_CHANGE)
  end

  # dummy method currently to stop changing filename by caller once created,
  # @return [hash] an error flag in the ':status' variable.
  # @param optional Parameter is ignored
  def filename=(*)
    @status.set(errors: Status::ERR_CANT_CHANGE)
  end

  # Read the configuration key (key)
  # @example
  #   key = settings[:key]
  # @return [<various>] Return value depends on the type of variable stored
  def [](key)
    @config[key]
  end

  # Set a configuration key.
  # If autosave: true then will also update the config file (default is true)
  # @example
  #   settings[:key] = "Value"
  #   settings[:array] = ["first", "second", "third"]
  # @return [<various>] Returns the variable that was assigned.
  def []=(key, value)
    @config[key] = value
    # automatically save to file if this has been requested.
    save unless @options[:autosave] == false
  end

  # Returns the fully qualified path to the configuration file in use.
  # @example
  #   path = config_path
  # @return [String] Full path and filename of the configuration file.
  def config_path
    File.expand_path(File.join(@location, @filename))
  end

  private

  def save_to_yaml
    file = File.open(config_path, 'w')
    file.write(@config.to_yaml)
    file.close
  rescue
    @status.set(errors: Status::ERR_CANT_SAVE_CONFIGURATION)
  end

  def create_new_file
    File.new(config_path, 'w').close
    @status.set(config_exists: true, errors: Status::INFO_FILE_CREATED)
  rescue
    @status.set(config_exists: false, errors: Status::ERR_CANT_CREATE_FILE)
  end

  def check_exists(options)
    @status[:config_exists] = true
    return if File.exist?(config_path)

    # file does not exist so we create if requested otherwise error out
    if options[:create_file] == true
      create_new_file
    else
      @status.set(config_exists: false, errors: Status::ERR_FILE_NOT_EXIST)
    end
  end
end

#location ⇒ String

Returns The directory storing the configuration file.

Returns:

  • (String) —

    The directory storing the configuration file.



55
56
57
58
59
60
61
62
63
64
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/confoog.rb', line 55

class Settings
  attr_reader :filename, :location, :status

  # rubocop:enable LineLength

  # Setup the class with specified parameters or default values if any or all
  # are absent.
  # All parameters are optional.
  # @param options [Hash] Hash value containing any passed parameters.
  def initialize(options = {})
    # merge default options to avoid ambiguity
    @options = DEFAULT_OPTIONS.merge(options)
    # set all other unset options to return false instead of Nul.
    @options.default = false

    # Hash containing any error or return from methods
    @status = Status.new(@options[:quiet], @options[:prefix])
    @location = @options[:location]
    @filename = @options[:filename]

    @config = {}

    # clear the error condition as default.
    @status.clear_error
    # make sure the file exists or can be created...
    check_exists(options)

    # if auto_load is true, automatically load from file
    load unless @options[:autoload] == false
  end

  # Return the value of the 'autosave' option.
  # @example
  #   autosave_status = settings.autosave
  #   => true
  # @param [None]
  # @return [Boolen] true if we are autosaving on change or addition.
  def autosave
    @options[:autosave]
  end

  # Change the 'autosave' option.
  # @example
  #   settings.autosave = false
  #   => false
  # @return [Boolean] The new value [true | false]
  # @param autosave [Boolean] True to send messages to console for errors.
  def autosave=(autosave)
    @options[:autosave] = autosave
  end

  # Return the value of the 'quiet' option.
  # @example
  #   is_quiet = settings.quiet
  # @param [None]
  # @return [Boolean] True if we are not writing to the console on error
  def quiet
    @status.quiet
  end

  # Change the 'quiet' option.
  # @example
  #   settings.quiet = true
  # @return [Boolean] The new value [true | false]
  # @param quiet [Boolean] True to send messages to console for errors.
  def quiet=(quiet)
    @status.quiet = quiet
  end

  # Save the entire configuration (@config) to the YAML file.
  # @example
  #   settings.save
  # @param [None]
  # @return Unspecified
  def save
    if @config.count > 0
      save_to_yaml
    else
      @status.set(errors: Status::ERR_NOT_WRITING_EMPTY_FILE)
    end
  end

  # Populate the configuration (@config) from the YAML file.
  # @param [None]
  # @example
  #   settings.load
  # @return Unspecified
  def load
    @config = YAML.load_file(config_path)
    @status.set(errors: Status::INFO_FILE_LOADED)
    if @config == false
      # console_output("Configuration file #{config_path} is empty!",
      #                OUTPUT_SEVERITY[:WARN])
      @status.set(errors: Status::ERR_NOT_LOADING_EMPTY_FILE)
    end
  rescue
    @status.set(errors: Status::ERR_CANT_LOAD)
  end

  # dummy method currently to stop changing location by caller once created,
  # @return [hash] an error flag in the ':status' variable.
  # @param [Optional] Parameter is ignored
  def location=(*)
    @status.set(errors: Status::ERR_CANT_CHANGE)
  end

  # dummy method currently to stop changing filename by caller once created,
  # @return [hash] an error flag in the ':status' variable.
  # @param optional Parameter is ignored
  def filename=(*)
    @status.set(errors: Status::ERR_CANT_CHANGE)
  end

  # Read the configuration key (key)
  # @example
  #   key = settings[:key]
  # @return [<various>] Return value depends on the type of variable stored
  def [](key)
    @config[key]
  end

  # Set a configuration key.
  # If autosave: true then will also update the config file (default is true)
  # @example
  #   settings[:key] = "Value"
  #   settings[:array] = ["first", "second", "third"]
  # @return [<various>] Returns the variable that was assigned.
  def []=(key, value)
    @config[key] = value
    # automatically save to file if this has been requested.
    save unless @options[:autosave] == false
  end

  # Returns the fully qualified path to the configuration file in use.
  # @example
  #   path = config_path
  # @return [String] Full path and filename of the configuration file.
  def config_path
    File.expand_path(File.join(@location, @filename))
  end

  private

  def save_to_yaml
    file = File.open(config_path, 'w')
    file.write(@config.to_yaml)
    file.close
  rescue
    @status.set(errors: Status::ERR_CANT_SAVE_CONFIGURATION)
  end

  def create_new_file
    File.new(config_path, 'w').close
    @status.set(config_exists: true, errors: Status::INFO_FILE_CREATED)
  rescue
    @status.set(config_exists: false, errors: Status::ERR_CANT_CREATE_FILE)
  end

  def check_exists(options)
    @status[:config_exists] = true
    return if File.exist?(config_path)

    # file does not exist so we create if requested otherwise error out
    if options[:create_file] == true
      create_new_file
    else
      @status.set(config_exists: false, errors: Status::ERR_FILE_NOT_EXIST)
    end
  end
end

#status ⇒ Hash (readonly)

Returns A hash containing status variables.

Returns:

  • (Hash) —

    A hash containing status variables.



55
56
57
58
59
60
61
62
63
64
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/confoog.rb', line 55

class Settings
  attr_reader :filename, :location, :status

  # rubocop:enable LineLength

  # Setup the class with specified parameters or default values if any or all
  # are absent.
  # All parameters are optional.
  # @param options [Hash] Hash value containing any passed parameters.
  def initialize(options = {})
    # merge default options to avoid ambiguity
    @options = DEFAULT_OPTIONS.merge(options)
    # set all other unset options to return false instead of Nul.
    @options.default = false

    # Hash containing any error or return from methods
    @status = Status.new(@options[:quiet], @options[:prefix])
    @location = @options[:location]
    @filename = @options[:filename]

    @config = {}

    # clear the error condition as default.
    @status.clear_error
    # make sure the file exists or can be created...
    check_exists(options)

    # if auto_load is true, automatically load from file
    load unless @options[:autoload] == false
  end

  # Return the value of the 'autosave' option.
  # @example
  #   autosave_status = settings.autosave
  #   => true
  # @param [None]
  # @return [Boolen] true if we are autosaving on change or addition.
  def autosave
    @options[:autosave]
  end

  # Change the 'autosave' option.
  # @example
  #   settings.autosave = false
  #   => false
  # @return [Boolean] The new value [true | false]
  # @param autosave [Boolean] True to send messages to console for errors.
  def autosave=(autosave)
    @options[:autosave] = autosave
  end

  # Return the value of the 'quiet' option.
  # @example
  #   is_quiet = settings.quiet
  # @param [None]
  # @return [Boolean] True if we are not writing to the console on error
  def quiet
    @status.quiet
  end

  # Change the 'quiet' option.
  # @example
  #   settings.quiet = true
  # @return [Boolean] The new value [true | false]
  # @param quiet [Boolean] True to send messages to console for errors.
  def quiet=(quiet)
    @status.quiet = quiet
  end

  # Save the entire configuration (@config) to the YAML file.
  # @example
  #   settings.save
  # @param [None]
  # @return Unspecified
  def save
    if @config.count > 0
      save_to_yaml
    else
      @status.set(errors: Status::ERR_NOT_WRITING_EMPTY_FILE)
    end
  end

  # Populate the configuration (@config) from the YAML file.
  # @param [None]
  # @example
  #   settings.load
  # @return Unspecified
  def load
    @config = YAML.load_file(config_path)
    @status.set(errors: Status::INFO_FILE_LOADED)
    if @config == false
      # console_output("Configuration file #{config_path} is empty!",
      #                OUTPUT_SEVERITY[:WARN])
      @status.set(errors: Status::ERR_NOT_LOADING_EMPTY_FILE)
    end
  rescue
    @status.set(errors: Status::ERR_CANT_LOAD)
  end

  # dummy method currently to stop changing location by caller once created,
  # @return [hash] an error flag in the ':status' variable.
  # @param [Optional] Parameter is ignored
  def location=(*)
    @status.set(errors: Status::ERR_CANT_CHANGE)
  end

  # dummy method currently to stop changing filename by caller once created,
  # @return [hash] an error flag in the ':status' variable.
  # @param optional Parameter is ignored
  def filename=(*)
    @status.set(errors: Status::ERR_CANT_CHANGE)
  end

  # Read the configuration key (key)
  # @example
  #   key = settings[:key]
  # @return [<various>] Return value depends on the type of variable stored
  def [](key)
    @config[key]
  end

  # Set a configuration key.
  # If autosave: true then will also update the config file (default is true)
  # @example
  #   settings[:key] = "Value"
  #   settings[:array] = ["first", "second", "third"]
  # @return [<various>] Returns the variable that was assigned.
  def []=(key, value)
    @config[key] = value
    # automatically save to file if this has been requested.
    save unless @options[:autosave] == false
  end

  # Returns the fully qualified path to the configuration file in use.
  # @example
  #   path = config_path
  # @return [String] Full path and filename of the configuration file.
  def config_path
    File.expand_path(File.join(@location, @filename))
  end

  private

  def save_to_yaml
    file = File.open(config_path, 'w')
    file.write(@config.to_yaml)
    file.close
  rescue
    @status.set(errors: Status::ERR_CANT_SAVE_CONFIGURATION)
  end

  def create_new_file
    File.new(config_path, 'w').close
    @status.set(config_exists: true, errors: Status::INFO_FILE_CREATED)
  rescue
    @status.set(config_exists: false, errors: Status::ERR_CANT_CREATE_FILE)
  end

  def check_exists(options)
    @status[:config_exists] = true
    return if File.exist?(config_path)

    # file does not exist so we create if requested otherwise error out
    if options[:create_file] == true
      create_new_file
    else
      @status.set(config_exists: false, errors: Status::ERR_FILE_NOT_EXIST)
    end
  end
end

Instance Method Details

#[](key) ⇒ <various>

Read the configuration key (key)

Examples:

key = settings[:key]

Returns:

  • (<various>) —

    Return value depends on the type of variable stored



172
173
174
 
# File 'lib/confoog.rb', line 172

def [](key)
  @config[key]
end

#[]=(key, value) ⇒ <various>

Set a configuration key. If autosave: true then will also update the config file (default is true)

Examples:

settings[:key] = "Value"
settings[:array] = ["first", "second", "third"]

Returns:

  • (<various>) —

    Returns the variable that was assigned.



182
183
184
185
186
 
# File 'lib/confoog.rb', line 182

def []=(key, value)
  @config[key] = value
  # automatically save to file if this has been requested.
  save unless @options[:autosave] == false
end

#autosave ⇒ Boolen

Return the value of the ‘autosave’ option.

Examples:

autosave_status = settings.autosave
=> true

Parameters:

  • (None)

Returns:

  • (Boolen) —

    true if we are autosaving on change or addition.



92
93
94
 
# File 'lib/confoog.rb', line 92

def autosave
  @options[:autosave]
end

#autosave=(autosave) ⇒ Boolean

Change the ‘autosave’ option.

Examples:

settings.autosave = false
=> false

Parameters:

  • autosave (Boolean) —

    True to send messages to console for errors.

Returns:

  • (Boolean) —

    The new value [true | false]



102
103
104
 
# File 'lib/confoog.rb', line 102

def autosave=(autosave)
  @options[:autosave] = autosave
end

#config_path ⇒ String

Returns the fully qualified path to the configuration file in use.

Examples:

path = config_path

Returns:

  • (String) —

    Full path and filename of the configuration file.



192
193
194
 
# File 'lib/confoog.rb', line 192

def config_path
  File.expand_path(File.join(@location, @filename))
end

#load ⇒ Object

Populate the configuration (@config) from the YAML file.

Examples:

settings.load

Parameters:

  • (None)

Returns:

  • Unspecified



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/confoog.rb', line 142

def load
  @config = YAML.load_file(config_path)
  @status.set(errors: Status::INFO_FILE_LOADED)
  if @config == false
    # console_output("Configuration file #{config_path} is empty!",
    #                OUTPUT_SEVERITY[:WARN])
    @status.set(errors: Status::ERR_NOT_LOADING_EMPTY_FILE)
  end
rescue
  @status.set(errors: Status::ERR_CANT_LOAD)
end

#quiet ⇒ Boolean

Return the value of the ‘quiet’ option.

Examples:

is_quiet = settings.quiet

Parameters:

  • (None)

Returns:

  • (Boolean) —

    True if we are not writing to the console on error



111
112
113
 
# File 'lib/confoog.rb', line 111

def quiet
  @status.quiet
end

#quiet=(quiet) ⇒ Boolean

Change the ‘quiet’ option.

Examples:

settings.quiet = true

Parameters:

  • quiet (Boolean) —

    True to send messages to console for errors.

Returns:

  • (Boolean) —

    The new value [true | false]



120
121
122
 
# File 'lib/confoog.rb', line 120

def quiet=(quiet)
  @status.quiet = quiet
end

#save ⇒ Object

Save the entire configuration (@config) to the YAML file.

Examples:

settings.save

Parameters:

  • (None)

Returns:

  • Unspecified



129
130
131
132
133
134
135
 
# File 'lib/confoog.rb', line 129

def save
  if @config.count > 0
    save_to_yaml
  else
    @status.set(errors: Status::ERR_NOT_WRITING_EMPTY_FILE)
  end
end