configurability 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90db460a224cb22dc552c50e39a5f78af6599d01502dfc97a72c52afcbfb4dcf
-  data.tar.gz: a8d656fd6844cc7df9d04248d9418962ff286004f652185a517fc834e302dab4
+  metadata.gz: a3d72bd8604379adbc7d7cc9fcaad9cbf5e05f506b4d5f2b91bcee03b31d980d
+  data.tar.gz: 82d58d94493be733dd8141dce382c644667c439bddfc29e3656c93938695dbd9
 SHA512:
-  metadata.gz: fd4959e2e09463fe43ea49216b53f2d98b211183fe7b2cf294069a241c1983cb8c4b9573daa1d677c79e35153a26c323aa6ea26edcd88c78a6ce8690df3d0e8b
-  data.tar.gz: 1b87c87a150ab5604ab0b370e9429aec1d5ce9325998f305ad12e6352be187421e6bb8821f08c6f479bf68f26338e77c9a1790a8d99d4cca8292899e6ca8691d
+  metadata.gz: 0ad8db05f08251e67fb781321f3c245d26f4619a0a5b1e506b1c90f360241a9c881362c27f980b243fffd535baaeeb50136f8b7f30e18265a63b22bba77c2ef5
+  data.tar.gz: d572f4feb1372d71b3676f1e128dfafb38b3b3ccf947873385e3e6d87d61321fee5c04c2e12e2244fcd337cc9c989c9c3ec6f59c6610e567dd4609bd174bff85

data/History.md

@@ -2,6 +2,19 @@
 
 ---
 
+## v5.0.0 [2025-01-29] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Detect and raise an error when declaring a setting if it
+  would have replaced an existing method
+- Add setting aliases
+- Add a `setting_default` declaration for overriding the
+  settings defaults for subclasses.
+- Add an accessor that can fetch embedded comments for
+  DSL-style settings
+
+
 ## v4.2.0 [2020-12-28] Michael Granger <ged@faeriemud.org>
 
 Improvements:

data/README.md

@@ -32,7 +32,7 @@ single action.
 
     # user.rb
     require 'configurability'
-    
+
     class User
         extend Configurability
 
@@ -104,7 +104,7 @@ You can configure the `Database` class (and all other objects extended with
 Configurability) with it like so:
 
     require 'configurability/config'
-    
+
     config = Configurability::Config.load( 'config.yml' )
     Configurability.configure_objects( config )
 
@@ -153,6 +153,56 @@ alongside its getter and setter:
     Mailer.use_whitelist?
     # => true
 
+If you want additional ways to check/set the setting, you can provide one or
+more aliases for a settings which will cause additional setting methods to be
+created:
+
+    class Server
+      extend Configurability
+      configurability( :server ) do
+        setting :environment, default: :development, alias: :host_env
+      end
+    end
+
+    Server.environment = :staging
+    Server.host_env
+    # => :staging
+
+
+### Inheritance
+
+Subclasses inherit settings from their parents, but their setting values are
+independent:
+
+    class Server
+      extend Configurability
+      configurability( :server ) do
+        setting :host, default: 'localhost'
+        setting :port, default: nil
+      end
+    end
+
+    class MailServer < Server; end
+
+    Server.host = '0.0.0.0'
+    MailServer.host
+    # => 'localhost'
+
+If you wish to override the default setting value of the parent class, you can't
+re-declare the setting but you can explicitly set the default:
+
+    class WebServer < Server
+        configurability( :server ) do
+          setting_default :port, 80
+        end
+    end
+
+    Server.port
+    # => nil
+
+    WebServer.port
+    # => 80
+
 
 ### More Details
 
@@ -374,8 +424,8 @@ write the modified config back out to the same file:
 then dump it to a YAML string:
 
     config.dump
-    # => "--- \ndatabase: \n  development: \n    adapter: sqlite3\n  
-      database: db/dev.db\n    pool: 5\n    timeout: 5000\n  testing: \n  
+    # => "--- \ndatabase: \n  development: \n    adapter: sqlite3\n
+      database: db/dev.db\n    pool: 5\n    timeout: 5000\n  testing: \n
       adapter: mysql\n    database: t_fixedassets\n    pool: 2\n    timeout:
       5000\n  production: \n    adapter: postgres\n    database:
       fixedassets\n    pool: 25\n    timeout: 50\nldap: \n  uri:
@@ -443,7 +493,7 @@ and generate the API documentation.
 
 ## License
 
-Copyright (c) 2010-2020 Michael Granger and Mahlon E. Smith
+Copyright (c) 2010-2025 Michael Granger and Mahlon E. Smith
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/configurability/setting_installer.rb

@@ -1,5 +1,6 @@
 # -*- ruby -*-
-#encoding: utf-8
+
+require 'prism'
 
 require 'loggability'
 require 'configurability' unless defined?( Configurability )
@@ -17,6 +18,7 @@ class Configurability::SettingInstaller
 	### constants to the specified +target+ object.
 	def initialize( target )
 		@target = target
+		@lexed = nil
 	end
 
 
@@ -28,8 +30,17 @@ class Configurability::SettingInstaller
 	### Declare a config setting with the specified +name+.
 	def setting( name, **options, &block )
 		self.log.debug "  adding %s setting to %p" % [ name, self.target ]
+
+		options[:alias] = Array( options[:alias] )
+		self.add_comment_accessor( name, options )
 		self.add_setting_accessors( name, options, &block )
-		self.add_default( name, options )
+		self.add_default( name, options[:default] )
+	end
+
+
+	### Declare a new default for the setting with the specified +name+.
+	def setting_default( name, new_default )
+		self.add_default( name, new_default )
 	end
 
 
@@ -39,6 +50,8 @@ class Configurability::SettingInstaller
 
 	### Add accessors with the specified +name+ to the target.
 	def add_setting_accessors( name, options, &writer_hook )
+		self.check_for_duplicates( name, options )
+
 		if options[:use_class_vars]
 			self.target.class_variable_set( "@@#{name}", nil )
 		else
@@ -47,13 +60,58 @@ class Configurability::SettingInstaller
 
 		reader = self.make_setting_reader( name, options )
 		writer = self.make_setting_writer( name, options, &writer_hook )
+		predicate = self.make_setting_predicate( name, options )
+		names = [ name ] + options[:alias]
+
+		names.each do |setting_name|
+			self.target.define_singleton_method( "#{setting_name}", &reader )
+			self.target.define_singleton_method( "#{setting_name}=", &writer )
+			self.target.define_singleton_method( "#{setting_name}?", &predicate ) if
+				options[:predicate]
+		end
+	end
+
+
+	### Create a reader that returns any raw comments found immediately above the
+	### specified +name+.
+	def add_comment_accessor( name, options )
+		# The source file with the configurablity block.
+		loc = caller_locations( 2, 1 ).first
 
-		self.target.define_singleton_method( "#{name}", &reader )
-		self.target.define_singleton_method( "#{name}=", &writer )
+		@lexed ||= Prism.lex_file( loc.path ).value
+		comments = @lexed.
+			take_while{|node| node.first.location.start_line < loc.lineno }.
+			reverse_each.
+			take_while{|node| node.first.type == :COMMENT }.
+			reverse_each.
+			map{|node| node.first.value }.
+			join
 
-		if options[:predicate]
-			predicate = self.make_setting_predicate( name, options )
-			self.target.define_singleton_method( "#{name}?", &predicate )
+		if options[:use_class_vars]
+			self.target.class_variable_set( "@@#{name}_comments", comments )
+		else
+			self.target.instance_variable_set( "@#{name}_comments", comments )
+		end
+
+		reader = self.make_setting_reader( "#{name}_comments", options )
+		self.target.define_singleton_method( "#{name}_comments", &reader )
+	end
+
+
+	### Check that there are not already accessors for the setting with the given +name+
+	### and +options+.
+	def check_for_duplicates( name, options )
+		names = [ name.to_sym ] + options[:alias]
+
+		names.each do |method_name|
+			raise ScriptError, "setting %p collides with method #%s" % [ name, method_name ] if
+				self.target.singleton_methods.include?( name )
+			raise ScriptError, "setting %p collides with method #%s=" % [ name, method_name ] if
+				self.target.singleton_methods.include?( "#{method_name}=".to_sym )
+			if options[:predicate]
+				raise ScriptError, "setting %p collides with method #%s?" % [ name, method_name ] if
+					self.target.singleton_methods.include?( "#{method_name}?".to_sym )
+			end
 		end
 	end
 
@@ -110,9 +168,7 @@ class Configurability::SettingInstaller
 
 	### Add a default for +name+ to the CONFIG_DEFAULTS constant of the target, creating
 	### it if necessary.
-	def add_default( name, options )
-		default_value = options[ :default ]
-
+	def add_default( name, default_value )
 		self.target.send( "#{name}=", default_value )
 		if self.target.respond_to?( :const_defined? )
 			defaults = if self.target.const_defined?( :CONFIG_DEFAULTS, false )

data/lib/configurability.rb

@@ -14,7 +14,7 @@ module Configurability
 
 
 	# Library version constant
-	VERSION = '4.2.0'
+	VERSION = '5.0.0'
 
 	# Version-control revision constant
 	REVISION = %q$Revision$

data/spec/configurability_spec.rb

@@ -618,6 +618,95 @@ describe Configurability do
 		end
 
 
+		it "allows a setting to be declared with a single alias" do
+			mod.configurability( :testconfig ) do
+				setting :environment, alias: :env, default: 'development'
+			end
+
+			expect {
+				mod.environment = 'production'
+			}.to change { mod.environment }.
+				from( 'development' ).
+				to( 'production' )
+
+			expect {
+				mod.env = 'staging'
+			}.to change { mod.environment }.
+				from( 'production' ).
+				to( 'staging' )
+
+			expect( mod.env ).to eq( 'staging' )
+
+			expect( mod.defaults ).to include(
+				environment: 'development',
+			)
+			expect( mod.defaults ).not_to include( :env )
+		end
+
+
+		it "allows a setting to be declared with multiple aliases" do
+			mod.configurability( :testconfig ) do
+				setting :environment, alias: [:env, :host], default: 'development'
+			end
+
+			expect {
+				mod.environment = 'production'
+			}.to change { mod.environment }.
+				from( 'development' ).
+				to( 'production' )
+
+			expect {
+				mod.env = 'staging'
+			}.to change { mod.environment }.
+				from( 'production' ).
+				to( 'staging' )
+
+			expect {
+				mod.host = 'development'
+			}.to change { mod.environment }.
+				from( 'staging' ).
+				to( 'development' )
+
+			expect( mod.env ).to eq( 'development' )
+			expect( mod.host ).to eq( 'development' )
+
+			expect( mod.defaults ).to include(
+				environment: 'development',
+			)
+			expect( mod.defaults ).not_to include( :env )
+		end
+
+
+		it "errors when declaring duplicate settings" do
+			expect {
+				mod.configurability( :testconfig ) do
+					setting :environment, default: 'development'
+					setting :environment, default: 'production'
+				end
+			}.to raise_error( ScriptError, /collides with method/i )
+		end
+
+
+		it "errors when declaring an alias that clobbers an existing setting" do
+			expect {
+				mod.configurability( :testconfig ) do
+					setting :environment, default: 'development'
+					setting :env, alias: :environment, default: 'production'
+				end
+			}.to raise_error( ScriptError, /collides with method/i )
+		end
+
+
+		it "errors when declaring an alias that clobbers an existing alias" do
+			expect {
+				mod.configurability( :testconfig ) do
+					setting :host, alias: :environment, default: 'development'
+					setting :env, alias: :environment, default: 'production'
+				end
+			}.to raise_error( ScriptError, /collides with method/i )
+		end
+
+
 		it "installs the current config after it's done if it's already loaded" do
 			config = OpenStruct.new( testconfig: {
 				environment: 'production',
@@ -667,7 +756,7 @@ describe Configurability do
 		end
 
 
-		it "supports inheritance of defaults" do
+		it "supports overriding defaults for child classes" do
 			parent_class = Class.new
 			parent_class.extend( Configurability )
 			parent_class.configurability( :testconfig ) do
@@ -676,7 +765,7 @@ describe Configurability do
 
 			child_class = Class.new( parent_class )
 			child_class.configurability( :testconfig ) do
-				setting :environment, default: :staging
+				setting_default :environment, :staging
 				setting :apikey, default: 'foom'
 			end
 
@@ -688,6 +777,25 @@ describe Configurability do
 		end
 
 
+		it "uses the setting block for setting up subclass defaults" do
+			superclass = Class.new
+			superclass.extend( described_class )
+			superclass.configurability( :testconfig ) do
+				setting :data_dir, default: 'this/that' do |dir|
+					Pathname( dir )
+				end
+			end
+
+			subclass = Class.new( superclass )
+			subclass.configurability( :testconfig ) do
+				setting_default :data_dir, 'an/other/place'
+			end
+
+			expect( subclass.data_dir ).to be_a( Pathname )
+			expect( subclass.data_dir.to_s ).to eq( 'an/other/place' )
+		end
+
+
 		it "allows the use of class variables instead of class-instance variables for settings on a Class" do
 			superclass = Class.new
 			superclass.extend( Configurability )
@@ -743,6 +851,29 @@ describe Configurability do
 			}.to change { mod.use_whitelist? }.from( false ).to( true )
 		end
 
+
+		it "can parse and recall comments for a setting" do
+			mod.configurability( :testconfig ) do
+				setting :use_whitelist
+
+				# Set the runtime environment
+				setting :environment
+
+				##
+				# A multiline example
+				# to illustrate comments are
+				# unmolested.
+				setting :apikey do |key|
+					raise "Invalid API key!" unless key.nil? || key.to_s =~ /\A\p{Xdigit}{32}\z/
+					key
+				end
+			end
+
+			expect( mod.use_whitelist_comments ).to be_empty
+			expect( mod.environment_comments ).to match( /^# Set the runtime environment$/ )
+			expect( mod.apikey_comments.count("\n") ).to eq( 4 )
+			expect( mod.apikey_comments ).to match( /comments are\n# unmolested/m )
+		end
 	end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: configurability
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Michael Granger
@@ -11,30 +11,32 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIID+DCCAmCgAwIBAgIBAzANBgkqhkiG9w0BAQsFADAiMSAwHgYDVQQDDBdnZWQv
-  REM9RmFlcmllTVVEL0RDPW9yZzAeFw0yMDEyMjQyMDU1MjlaFw0yMTEyMjQyMDU1
-  MjlaMCIxIDAeBgNVBAMMF2dlZC9EQz1GYWVyaWVNVUQvREM9b3JnMIIBojANBgkq
-  hkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAvyVhkRzvlEs0fe7145BYLfN6njX9ih5H
-  L60U0p0euIurpv84op9CNKF9tx+1WKwyQvQP7qFGuZxkSUuWcP/sFhDXL1lWUuIl
-  M4uHbGCRmOshDrF4dgnBeOvkHr1fIhPlJm5FO+Vew8tSQmlDsosxLUx+VB7DrVFO
-  5PU2AEbf04GGSrmqADGWXeaslaoRdb1fu/0M5qfPTRn5V39sWD9umuDAF9qqil/x
-  Sl6phTvgBrG8GExHbNZpLARd3xrBYLEFsX7RvBn2UPfgsrtvpdXjsHGfpT3IPN+B
-  vQ66lts4alKC69TE5cuKasWBm+16A4aEe3XdZBRNmtOu/g81gvwA7fkJHKllJuaI
-  dXzdHqq+zbGZVSQ7pRYHYomD0IiDe1DbIouFnPWmagaBnGHwXkDT2bKKP+s2v21m
-  ozilJg4aar2okb/RA6VS87o+d7g6LpDDMMQjH4G9OPnJENLdhu8KnPw/ivSVvQw7
-  N2I4L/ZOIe2DIVuYH7aLHfjZDQv/mNgpAgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYD
-  VR0PBAQDAgSwMB0GA1UdDgQWBBRyjf55EbrHagiRLqt5YAd3yb8k4DANBgkqhkiG
-  9w0BAQsFAAOCAYEAMYegZanJi8zq7QKPT7wqXefX4C88I5JWeBHR3PvvWK0CwyMV
-  peyiu5I13w/lYX+HUZjE4qsSpJMJFXWl4WZCOo+AMprOcf0PxfuJpxCej5D4tavf
-  vRfhahSw7XJrcZih/3J+/UgoH7R05MJ+8LTcy3HGrB3a0vTafjm8OY7Xpa0LJDoN
-  JDqxK321VIHyTibbKeA1hWSE6ljlQDvFbTqiCj3Ulp1jTv3TOlvRl8fqcfhxUJI0
-  +5Q82jJODjEN+GaWs0V+NlrbU94cXwS2PH5dXogftB5YYA5Ex8A0ikZ73xns4Hdo
-  XxdLdd92F5ovxA23j/rKe/IDwqr6FpDkU3nPXH/Qp0TVGv9zZnVJc/Z6ChkuWj8z
-  pW7JAyyiiHZgKKDReDrA2LA7Zs3o/7KA6UtUH0FHf8LYhcK+pfHk6RtjRe65ffw+
-  MCh97sQ/Z/MOusb5+QddBmB+k8EicXyGNl4b5L4XpL7fIQu+Y96TB3JEJlShxFD9
-  k9FjI4d9EP54gS/4
+  MIIEbDCCAtSgAwIBAgIBATANBgkqhkiG9w0BAQsFADA+MQwwCgYDVQQDDANnZWQx
+  GTAXBgoJkiaJk/IsZAEZFglGYWVyaWVNVUQxEzARBgoJkiaJk/IsZAEZFgNvcmcw
+  HhcNMjUwMTAxMDMzMTA5WhcNMjYwMTAxMDMzMTA5WjA+MQwwCgYDVQQDDANnZWQx
+  GTAXBgoJkiaJk/IsZAEZFglGYWVyaWVNVUQxEzARBgoJkiaJk/IsZAEZFgNvcmcw
+  ggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQC/JWGRHO+USzR97vXjkFgt
+  83qeNf2KHkcvrRTSnR64i6um/ziin0I0oX23H7VYrDJC9A/uoUa5nGRJS5Zw/+wW
+  ENcvWVZS4iUzi4dsYJGY6yEOsXh2CcF46+QevV8iE+UmbkU75V7Dy1JCaUOyizEt
+  TH5UHsOtUU7k9TYARt/TgYZKuaoAMZZd5qyVqhF1vV+7/Qzmp89NGflXf2xYP26a
+  4MAX2qqKX/FKXqmFO+AGsbwYTEds1mksBF3fGsFgsQWxftG8GfZQ9+Cyu2+l1eOw
+  cZ+lPcg834G9DrqW2zhqUoLr1MTly4pqxYGb7XoDhoR7dd1kFE2a067+DzWC/ADt
+  +QkcqWUm5oh1fN0eqr7NsZlVJDulFgdiiYPQiIN7UNsii4Wc9aZqBoGcYfBeQNPZ
+  soo/6za/bWajOKUmDhpqvaiRv9EDpVLzuj53uDoukMMwxCMfgb04+ckQ0t2G7wqc
+  /D+K9JW9DDs3Yjgv9k4h7YMhW5gftosd+NkNC/+Y2CkCAwEAAaN1MHMwCQYDVR0T
+  BAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFHKN/nkRusdqCJEuq3lgB3fJvyTg
+  MBwGA1UdEQQVMBOBEWdlZEBGYWVyaWVNVUQub3JnMBwGA1UdEgQVMBOBEWdlZEBG
+  YWVyaWVNVUQub3JnMA0GCSqGSIb3DQEBCwUAA4IBgQBjrBzCKWzXFigswYSPzGO8
+  9atBtY/eQdcN6KCL+PTzQBD9yePGF7H/xsww3awRauP+D1VUjCFbiiC3Qb0Ww0Qd
+  OVA0s10T9KpZ8nb2XyKocSK7TfgDhcyr0V4H2MPxwK9SWYjGGh8z9z9HmT0i3PyX
+  fXOSzzEoG6u26HIOg0nxSpitEjiAHBekQxy9ka5NuQbxoxMg+eIHU4rU9IUhu0Rf
+  wl4wuvPVE3UQK0v0uqT6rJukEKQ1iNgK5R8klgEIv79XhQPgTkMt31FGfrwOp6HB
+  OE0HMwOwY9B0w3aOxxdMQyyRxaZVv3eWE5RimQI7T0TUaxPngtS33ByMZjTeidxi
+  ESIUEPVXoBCkFgLW1EVlBb+rG7WLYod4eVll4tKA42Bi2Ju90tqiJ1YQiyuRfCnp
+  8qAqdfV+4u6Huu1KzAuDQCheyEyISsLST37sU/irV3czV6BiFipWag1XiJciRT3A
+  wZqCfTNVHTdtsCbfdA1DsA3RdG2iEH3TOHzv1Rqzqh4=
   -----END CERTIFICATE-----
-date: 2020-12-28 00:00:00.000000000 Z
+date: 2025-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -50,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake-deveiate
   requirement: !ruby/object:Gem::Requirement
@@ -94,9 +110,8 @@ dependencies:
         version: '3.9'
 description: Configurability is a unified, non-intrusive, assume-nothing configuration
   system for Ruby. It lets you keep the configuration for multiple objects in a single
-  config file, load the file when it's convenient for you, and distribute the
-  configuration when you're ready, sending it everywhere it needs to go with a
-  single action.
+  config file, load the file when it’s convenient for you, and distribute the configuration
+  when you’re ready, sending it everywhere it needs to go with a single action.
 email:
 - ged@faeriemud.org
 - mahlon@martini.nu
@@ -146,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Configurability is a unified, non-intrusive, assume-nothing configuration