Comments for Conf-interface. get-method added.

lib/knot/interface.rb

@@ -11,22 +11,35 @@ class Knot::Zone
 		@zone, @transaction_opened = zone, 0
 	end
 
+	# If no transaction opened, yet, it opens a new transaction.
+	# Counts calling begin.
+	# Knot allowes only one global transaction, so if two clients tries to open a transaction,
+	# the second will fail.  But the second client can change items in the same
+	# transaction like the first client.
+	# The first client, which calls commit or abort, wins and the transaction will be closed.
+	# So, the transaction-handling is only safe, if one client connects to knot.
 	def begin
 		@transaction_opened += 1
 		@protocol.call command: 'zone-begin', zone: @zone  if 1 == @transaction_opened
 	end
 
+	# Decreases opened transactions.
+	# If opened transactions is zero, it stores items and closes transaction successfully.
 	def commit
 		@protocol.call command: 'zone-commit', zone: @zone  if 1 == @transaction_opened
 		@transaction_opened -= 1  if 0 < @transaction_opened
 	end
 
+	# Closes transaction without saving immidiatly.
+	# Counter of opened transaction will be reset to 0.
 	def abort
 		@protocol.call command: 'zone-abort', zone: @zone
 		@transaction_opened = 0
 	end
 
-	def transaction
+	# Opens transaction, calls yielded Proc and closes transaction after return.
+	# If exception was raised, the transaction will be aborted.
+	def transaction # :yield:
 		self.begin
 		yield self
 	rescue Object
@@ -72,6 +85,7 @@ class Knot::Zone
 	rescue Knot::Errors::ENONODE, Knot::Errors::ENOENT
 	end
 	alias delete unset
+	alias del unset
 
 	def get owner = nil, type = nil
 		@protocol.call command: 'zone-get',
@@ -115,10 +129,12 @@ class Knot::Conf
 
 	def parse_item k
 		case k
-		when k
+		when Hash
 			case k.keys.sort
-			when %w[section], %w[id section], %w[item section], %w[id item section] then k
-			else raise ArgumentError, "Invalid Item-format"
+			when %w[section], %w[id section], %w[item section], %w[id item section]
+				k
+			else
+				raise ArgumentError, "Invalid Item-format"
 			end
 
 		when Array
@@ -134,16 +150,26 @@ class Knot::Conf
 					(?: \[ (?<id> [a-z0-9_.-]+) \] )?
 					(?: \. (?<item>[a-z0-9_-]+) )?
 				\z/xi
+
 			$~.named_captures.delete_if {|_,v| v.nil? }
-		else raise ArgumentError, "Invalid Item-format"
+
+		else
+			raise ArgumentError, "Invalid Item-format"
 		end
 	end
 
+	def get item = nil
+		@protocol.call (item ? parse_item( item) : {}).update( command: 'conf-get')
+	end
+
+	# Sets or adds a new value to item.
+	# knot knows single-value items like `server.rundir` and multi-value items like `server.listen`.
+	# If you set a single-value, it will replace the old value.  On a multi-value, it will add it.
 	def set item, value
 		@protocol.call parse_item( item).update( command: 'conf-set', data: value)
 	end
-	alias [] set
 
+	# Removes value from item.  If you provide a value, this value will be removed.
 	def unset item, value = nil
 		@protocol.call parse_item( item).update( command: 'conf-unset', data: value)
 	end