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.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/confoog.rb', line 92

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 = {}
  @location = @options[:location]
  @filename = @options[:filename]

  @config = {}

  # clear the error condition as default.
  status_set(errors: ERR_NO_ERROR)
  # make sure the file exists or can be created...
  check_exists(options)
end

Instance Attribute Details

#filename ⇒ String

Returns The configuration filename in use.

Returns:

  • (String) —

    The configuration filename in use.



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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/confoog.rb', line 83

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 = {}
    @location = @options[:location]
    @filename = @options[:filename]

    @config = {}

    # clear the error condition as default.
    status_set(errors: ERR_NO_ERROR)
    # make sure the file exists or can be created...
    check_exists(options)
  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
    @options[: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)
    @options[: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
      console_output("Not saving empty configuration data to #{config_path}",
                     OUTPUT_SEVERITY[:WARN])
      status_set(errors: 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: INFO_FILE_LOADED)
    if @config == false
      console_output("Configuration file #{config_path} is empty!",
                     OUTPUT_SEVERITY[:WARN])
      status_set(errors: ERR_NOT_LOADING_EMPTY_FILE)
    end
  rescue
    console_output("Cannot load configuration data from #{config_path}",
                   OUTPUT_SEVERITY[:ERR])
  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: ERR_CANT_CHANGE)
    console_output('Cannot change file location after creation',
                   OUTPUT_SEVERITY[:WARN])
  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: ERR_CANT_CHANGE)
    console_output('Cannot change filename after creation',
                   OUTPUT_SEVERITY[:WARN])
  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
  # @example
  #   settings[:key] = "Value"
  #   settings[:array] = ["first", "second", "third"]
  # @return [<various>] Returns the variable that was assigned.
  def []=(key, value)
    @config[key] = value
  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 console_output(message, severity)
    return unless @options[:quiet] == false
    $stderr.puts "#{@options[:prefix]} : #{severity} - #{message}"
  end

  def save_to_yaml
    file = File.open(config_path, 'w')
    file.write(@config.to_yaml)
    file.close
  rescue
    status_set(errors: ERR_CANT_SAVE_CONFIGURATION)
    console_output("Cannot save configuration data to #{config_path}",
                   OUTPUT_SEVERITY[:ERR])
  end

  def create_new_file
    File.new(config_path, 'w').close
    status_set(config_exists: true, errors: INFO_FILE_CREATED)
  rescue
    status_set(config_exists: false, errors: ERR_CANT_CREATE_FILE)
    console_output('Cannot create the specified Configuration file!',
                   OUTPUT_SEVERITY[:ERR])
  end

  def status_set(status)
    status.each do |key, value|
      @status[key] = value
    end
  end

  def check_exists(options)
    status_set(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: ERR_FILE_NOT_EXIST)
      console_output('The specified Configuration file does not exist.',
                     OUTPUT_SEVERITY[:ERR])
    end
  end
end

#location ⇒ String

Returns The directory storing the configuration file.

Returns:

  • (String) —

    The directory storing the configuration file.



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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/confoog.rb', line 83

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 = {}
    @location = @options[:location]
    @filename = @options[:filename]

    @config = {}

    # clear the error condition as default.
    status_set(errors: ERR_NO_ERROR)
    # make sure the file exists or can be created...
    check_exists(options)
  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
    @options[: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)
    @options[: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
      console_output("Not saving empty configuration data to #{config_path}",
                     OUTPUT_SEVERITY[:WARN])
      status_set(errors: 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: INFO_FILE_LOADED)
    if @config == false
      console_output("Configuration file #{config_path} is empty!",
                     OUTPUT_SEVERITY[:WARN])
      status_set(errors: ERR_NOT_LOADING_EMPTY_FILE)
    end
  rescue
    console_output("Cannot load configuration data from #{config_path}",
                   OUTPUT_SEVERITY[:ERR])
  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: ERR_CANT_CHANGE)
    console_output('Cannot change file location after creation',
                   OUTPUT_SEVERITY[:WARN])
  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: ERR_CANT_CHANGE)
    console_output('Cannot change filename after creation',
                   OUTPUT_SEVERITY[:WARN])
  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
  # @example
  #   settings[:key] = "Value"
  #   settings[:array] = ["first", "second", "third"]
  # @return [<various>] Returns the variable that was assigned.
  def []=(key, value)
    @config[key] = value
  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 console_output(message, severity)
    return unless @options[:quiet] == false
    $stderr.puts "#{@options[:prefix]} : #{severity} - #{message}"
  end

  def save_to_yaml
    file = File.open(config_path, 'w')
    file.write(@config.to_yaml)
    file.close
  rescue
    status_set(errors: ERR_CANT_SAVE_CONFIGURATION)
    console_output("Cannot save configuration data to #{config_path}",
                   OUTPUT_SEVERITY[:ERR])
  end

  def create_new_file
    File.new(config_path, 'w').close
    status_set(config_exists: true, errors: INFO_FILE_CREATED)
  rescue
    status_set(config_exists: false, errors: ERR_CANT_CREATE_FILE)
    console_output('Cannot create the specified Configuration file!',
                   OUTPUT_SEVERITY[:ERR])
  end

  def status_set(status)
    status.each do |key, value|
      @status[key] = value
    end
  end

  def check_exists(options)
    status_set(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: ERR_FILE_NOT_EXIST)
      console_output('The specified Configuration file does not exist.',
                     OUTPUT_SEVERITY[:ERR])
    end
  end
end

#status ⇒ Hash (readonly)

Returns A hash containing status variables.

Returns:

  • (Hash) —

    A hash containing status variables.



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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/confoog.rb', line 83

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 = {}
    @location = @options[:location]
    @filename = @options[:filename]

    @config = {}

    # clear the error condition as default.
    status_set(errors: ERR_NO_ERROR)
    # make sure the file exists or can be created...
    check_exists(options)
  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
    @options[: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)
    @options[: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
      console_output("Not saving empty configuration data to #{config_path}",
                     OUTPUT_SEVERITY[:WARN])
      status_set(errors: 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: INFO_FILE_LOADED)
    if @config == false
      console_output("Configuration file #{config_path} is empty!",
                     OUTPUT_SEVERITY[:WARN])
      status_set(errors: ERR_NOT_LOADING_EMPTY_FILE)
    end
  rescue
    console_output("Cannot load configuration data from #{config_path}",
                   OUTPUT_SEVERITY[:ERR])
  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: ERR_CANT_CHANGE)
    console_output('Cannot change file location after creation',
                   OUTPUT_SEVERITY[:WARN])
  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: ERR_CANT_CHANGE)
    console_output('Cannot change filename after creation',
                   OUTPUT_SEVERITY[:WARN])
  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
  # @example
  #   settings[:key] = "Value"
  #   settings[:array] = ["first", "second", "third"]
  # @return [<various>] Returns the variable that was assigned.
  def []=(key, value)
    @config[key] = value
  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 console_output(message, severity)
    return unless @options[:quiet] == false
    $stderr.puts "#{@options[:prefix]} : #{severity} - #{message}"
  end

  def save_to_yaml
    file = File.open(config_path, 'w')
    file.write(@config.to_yaml)
    file.close
  rescue
    status_set(errors: ERR_CANT_SAVE_CONFIGURATION)
    console_output("Cannot save configuration data to #{config_path}",
                   OUTPUT_SEVERITY[:ERR])
  end

  def create_new_file
    File.new(config_path, 'w').close
    status_set(config_exists: true, errors: INFO_FILE_CREATED)
  rescue
    status_set(config_exists: false, errors: ERR_CANT_CREATE_FILE)
    console_output('Cannot create the specified Configuration file!',
                   OUTPUT_SEVERITY[:ERR])
  end

  def status_set(status)
    status.each do |key, value|
      @status[key] = value
    end
  end

  def check_exists(options)
    status_set(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: ERR_FILE_NOT_EXIST)
      console_output('The specified Configuration file does not exist.',
                     OUTPUT_SEVERITY[:ERR])
    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



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

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

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

Set a configuration key

Examples:

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

Returns:

  • (<various>) —

    Returns the variable that was assigned.



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

def []=(key, value)
  @config[key] = value
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.



201
202
203
 
# File 'lib/confoog.rb', line 201

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



149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/confoog.rb', line 149

def load
  @config = YAML.load_file(config_path)
  status_set(errors: INFO_FILE_LOADED)
  if @config == false
    console_output("Configuration file #{config_path} is empty!",
                   OUTPUT_SEVERITY[:WARN])
    status_set(errors: ERR_NOT_LOADING_EMPTY_FILE)
  end
rescue
  console_output("Cannot load configuration data from #{config_path}",
                 OUTPUT_SEVERITY[:ERR])
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



116
117
118
 
# File 'lib/confoog.rb', line 116

def quiet
  @options[: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]



125
126
127
 
# File 'lib/confoog.rb', line 125

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

#save ⇒ Object

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

Examples:

settings.save

Parameters:

  • (None)

Returns:

  • Unspecified



134
135
136
137
138
139
140
141
142
 
# File 'lib/confoog.rb', line 134

def save
  if @config.count > 0
    save_to_yaml
  else
    console_output("Not saving empty configuration data to #{config_path}",
                   OUTPUT_SEVERITY[:WARN])
    status_set(errors: ERR_NOT_WRITING_EMPTY_FILE)
  end
end