sequel-pg-comment 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 395d855974e2dab38580a5f51fcca0dd417a1d62
-  data.tar.gz: 5a5d63691292204a7d1144beb8b1a2b58df613e4
+  metadata.gz: 3110fff14db57745785e517abfc96b0c67c8f806
+  data.tar.gz: 48ebb162456d9d455557dd019b6e706766bd9024
 SHA512:
-  metadata.gz: de01d8c954e2bbaaa7224551ffe018c757da9b216797db2242e5f240751a46cc08ce593041ea8a5bfb2bafabee4ed45e9295d3ffb9d823b2e04105662c3eac81
-  data.tar.gz: f9728263f44b18b9b96fc3117d6a0385fa8d762bdfdc1a94fa9b514805c47e3b84945204d0737e34130fc62149f4abfb445c081e3aa03abc292dc6388b05a453
+  metadata.gz: d96a82d756893a528156fed4eeb202fc73d1b60bd7e4ad9c3f6863769427c2763216370d0093e25486191cbbd82b20cda1994363f8bcf30d5603b71b7b8b5614
+  data.tar.gz: 4a0d8e466cce89d873d9ea1061561ebbbc527813d35c52171925cdc76eb3215641f42fbd320787a4b76cf48fbc66a9c138bd9f16b2af8a95c76017206a2fbabe

data/lib/sequel/extensions/pg_comment.rb

@@ -1,9 +1,52 @@
-module Sequel::Extension; end  #:nodoc:
+module Sequel::Postgres; end  #:nodoc:
 
 # PostgreSQL-specific extension to set and retrieve comments on
 # all database objects.
-# 
-module Sequel::Extension::PgComment
+#
+module Sequel::Postgres::Comment
+	# The types of PostgreSQL object that are commented on in their own
+	# right.
+	STANDALONE_TYPES = [
+		:aggregate,
+		:cast,
+		:collation,
+		:conversion,
+		:database,
+		:domain,
+		:extension,
+		:event_trigger,
+		:foreign_data_wrapper,
+		:foreign_table,
+		:function,
+		:index,
+		:large_object,
+		:materialized_view,
+		:operator,
+		:operator_class,
+		:operator_family,
+		:language,
+		:procedural_language,
+		:role,
+		:schema,
+		:sequence,
+		:server,
+		:table,
+		:tablespace,
+		:text_search_configuration,
+		:text_search_dictionary,
+		:text_search_parser,
+		:text_search_template,
+		:type,
+		:view
+	]
+
+	CONTAINED_TYPES = [
+		:column,
+		:constraint,
+		:rule,
+		:trigger
+	]
+
 	# Strip indenting whitespace from a comment string.
 	#
 	# Two rules are applied by this method:
@@ -49,7 +92,7 @@ module Sequel::Extension::PgComment
 	# @param comment [String] The comment to mangle for whitespace.
 	#
 	# @return [String] The normalised comment, with whitespace removed.
-	#      
+	#
 	def self.normalise_comment(comment)
 		comment.tap do |s|
 			s.gsub!(/\A\n+/, '')
@@ -61,13 +104,10 @@ module Sequel::Extension::PgComment
 	end
 end
 
-require_relative 'pg_comment/sql_generator'
 require_relative 'pg_comment/database_methods'
 require_relative 'pg_comment/dataset_methods'
-require_relative 'pg_comment/create_table_generator_methods'
-require_relative 'pg_comment/alter_table_generator_methods'
 
 Sequel::Database.register_extension(:pg_comment) do |db|
-	db.extend Sequel::Extension::PgComment::DatabaseMethods
-	db.extend_datasets Sequel::Extension::PgComment::DatasetMethods
+	db.extend Sequel::Postgres::Comment::DatabaseMethods
+	db.extend_datasets Sequel::Postgres::Comment::DatasetMethods
 end

data/lib/sequel/extensions/pg_comment/database_methods.rb

@@ -1,42 +1,51 @@
 # Support for setting and retrieving comments on all object types
 # in a PostgreSQL database.
 #
-module Sequel::Extension::PgComment::DatabaseMethods
-	# Set the comment for a database object.
-	#
-	# @param type [#to_s] The type of object that you wish to comment on.
-	#   This can either be a string or symbol.  Any object type that PgSQL
-	#   knows about should be fair game.  The current list of object types
-	#   that this plugin knows about (and hence will accept) is listed in
-	#   the {Sequel::Extension::PgComment::OBJECT_TYPES} array.
-	#
-	# @param id [#to_s] The name of the object that you wish to comment on.
-	#   For most types of object, this should be the literal name of the
-	#   object.  However, for columns in a table or view, you should separate
-	#   the table/view name from the column name with a double underscore
-	#   (ie `__`).  This is the standard Sequel convention for such things.
+module Sequel::Postgres::Comment::DatabaseMethods
+	# @param type [Symbol] The object type you're looking to set the comment
+	#   on.  This is just the PostgreSQL type name, lowercased, with spaces
+	#   replaced with underscores.
+	#
+	# @param id [Symbol, String, Array<Symbol, String>] The identifier of the
+	#   object that you wish to comment on.  For most types of object, this
+	#   should be the literal name of the object.  However, for objects which
+	#   are "contained" in another object (columns in tables/views, and
+	#   constraints, triggers, and rules in tables) you must pass the
+	#   identifier as a two-element array, where the first element is the
+	#   container table or view, and the second element is the contained
+	#   object (column, constraint, rule, or trigger).
+	#
+	#   In any event, when a `Symbol` is encountered, it is quoted for
+	#   safety, and split into a schema and object name pair, if appropriate.
+	#   If a `String` is passed, then **no escaping or quoting is done**.
+	#   While this is a slight risk, it is necessary to allow you to
+	#   reference complex object names which can't reasonably be described
+	#   otherwise (`FUNCTION`, I'm looking at you).
 	#
 	# @param comment [String] The comment you wish to set for the database
 	#   object.
 	#
-	# @see {Sequel::Extension::PgComment.normalise_comment} for details on
+	# @raise [Sequel::Error] if the specified `type` isn't recognised.
+	#
+	# @see {Sequel::Postgres::Comment.normalise_comment} for details on
 	#   how the comment string is interpreted.
 	#
 	def comment_on(type, id, comment)
-		gen = begin
-			Sequel::Extension::PgComment::SqlGenerator.create(type, id, comment)
-		rescue ArgumentError
-			raise ArgumentError,
-					"Invalid object type: #{type.inspect}"
+		if Sequel::Postgres::Comment::STANDALONE_TYPES.include?(type)
+			comment_on_standalone_type(type, id, comment)
+		elsif Sequel::Postgres::Comment::CONTAINED_TYPES.include?(type)
+			comment_on_contained_type(type, id, comment)
+		else
+			raise Sequel::Error,
+			      "Unknown object type: #{type.inspect}"
 		end
-
-		execute(gen.generate)
 	end
 
+
 	# Retrieve the comment for a database object.
 	#
 	# @param object [#to_s] The name of the database object to retrieve.  For
-	#   most objects, this should be the literal name of the object. 
+	#   most objects, this should be the literal name of the object.
 	#   However, for columns on tables and views, the name of the table/view
 	#   should be a separated from the name of the column by a double
 	#   underscore (ie `__`).
@@ -50,14 +59,19 @@ module Sequel::Extension::PgComment::DatabaseMethods
 		if object.index("__")
 			tbl, col = object.split("__", 2)
 
-			execute("SELECT col_description(c.oid, a.attnum) " +
-					  "FROM pg_class c JOIN pg_attribute a " +
-					  "ON (c.oid=a.attrelid) " +
-					  "WHERE c.relname=#{literal(tbl)} " +
-					  "AND a.attname=#{literal(col)}"
-					 )
+			(select(Sequel.function(:col_description, :c__oid, :a__attnum).as(:comment)).
+			   from(Sequel.as(:pg_class, :c)).
+			   join(Sequel.as(:pg_attribute, :a), :c__oid => :a__attrelid).
+			   where(:c__relname => tbl).
+			   and(:a__attname => col).first || {})[:comment]
 		else
-			execute("SELECT obj_description(#{literal(object.to_s)}::regclass, 'pg_class')")
+			(select(
+			   Sequel.function(
+			     :obj_description,
+			     Sequel.cast(object, :regclass),
+			     "pg_class"
+			   ).as(:comment)
+			 ).first || {})[:comment]
 		end
 	end
 
@@ -78,51 +92,47 @@ module Sequel::Extension::PgComment::DatabaseMethods
 	end
 
 	#:nodoc:
-	# Enhanced version to support setting comments on objects created in a
-	# block-form `create_table` statement.
+	# Enhanced to support creating comments on columns, after the table
+	# itself (and hence all its columns) have been created.
 	#
-	def create_table_generator(&block)
-		super do
-			extend Sequel::Extension::PgComment::CreateTableGeneratorMethods
-			@comments = []
-			instance_eval(&block) if block
+	def create_table_from_generator(name, generator, options)
+		generator.columns.each do |col|
+			if col[:comment]
+				comment_on(:column, [name, col[:name]], col[:comment])
+			end
+		end
+
+		generator.constraints.each do |c|
+			case c[:type]
+			when :primary_key
+				c_name = c[:name] || "#{name}_pkey".to_sym
+				comment_on(:index, c_name, c[:comment])
+			when :foreign_key, :check
+				if c[:type] == :check && c[:name].nil?
+					raise Sequel::Error,
+					      "Setting comments on unnamed check constraints is not supported"
+				end
+				c_name = c[:name] || "#{name}_#{c[:columns].first}_fkey".to_sym
+				comment_on(:constraint, [name, c_name], c[:comment])
+			when :unique
+				c_name = c[:name] || ([name] + c[:columns] + ["key"]).join("_").to_sym
+				comment_on(:index, c_name, c[:comment])
+			end
 		end
 	end
 
 	#:nodoc:
-	# Enhanced version to support setting comments on objects created in a
-	# block-form `create_table` statement.
-	#
-	# If you're wondering why we override the
-	# create_table_indexes_from_generator method, rather than
-	# create_table_from_generator, it's because the indexes method runs last,
-	# and we can only create our comments after the objects we're commenting
-	# on have been created.  We *could* set some comments in
-	# create_table_from_generator, and then set index comments in
-	# create_table_indexes_from_generator, but why override two methods when
-	# you can just override one to get the same net result?
+	# Enhanced to support creating comments on indexes, after the indexes
+	# themselves have been created.
 	#
 	def create_table_indexes_from_generator(name, generator, options)
 		super
 
-		generator.comments.each do |sql_gen|
-			if sql_gen.respond_to? :table_name
-				sql_gen.table_name = name
+		generator.indexes.each do |idx|
+			if idx[:comment]
+				i_name = idx[:name] || ([name] + idx[:columns] + ["index"]).join("_").to_sym
+				comment_on(:index, i_name, idx[:comment])
 			end
-
-			execute(sql_gen.generate)
-		end
-	end
-
-	#:nodoc:
-	# Enhanced version to support setting comments on objects created in a
-	# block-form `alter_table` statement.
-	#
-	def alter_table_generator(&block)
-		super do
-			extend Sequel::Extension::PgComment::AlterTableGeneratorMethods
-			@comments = []
-			instance_eval(&block) if block
 		end
 	end
 
@@ -133,12 +143,30 @@ module Sequel::Extension::PgComment::DatabaseMethods
 	def apply_alter_table_generator(name, generator)
 		super
 
-		generator.comments.each do |sql_gen|
-			if sql_gen.respond_to?(:table_name=)
-				sql_gen.table_name = name
+		schema, table = schema_and_table(name)
+		fqtable = [schema, table].compact.map { |e| literal e.to_sym }.join('.')
+
+		generator.operations.each do |op|
+			if op[:comment]
+				case op[:op]
+				when :add_column
+					comment_on(:column, [name, op[:name]], op[:comment])
+				when :add_constraint
+					case op[:type]
+					when :primary_key
+						comment_on(:index, "#{name}_pkey".to_sym, op[:comment])
+					when :foreign_key, :check
+						c_name = op[:name] || "#{name}_#{op[:columns].first}_fkey".to_sym
+						comment_on(:constraint, [name, c_name], op[:comment])
+					when :unique
+						c_name = op[:name] || ([name] + op[:columns] + ["key"]).join("_").to_sym
+						comment_on(:index, c_name, op[:comment])
+					end
+				when :add_index
+					c_name = op[:name] || ([name] + op[:columns] + ["index"]).join("_").to_sym
+					comment_on(:index, c_name, op[:comment])
+				end
 			end
-
-			execute(sql_gen.generate)
 		end
 	end
 
@@ -160,16 +188,41 @@ module Sequel::Extension::PgComment::DatabaseMethods
 
 	private
 
-	# Quote an object name, handling the double underscore convention
-	# for separating a column name from its containing object.
-	#
-	def quote_comment_identifier(id)
-		id = id.to_s
-		if id.index("__")
-			tbl, col = id.split("__", 2)
-			quote_identifier(tbl) + "." + quote_identifier(col)
+	def comment_on_standalone_type(type, id, comment)
+		run "COMMENT ON #{type.to_s.gsub("_", " ").upcase} #{quoted_schema_and_table id} IS #{literal comment}"
+	end
+
+	def comment_on_contained_type(type, id, comment)
+		unless id.is_a?(Array) and id.length == 2
+			raise Sequel::Error,
+			      "Invalid ID for #{type.inspect}: must be a two-element array"
+		end
+
+		fqtable = quoted_schema_and_table(id[0])
+		fqname  = if id[1].is_a?(Symbol)
+			quote_identifier id[1]
+		elsif id[1].is_a?(String)
+			id[1]
+		else
+			raise Sequel::Error,
+			      "Invalid type for object ID: must be a Symbol or String"
+		end
+
+		if type == :column
+			run "COMMENT ON COLUMN #{fqtable}.#{fqname} IS #{literal comment}"
+		else
+			run "COMMENT ON #{type.to_s.gsub("_", " ").upcase} #{fqname} ON #{fqtable} IS #{literal comment}"
+		end
+	end
+
+	def quoted_schema_and_table(id)
+		if id.is_a?(Symbol)
+			literal id
+		elsif id.is_a?(String)
+			id
 		else
-			quote_identifier(id)
+			raise Sequel::Error,
+			      "Invalid type for ID: #{id.inspect} (must by symbol or string)"
 		end
 	end
 end

data/lib/sequel/extensions/pg_comment/dataset_methods.rb

@@ -6,7 +6,7 @@
 # Will retrieve the comment for `foo_tbl.some_column`, if such a
 # column exists.
 #
-module Sequel::Extension::PgComment::DatasetMethods
+module Sequel::Postgres::Comment::DatasetMethods
 	# Retrieve the comment for the column named `col` in the "primary" table
 	# for this dataset.
 	#
@@ -19,4 +19,19 @@ module Sequel::Extension::PgComment::DatasetMethods
 	def comment_for(col)
 		db.comment_for("#{first_source_table}__#{col}")
 	end
+
+	# Retrieve the comment for the "primary" table in the dataset.
+	#
+	# @return [String, NilClass] The comment for the table, or `nil` if there
+	#   is no comment defined.
+	#
+	# @example Simple, single-table dataset
+	#   db[:foo].comment  # => comment for table foo
+	#
+	# @example Multi-table dataset
+	#   db[:foo].join(:bar, ...).where { id < 20 }.comment  # => comment for table foo
+	#
+	def comment
+		db.comment_for(first_source_table)
+	end
 end

data/spec/alter_table_comment_spec.rb

@@ -38,14 +38,6 @@ describe "schema modification" do
 		  to eq("COMMENT ON COLUMN \"foo\".\"bar_id\" IS 'Over there!'")
 	end
 
-	it "sets a column comment on add_foreign_key with custom constraint name" do
-		db.alter_table :foo do
-			add_foreign_key :bar_id, :bar, :comment => "Over there!", :name => :fkr
-		end
-		expect(db.sqls.last).
-		  to eq("COMMENT ON COLUMN \"foo\".\"bar_id\" IS 'Over there!'")
-	end
-
 	it "sets a constraint comment on composite add_foreign_key" do
 		db.alter_table :foo do
 			add_foreign_key [:name, :dob], :bar, :comment => "Over there!"
@@ -96,7 +88,7 @@ describe "schema modification" do
 
 	it "sets a constraint comment" do
 		db.alter_table :foo do
-			add_constraint(:min_length, :comment => "Bigger is better!") do
+			add_constraint(:name => :min_length, :comment => "Bigger is better!") do
 				char_length(name) > 2
 			end
 		end

data/spec/comment_for_spec.rb

@@ -9,26 +9,27 @@ describe "#comment_for" do
 	it "gets a table comment" do
 		db.comment_for(:foo)
 		expect(db.sqls).
-		  to eq(["SELECT obj_description('foo'::regclass, 'pg_class')"])
+		  to eq([%{SELECT obj_description(CAST('foo' AS regclass), 'pg_class') } +
+		           %{AS \"comment\" LIMIT 1}])
 	end
 
 	it "gets a column comment" do
 		db.comment_for(:foo__column)
 		expect(db.sqls).
-		  to eq(["SELECT col_description(c.oid, a.attnum) " +
-		          "FROM pg_class c " +
-		          "JOIN pg_attribute a ON (c.oid=a.attrelid) " +
-		          "WHERE c.relname='foo' AND a.attname='column'"
+		  to eq([%{SELECT col_description("c"."oid", "a"."attnum") AS "comment" } +
+		           %{FROM "pg_class" AS "c" } +
+		           %{INNER JOIN "pg_attribute" AS "a" ON ("c"."oid" = "a"."attrelid") } +
+		           %{WHERE (("c"."relname" = 'foo') AND ("a"."attname" = 'column')) LIMIT 1}
 		       ])
 	end
 
 	it "gets a column comment via the dataset" do
 		db[:foo].comment_for(:column)
 		expect(db.sqls).
-		  to eq(["SELECT col_description(c.oid, a.attnum) " +
-		          "FROM pg_class c " +
-		          "JOIN pg_attribute a ON (c.oid=a.attrelid) " +
-		          "WHERE c.relname='foo' AND a.attname='column'"
+		  to eq([%{SELECT col_description("c"."oid", "a"."attnum") AS "comment" } +
+		           %{FROM "pg_class" AS "c" } +
+		           %{INNER JOIN "pg_attribute" AS "a" ON ("c"."oid" = "a"."attrelid") } +
+		           %{WHERE (("c"."relname" = 'foo') AND ("a"."attname" = 'column')) LIMIT 1}
 		       ])
 	end
 end

data/spec/comment_on_spec.rb

@@ -12,8 +12,8 @@ describe "#comment_on" do
 		  to eq(["COMMENT ON TABLE \"foo\" IS 'Ohai!'"])
 	end
 
-	it "accepts a string as object type" do
-		db.comment_on("table", :foo, "Ohai!")
+	it "accepts a symbol as object name" do
+		db.comment_on(:table, :foo, "Ohai!")
 		expect(db.sqls).
 		  to eq(["COMMENT ON TABLE \"foo\" IS 'Ohai!'"])
 	end
@@ -39,7 +39,19 @@ describe "#comment_on" do
 	it "explodes if an invalid object type is given" do
 		expect do
 			db.comment_on(:foobooblee, :foo, "O'hai!")
-		end.to raise_error(ArgumentError, /invalid object type/i)
+		end.to raise_error(Sequel::Error)
+	end
+
+	it "explodes if an invalid ID type is given for a table" do
+		expect do
+			db.comment_on(:table, [:foo, :bar], "Ohai!")
+		end.to raise_error(Sequel::Error)
+	end
+
+	it "explodes if an invalid ID type is given for a column" do
+		expect do
+			db.comment_on(:column, :foo, "Ohai!")
+		end.to raise_error(Sequel::Error)
 	end
 
 	it "quotes the object name" do
@@ -49,8 +61,14 @@ describe "#comment_on" do
 	end
 
 	it "sets a column comment correctly" do
-		db.comment_on(:column, :foo__bar_id, "Ohai, column!")
+		db.comment_on(:column, [:foo, :bar_id], "Ohai, column!")
 		expect(db.sqls).
 		  to eq(["COMMENT ON COLUMN \"foo\".\"bar_id\" IS 'Ohai, column!'"])
 	end
+
+	it "sets a trigger comment correctly" do
+		db.comment_on(:trigger, [:foo, :bar_id], "Whoa there, trigger!")
+		expect(db.sqls).
+		  to eq(["COMMENT ON TRIGGER \"bar_id\" ON \"foo\" IS 'Whoa there, trigger!'"])
+	end
 end

data/spec/create_table_comment_spec.rb

@@ -43,17 +43,6 @@ describe "schema creation" do
 		  to eq("COMMENT ON COLUMN \"foo\".\"id\" IS 'I am unique'")
 	end
 
-	it "sets a primary key comment on a custom constraint name" do
-		db.create_table :foo do
-			primary_key :id,
-			            :comment => "I am unique",
-			            :name => :custom_pk
-		end
-
-		expect(db.sqls.last).
-		  to eq("COMMENT ON COLUMN \"foo\".\"id\" IS 'I am unique'")
-	end
-
 	it "sets a composite primary key comment" do
 		db.create_table :foo do
 			primary_key [:bar, :baz],
@@ -90,7 +79,7 @@ describe "schema creation" do
 		end
 		
 		expect(db.sqls.last).
-		  to eq("COMMENT ON CONSTRAINT \"bar_bar_name_fkey\" ON \"foo\" IS 'Over there!'")
+		  to eq("COMMENT ON CONSTRAINT \"foo_bar_name_fkey\" ON \"foo\" IS 'Over there!'")
 	end
 
 	it "sets a composite foreign_key comment with custom name" do
@@ -168,26 +157,18 @@ describe "schema creation" do
 
 	it "sets a constraint comment" do
 		db.create_table :foo do
-			constraint :clamp, :num => 1..5, :comment => "Toight"
+			constraint({ :name => :clamp, :comment => "Toight" }, :num => 1..5)
 		end
 
 		expect(db.sqls.last).
 		  to eq("COMMENT ON CONSTRAINT \"clamp\" ON \"foo\" IS 'Toight'")
 	end
 
-	it "blows up trying to an unnamed constraint comment" do
-		expect do
-			db.create_table :foo do
-				constraint nil, :num => 1..5, :comment => "Kaboom"
-			end
-		end.to raise_error(/not supported/i)
-	end
-
 	it "blows up trying to comment on a check" do
 		expect do
 			db.create_table :foo do
 				check(:comment => "Kaboom") { char_length(name) > 2 }
 			end
-		end.to raise_error(/not supported/i)
+		end.to raise_error(Sequel::Error, /not supported/i)
 	end
 end

data/spec/dataset_comment_spec.rb

@@ -0,0 +1,20 @@
+require_relative 'spec_helper'
+require 'sequel'
+
+describe "Dataset#comment" do
+	let(:db) { Sequel.connect("mock://postgres").extension(:pg_comment) }
+
+	it "gets the comment for the table" do
+		db[:foo].comment
+		expect(db.sqls).
+		  to eq([%{SELECT obj_description(CAST('foo' AS regclass), 'pg_class') } +
+		           %{AS "comment" LIMIT 1}])
+	end
+
+	it "gets the comment for the first table" do
+		db[:foo].join(:bar, :id => :bar_id).where { foo__id < 20 }.comment
+		expect(db.sqls).
+		  to eq([%{SELECT obj_description(CAST('foo' AS regclass), 'pg_class') } +
+		           %{AS "comment" LIMIT 1}])
+	end
+end

data/spec/normalise_comment_spec.rb

@@ -2,9 +2,9 @@ require_relative 'spec_helper'
 require 'sequel'
 require 'sequel/extensions/pg_comment'
 
-context "Sequel::Extension::PgComment.normalise_comment" do
+context "Sequel::Postgres::Comment.normalise_comment" do
 	def nc(s)
-		Sequel::Extension::PgComment.normalise_comment(s)
+		Sequel::Postgres::Comment.normalise_comment(s)
 	end
 
 	it "does nothing to a string with no leading whitespace" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel-pg-comment
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-15 00:00:00.000000000 Z
+date: 2015-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: git-version-bump
@@ -199,11 +199,8 @@ files:
 - README.md
 - Rakefile
 - lib/sequel/extensions/pg_comment.rb
-- lib/sequel/extensions/pg_comment/alter_table_generator_methods.rb
-- lib/sequel/extensions/pg_comment/create_table_generator_methods.rb
 - lib/sequel/extensions/pg_comment/database_methods.rb
 - lib/sequel/extensions/pg_comment/dataset_methods.rb
-- lib/sequel/extensions/pg_comment/sql_generator.rb
 - sequel-pg-comment.gemspec
 - spec/alter_table_comment_spec.rb
 - spec/comment_for_spec.rb
@@ -211,10 +208,10 @@ files:
 - spec/create_join_table_comment_spec.rb
 - spec/create_table_comment_spec.rb
 - spec/create_view_comment_spec.rb
+- spec/dataset_comment_spec.rb
 - spec/extension_spec.rb
 - spec/normalise_comment_spec.rb
 - spec/spec_helper.rb
-- spec/sql_generator_spec.rb
 homepage: http://theshed.hezmatt.org/sequel-pg-comment
 licenses: []
 metadata: {}

data/lib/sequel/extensions/pg_comment/alter_table_generator_methods.rb

@@ -1,126 +0,0 @@
-#:nodoc:
-# Enhancements to the standard schema modification methods in a
-# block-form `alter_table` method, to support setting comments via the
-# `:comment` option.
-#
-# Note that not every schema modification method is enhanced in this module;
-# some modifications are implemneted in terms of more fundamental methods,
-# and so do not require their own method here.  For example, `add_foreign_key`
-# with a single column is handled by `add_column`, and so doesn't require its
-# own implementation.  Rest assured that all schema modification methods
-# *should* accept a `:comment` option, and set a comment in the database.  If
-# you find one that doesn't, please file a bug.
-#
-module Sequel::Extension::PgComment::AlterTableGeneratorMethods
-	attr_reader :comments
-
-	include Sequel::Extension::PgComment
-
-	# Enhanced version of the `add_column` schema modification method,
-	# which supports setting a comment on the column.
-	#
-	# @option [String] :comment The comment to set on the column
-	#   that is being added.
-	#
-	def add_column(*args)
-		super
-
-		if args.last.is_a?(Hash) && args.last[:comment]
-			comments << SqlGenerator.create(:column, args.first, args.last[:comment])
-		end
-	end
-
-	# Enhanced version of the `add_composite_primary_key` schema modification
-	# method, which supports setting a comment on the index.
-	#
-	# @option [String] :comment The comment to set on the index that is being
-	#   added.
-	#
-	def add_composite_primary_key(columns, opts)
-		super
-
-		if opts[:comment]
-			comments << PrefixSqlGenerator.new(:index, :_pkey, opts[:comment])
-		end
-	end
-
-	# Enhanced version of the `add_composite_foreign_key` schema modification
-	# method, which supports setting a comment on the constraint.
-	#
-	# @option [String] :comment The comment to set on the constraint that is being
-	#   added.
-	#
-	def add_composite_foreign_key(columns, table, opts)
-		super
-		
-		if opts[:comment]
-			comments << if opts[:name]
-				SqlGenerator.create(:constraint, opts[:name], opts[:comment])
-			else
-				PrefixSqlGenerator.new(
-			     :constraint,
-			     "_#{columns.first}_fkey".to_sym,
-			     opts[:comment]
-			   )
-			end
-		end
-	end
-
-	# Enhanced version of the `add_index` schema modification method, which
-	# supports setting a comment on the index.
-	#
-	# @option [String] :comment The comment to set on the index that is being
-	#   added.
-	#
-	def add_index(columns, opts = OPTS)
-		if opts[:comment]
-			comments << if opts[:name]
-				SqlGenerator.create(:index, opts[:name], opts[:comment])
-			else
-				PrefixSqlGenerator.new(
-				  :index,
-				  "_#{[columns].flatten.map(&:to_s).join("_")}_index".to_sym,
-				  opts[:comment]
-				)
-			end
-		end
-	end
-
-	# Enhanced version of the `add_constraint` schema modification method,
-	# which supports setting a comment on the constraint.
-	#
-	# @option [String] :comment The comment to set on the constraint that is
-	#   being added.
-	#
-	def add_constraint(name, *args, &block)
-		super
-
-		opts = args.last.is_a?(Hash) ? args.last : {}
-
-		if opts[:comment]
-			comments << SqlGenerator.create(:constraint, name, opts[:comment])
-		end
-	end
-
-	# Enhanced version of the `add_unique_constraint` schema modification
-	# method, which supports setting a comment on the index.
-	#
-	# @option [String] :comment The comment to set on the index that is being
-	#   added.
-	#
-	def add_unique_constraint(columns, opts = OPTS)
-		super
-
-		if opts[:comment]
-			comments << if opts[:name]
-				SqlGenerator.create(:index, opts[:name], opts[:comment])
-			else
-				PrefixSqlGenerator.new(
-			     :index,
-			     "_#{[columns].flatten.map(&:to_s).join("_")}_key".to_sym,
-			     opts[:comment]
-			   )
-			end
-		end
-	end
-end

data/lib/sequel/extensions/pg_comment/create_table_generator_methods.rb

@@ -1,159 +0,0 @@
-#:nodoc:
-# Enhancements to the standard schema modification methods in a
-# block-form `create_table` method, to support setting comments via the
-# `:comment` option.
-#
-module Sequel::Extension::PgComment::CreateTableGeneratorMethods
-	# An array of all the comments that this generator has seen fit to
-	# create.
-	#
-	# @return [Array<SqlGenerator>]
-	#
-	attr_reader :comments
-
-	include Sequel::Extension::PgComment
-
-	# Enhanced version of the `column` table definition method, which
-	# supports setting a comment on the column.
-	#
-	# @option [String] :comment The comment to set on the column that is
-	#   being defined.
-	#
-	def column(*args)
-		super
-
-		if args.last.is_a?(Hash) && args.last[:comment]
-			comments << SqlGenerator.create(:column, args.first, args.last[:comment])
-		end
-	end
-
-	# Enhanced version of the `primary_key` table definition method, which
-	# supports setting a comment on either the column or constraint.
-	#
-	# If the primary key is composite (`name` is an array), then the comment
-	# will be placed on the index.  Otherwise, the comment will be set
-	# on the column itself.
-	#
-	# @option [String] :comment The comment to set on the column or
-	#   index that is being defined.
-	#
-	def primary_key(name, *args)
-		if args.last.is_a?(Hash) && args.last[:comment] and !name.is_a? Array
-			# The composite primary key case will be handled by the
-			# `composite_primary_key` method, so we don't have to deal with it
-			# here.
-			comments << SqlGenerator.create(:column, name, args.last[:comment])
-		end
-				
-		super
-	end
-
-	# Enhanced version of the `composite_primary_key` table definition method,
-	# which supports setting a comment on the primary key index.
-	#
-	# @option [String] :comment The comment to set on the primary key index.
-	#
-	def composite_primary_key(columns, *args)
-		if args.last.is_a?(Hash) and args.last[:comment]
-			if args.last[:name]
-				comments << SqlGenerator.create(
-				              :index,
-				              args.last[:name],
-				              args.last[:comment]
-				            )
-			else
-				comments << PrefixSqlGenerator.new(:index, :_pkey, args.last[:comment])
-			end
-		end
-
-		super
-	end
-
-	# Enhanced version of the `composite_foreign_key` table definition method,
-	# which supports setting a comment on the FK constraint.
-	#
-	# @option [String] :comment The comment to set on the foreign key constraint.
-	#
-	def composite_foreign_key(columns, opts)
-		if opts.is_a?(Hash) and opts[:comment] and opts[:table]
-			if opts[:name]
-				comments << SqlGenerator.create(
-				              :constraint,
-				              opts[:name],
-				              opts[:comment]
-				            )
-			else
-				comments << SqlGenerator.create(
-				              :constraint,
-				              "#{opts[:table]}_#{columns.first}_fkey".to_sym,
-				              opts[:comment]
-				            )
-			end
-		end
-
-		super
-	end
-
-	# Enhanced version of the `index` table definition method,
-	# which supports setting a comment on the index.
-	#
-	# @option [String] :comment The comment to set on the index that is being
-	#   defined.
-	#
-	def index(columns, opts = OPTS)
-		if opts[:comment]
-			if opts[:name]
-				comments << SqlGenerator.create(:index, opts[:name], opts[:comment])
-			else
-				comments << PrefixSqlGenerator.new(
-				              :index,
-				              ("_" + [columns].flatten.map(&:to_s).join('_') + "_index").to_sym,
-				              opts[:comment]
-				            )
-			end
-		end
-		
-		super
-	end
-
-	# Enhanced version of the `unique` table definition method,
-	# which supports setting a comment on the unique index.
-	#
-	# @option [String] :comment The comment to set on the index that will be
-	#   defined.
-	#
-	def unique(columns, opts = OPTS)
-		if opts[:comment]
-			if opts[:name]
-				comments << SqlGenerator.create(:index, opts[:name], opts[:comment])
-			else
-				comments << PrefixSqlGenerator.new(
-				              :index,
-				              ("_" + [columns].flatten.map(&:to_s).join('_') + "_key").to_sym,
-				              opts[:comment]
-				            )
-			end
-		end
-		
-		super
-	end
-
-	# Enhanced version of the `constraint` table definition method,
-	# which supports setting a comment on the constraint.
-	#
-	# @option [String] :comment The comment to set on the constraint that is
-	#   being defined.
-	#
-	def constraint(name, *args, &block)
-		opts = name.is_a?(Hash) ? name : (args.last.is_a?(Hash) ? args.last : {})
-		
-		if opts[:comment]
-			if name
-				comments << SqlGenerator.create(:constraint, name, opts[:comment])
-			else
-				raise RuntimeError,
-				      "Setting comments on unnamed or check constraints is not supported"
-			end
-		end
-	end
-end

data/lib/sequel/extensions/pg_comment/sql_generator.rb

@@ -1,257 +0,0 @@
-module Sequel::Extension::PgComment
-	#:nodoc:
-	# Generate SQL to set a comment.
-	#
-	class SqlGenerator
-		# The PostgreSQL object types which this class knows how to generate
-		# comment SQL for.
-		#
-		OBJECT_TYPES = %w{AGGREGATE
-		                  CAST
-		                  COLLATION
-		                  CONVERSION
-		                  DATABASE
-		                  DOMAIN
-								EXTENSION
-								EVENT\ TRIGGER
-								FOREIGN\ DATA\ WRAPPER
-								FOREIGN\ TABLE
-								FUNCTION
-								INDEX
-								LARGE\ OBJECT
-								MATERIALIZED\ VIEW
-								OPERATOR
-								OPERATOR\ CLASS
-								OPERATOR\ FAMILY
-								PROCEDURAL\ LANGUAGE
-								LANGUAGE
-								ROLE
-								SCHEMA
-								SEQUENCE
-								SERVER
-								TABLE
-								TABLESPACE
-								TEXT\	SEARCH\ CONFIGURATION
-								TEXT\ SEARCH\ DICTIONARY
-								TEXT\ SEARCH\ PARSER
-								TEXT\ SEARCH\ TEMPLATE
-								TYPE
-								VIEW
-							}
-		
-		# Find the correct class for a given object type, and instantiate a
-		# new one of them.
-		#
-		# @param object_type [String, Symbol] The type of object we're going
-		#   to comment on.  Strings and symbols are both fine, and any case
-		#   is fine, too.  Any underscores get turned into spaces.  Apart from
-		#   that, it needs to be the exact name that PostgreSQL uses for the given
-		#   type.
-		#
-		# @param object_name [String, Symbol] The name of the database object to
-		#   set the comment on.  A string is considered "already quoted", and hence
-		#   is not escaped any further.  A symbol is run through the usual Sequel
-		#   identifier escaping code before being unleashed on the world.
-		#
-		# @param comment [String] The comment to set.
-		#
-		# @return [SqlGenerator] Some sort of `SqlGenerator` object, or a subclass.
-		#
-		# @raise [ArgumentError] if you passed in an `object_type` that we don't
-		#   know about.
-		#
-		def self.create(object_type, object_name, comment)
-			generators.each do |gclass|
-				if gclass.handles?(object_type)
-					return gclass.new(object_type, object_name, comment)
-				end
-			end
-
-			raise ArgumentError,
-			      "Unrecognised object type #{object_type.inspect}"
-		end
-
-		# Return whether or not this class supports the specified object type.
-		#
-		# @param object_type [String, Symbol] @see {.create}
-		#
-		# @return [TrueClass, FalseClass] whether or not this class can handle
-		#   the object type you passed.
-		#
-		def self.handles?(object_type)
-			self.const_get(:OBJECT_TYPES).include?(object_type.to_s.upcase.gsub('_', ' '))
-		end
-
-		private
-
-		# Return all known `SqlGenerator` classes.
-		#
-		def self.generators
-			@generators ||= ObjectSpace.each_object(Class).select do |klass|
-				klass.ancestors.include?(self)
-			end
-		end
-
-		# We just need this so we can quote things.
-		def self.mock_db
-			@mock_db ||= Sequel.connect("mock://postgres")
-		end
-
-		public
-
-		# The canonicalised string (that is, all-uppercase, with words
-		# separated by spaces) for the object type of this SQL generator.
-		#
-		attr_reader :object_type
-		
-		# The raw (might-be-a-symbol, might-be-a-string) object name that
-		# was passed to us originally.
-		#
-		attr_reader :object_name
-		
-		# The comment.
-		attr_reader :comment
-
-		# Spawn a new SqlGenerator.
-		#
-		# @see {.create}
-		#
-		def initialize(object_type, object_name, comment)
-			@object_type = object_type.to_s.upcase.gsub('_', ' ')
-			@object_name = object_name
-			@comment     = comment
-		end
-
-		# SQL to set a comment on the object of our affection.
-		#
-		# @return [String] The SQL needed to set the comment.
-		#
-		def generate
-			quoted_object_name = case object_name
-			when Symbol
-				literal object_name
-			else
-				object_name
-			end
-				
-			"COMMENT ON #{object_type} #{quoted_object_name} IS #{literal comment.to_s}"
-		end
-
-		private
-
-		# Quote the provided database object (a symbol) or string value
-		# (a string).
-		#
-		def literal(s)
-			self.class.mock_db.literal(s)
-		end
-	end
-
-	#:nodoc:
-	# A specialised generator for object types that live "inside" a
-	# table.  Specifically, those types are columns, constraints,
-	# rules, and triggers.
-	#
-	# They get their own subclass because these object types can be
-	# manipulated inside a `create_table` or `alter_table` block, and at the
-	# time the block is evaluated, the code doesn't know the name of the
-	# table in which they are contained.  So, we just stuff what we *do* know
-	# into these generators, and then when all's done, we can go to each of
-	# these generators, say "this is your table name", and then ask for the
-	# generated SQL.
-	#
-	class TableObjectSqlGenerator < SqlGenerator
-		# The few object types that this class handles.
-		OBJECT_TYPES = %w{COLUMN CONSTRAINT RULE TRIGGER}
-
-		# The name of the object which contains the object which is the direct
-		# target of this SQL generator.  Basically, it's the table name.
-		attr_accessor :table_name
-
-		# Overridden constructor to deal with the double-underscore-separated
-		# names that we all know and love.
-		#
-		# @see {SqlGenerator#initialize}
-		#
-		def initialize(object_type, object_name, comment)
-			super
-
-			if object_name.is_a?(Symbol) and object_name.to_s.index("__")
-				@table_name, @object_name = object_name.to_s.split("__", 2).map(&:to_sym)
-			end
-		end
-
-		# Generate special SQL.
-		#
-		# @see {SqlGenerator#generate}
-		#
-		def generate
-			if table_name.nil?
-				raise ArgumentError,
-				      "Cannot generate SQL for #{object_type} #{object_name} " +
-				        "without a table_name"
-			end
-
-			qualified_object_name = case object_type
-			when "COLUMN"
-				"#{maybe_escape table_name}.#{maybe_escape object_name}"
-			when "CONSTRAINT", "RULE", "TRIGGER"
-				"#{maybe_escape object_name} ON #{maybe_escape table_name}"
-			end
-			
-			"COMMENT ON #{object_type} #{qualified_object_name} IS #{literal comment}"
-		end
-
-		private
-		
-		# Handle with the vagaries of having both strings and symbols as
-		# possible names -- we escape symbols, but leave strings to their own
-		# devices.
-		#
-		def maybe_escape(s)
-			Symbol === s ? literal(s) : s
-		end
-	end
-
-	#:nodoc:
-	# This is an annoying corner-case generator -- it doesn't handle any
-	# types by default, but it will handle any *other* type where the name of
-	# a table needs to be prefixed by a name.  The only known use case for
-	# this at present is "implicit" (that is, automatically generated by the
-	# database) constraints and indexes that get prefixed by the table name,
-	# and which are generated at a time when the calling code doesn't know the
-	# name of the table that it is generating SQL for.
-	#
-	class PrefixSqlGenerator < SqlGenerator
-		# This class doesn't handle any object types directly, and must be
-		# instantiated directly when needed
-		OBJECT_TYPES = %w{}
-
-		# The name of the table which should be prefixed to the object name
-		# that was specified when this instance was created.
-		#
-		attr_accessor :table_name
-
-		# Generate super-dooper special SQL.
-		#
-		# @see {SqlGenerator#generate}
-		#
-		def generate
-			if table_name.nil?
-				raise ArgumentError,
-				      "Cannot generate SQL for #{object_type} #{object_name} " +
-				        "without a table_name"
-			end
-
-			prefixed_object_name = "#{table_name}#{object_name}"
-			
-			if Symbol === table_name || Symbol === object_name
-				prefixed_object_name = prefixed_object_name.to_sym
-			end
-
-			g = SqlGenerator.create(object_type, prefixed_object_name, comment)
-			g.table_name = table_name if g.respond_to? :table_name
-			g.generate
-		end
-	end
-end

data/spec/sql_generator_spec.rb

@@ -1,96 +0,0 @@
-require_relative 'spec_helper'
-
-require 'sequel'
-require 'sequel/extensions/pg_comment'
-
-describe "SqlGenerator" do
-	SqlGenerator = Sequel::Extension::PgComment::SqlGenerator
-	PrefixSqlGenerator = Sequel::Extension::PgComment::PrefixSqlGenerator
-
-	context "a simple type expressed as a string" do
-		let(:generator) { SqlGenerator.create("TABLE", :foo, "Ohai!") }
-
-		it "generates quoted SQL" do
-			expect(generator.generate).
-			  to eq("COMMENT ON TABLE \"foo\" IS 'Ohai!'")
-		end
-	end
-
-	context "a simple type expressed as a crazy-case string" do
-		let(:generator) { SqlGenerator.create("TaBlE", :foo, "Ohai!") }
-
-		it "generates quoted SQL" do
-			expect(generator.generate).
-			  to eq("COMMENT ON TABLE \"foo\" IS 'Ohai!'")
-		end
-	end
-
-	context "a simple type expressed as a symbol" do
-		let(:generator) { SqlGenerator.create(:table, :foo, "Ohai!") }
-
-		it "generates quoted SQL" do
-			expect(generator.generate).
-			  to eq("COMMENT ON TABLE \"foo\" IS 'Ohai!'")
-		end
-	end
-
-	context "a multi-word type expressed as a symbol" do
-		let(:generator) { SqlGenerator.create(:event_trigger, :foo, "Ohai!") }
-
-		it "generates correct SQL" do
-			expect(generator.generate).
-			  to eq("COMMENT ON EVENT TRIGGER \"foo\" IS 'Ohai!'")
-		end
-	end
-
-	context "with a string as the object name" do
-		let(:generator) { SqlGenerator.create(:table, "foo", "Ohai!") }
-
-		it "generates unquoted SQL" do
-			expect(generator.generate).
-			  to eq("COMMENT ON TABLE foo IS 'Ohai!'")
-		end
-	end
-		
-	it "escapes the comment" do
-		expect(SqlGenerator.create(:table, :foo, "O'hai!").generate).
-		  to eq("COMMENT ON TABLE \"foo\" IS 'O''hai!'")
-	end
-
-	it "explodes if an invalid object type is given" do
-		expect do
-			SqlGenerator.create(:foobooblee, :foo, "O'hai!")
-		end.to raise_error(ArgumentError, /unrecognised object type/i)
-	end
-
-	it "sets a column comment correctly" do
-		expect(SqlGenerator.create(:column, :foo__bar_id, "Ohai, column!").generate).
-		  to eq("COMMENT ON COLUMN \"foo\".\"bar_id\" IS 'Ohai, column!'")
-	end
-
-	it "sets a constraint comment correctly" do
-		g = SqlGenerator.create(:constraint, :foo__not_for_you, "Ohai, constraint!")
-		expect(g.generate).
-		  to eq("COMMENT ON CONSTRAINT \"not_for_you\" ON \"foo\" IS 'Ohai, constraint!'")
-	end
-
-	it "sets a rule comment correctly" do
-		g = SqlGenerator.create(:rule, :foo__not_for_you, "Ohai, rule!")
-		expect(g.generate).
-		  to eq("COMMENT ON RULE \"not_for_you\" ON \"foo\" IS 'Ohai, rule!'")
-	end
-
-	it "sets a trigger comment correctly" do
-		g = SqlGenerator.create(:trigger, :foo__spoing, "Ohai, trigger!")
-		expect(g.generate).
-		  to eq("COMMENT ON TRIGGER \"spoing\" ON \"foo\" IS 'Ohai, trigger!'")
-	end
-
-	it "sets a comment on a prefixed name correctly" do
-		g = PrefixSqlGenerator.new(:index, :_pkey, "Ohai, pkey!")
-		g.table_name = :foo
-
-		expect(g.generate).
-		  to eq("COMMENT ON INDEX \"foo_pkey\" IS 'Ohai, pkey!'")
-	end
-end