plume 0.1.0 → 0.2.0

data/lib/plume/ast/literal_expression.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Plume
+	class LiteralExpression < Node
+		token :value_tk          # required
+
+		attribute :value, _Void # required
+
+		def self.new(*, value:, **) = super
+		def self.concrete(*, **) = super
+
+		# Parser may pass either tokens or attributes, so
+		# require none in `concrete` signature but ensure presence here.
+		def after_initialize
+			if @value == LiteralNil && @value_tk == LiteralNil
+				raise ArgumentError.new("missing either: :value, :value_tk")
+			end
+		end
+
+		def value
+			v = (@value == LiteralNil) ? value_tk_val : @value
+			case v
+			when LiteralNil then nil
+			when LiteralFalse then false
+			else v
+			end
+		end
+	end
+end

data/lib/plume/ast/literal_false.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Plume
+	LiteralFalse = Object.new
+	def LiteralFalse.inspect = "<LiteralFalse>"
+	LiteralFalse.freeze
+end

data/lib/plume/ast/literal_nil.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Plume
+	LiteralNil = Object.new
+	def LiteralNil.inspect = "<LiteralNil>"
+	LiteralNil.freeze
+end

data/lib/plume/ast/literal_value.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plume
+	LiteralValue = _Union(
+		nil,
+		true,
+		false,
+		:CURRENT_TIME,
+		:CURRENT_DATE,
+		:CURRENT_TIMESTAMP,
+		:*,
+		Numeric,
+		String,
+		# Blob,
+		LiteralNil,
+		LiteralFalse,
+	)
+end

data/lib/plume/ast/match_clause.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plume
+	class MatchClause < Node
+		token :match_kw
+		token :type_tk
+
+		attribute :type, Stringy
+
+		def self.new(*, type:, **) = super
+		def self.concrete(*, match_kw:, type_tk:, **) = super
+
+		def type = (@type == LiteralNil) ? type_tk_src.to_sym.upcase : @type
+	end
+end

data/lib/plume/ast/node.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Plume
+	class Node < Literal::Struct
+		extend Union::Types
+
+		Stringy = _Union(String, Symbol)
+
+		prop :full_source, _Nilable(String)
+		prop :leading, _Nilable(Token)
+		prop :trailing, _Nilable(Token)
+
+		def self.inspectable(*props)
+			@inspectable_props ||= Set.new
+			@inspectable_props.merge(props)
+		end
+
+		def self.all_inspectable_props
+			ancestors.reduce(Set.new) do |all_props, ancestor|
+				if (props = ancestor.instance_variable_get(:@inspectable_props))
+					all_props.merge(props)
+				else
+					all_props
+				end
+			end
+		end
+
+		def inspectable_props
+			all_inspectable_props = self.class.all_inspectable_props
+			all_inspectable_props.map do |prop|
+				val = __send__(prop)
+				next if val.nil? || (val.respond_to?(:empty?) && val.empty?)
+
+				[prop, val]
+			end.tap(&:compact!)
+		end
+
+		alias_method :full_inspect, :inspect
+		def inspect
+			return "#<#{self.class.name}:#{object_id}>" if inspectable_props.empty?
+
+			prop_values = inspectable_props.map do |prop, val|
+				"#{prop}=#{val.inspect}"
+			end
+
+			"#<#{self.class.name}:#{object_id} #{prop_values&.join(", ")}>"
+		end
+
+		def pretty_please(pp)
+			pp.push "#{self.class.name}("
+			pp.map(inspectable_props) do |prop, val|
+				"#{prop} = #{pp.capture { pp.prettify(val) }}"
+			end
+			pp.push ")"
+		end
+
+		# Direct child nodes in property declaration order. Arrays of nodes are flattened in
+		def children
+			self.class.literal_properties.each_with_object([]) do |property, kids|
+				value = instance_variable_get(:"@#{property.name}")
+				case value
+				when Node then kids << value
+				when Array then value.each { |v| kids << v if Node === v }
+				end
+			end
+		end
+
+		# Yields every node in the subtree depth-first, parents before their children,
+		# along with the parent (nil for the receiver)
+		def walk(parent = nil, &block)
+			return enum_for(:walk, parent) unless block
+
+			yield self, parent
+			children.each { |child| child.walk(self, &block) }
+			self
+		end
+
+		def each_node(&block)
+			return enum_for(:each_node) unless block
+
+			walk { |node, _parent| yield node }
+		end
+
+		# Byte range `[beg, fin]` of the source this node was parsed from, spanning every token
+		# in its subtree. Separators the node merely carries (`leading`/`trailing`) are left out.
+		# Nil for nodes built by hand with `.new`
+		def location
+			beg = fin = nil
+			each_token_span do |_tok, b, f|
+				beg = b if beg.nil? || b < beg
+				fin = f if fin.nil? || f > fin
+			end
+			[beg, fin].freeze if beg
+		end
+
+		def to_sql = Printer.print(self)
+
+		def source_text
+			return unless @full_source && (loc = location)
+
+			@full_source.byteslice(loc[0], loc[1] - loc[0])
+		end
+
+		def each_token_span(&block)
+			instance_variables.each do |ivar|
+				next if ivar == :@leading || ivar == :@trailing
+
+				case (value = instance_variable_get(ivar))
+				when Node then value.each_token_span(&block)
+				when Array
+					if Token === value
+						yield value
+					else
+						value.each do |v|
+							if Node === v then v.each_token_span(&block)
+							elsif Token === v then yield v
+							end
+						end
+					end
+				end
+			end
+		end
+
+		# Uses the public readers, so token-backed values like `TableName#table` come out
+		# as their parsed values rather than raw token spans
+		def deconstruct_keys(keys)
+			names = keys || self.class.literal_properties.map(&:name)
+			names.each_with_object({}) do |name, h|
+				h[name] = public_send(name) if respond_to?(name)
+			end
+		end
+
+		def self.concrete(*a, full_source:, **kw)
+			object = allocate
+			object.__send__(:initialize, *a, full_source: full_source, **kw)
+			object
+		end
+
+		# Every prop is type checked as a tree is built, so the check must never hash a node,
+		# see Plume::Union
+		def self.attribute(name, type, **kw)
+			prop name, _Nilable(_Union(type, LiteralNil)), reader: kw.fetch(:reader, false), default: LiteralNil, **kw
+			inspectable name
+		end
+
+		def self.token_names
+			ancestors.each_with_object(Set.new) do |ancestor, names|
+				names.merge(ancestor.instance_variable_get(:@token_names) || [])
+			end
+		end
+
+		def self.token(name, **kw)
+			(@token_names ||= Set.new) << name
+			prop name, _Nilable(_Union(Token, LiteralNil)), reader: false, default: LiteralNil, **kw
+
+			# Define methods for accessing token properties, like the original source text, parsed value, and location.
+			# The token reader method is simply the parsed value of the token.
+			class_eval <<-RUBY, __FILE__, __LINE__ + 1
+				# frozen_string_literal: true
+
+				def #{name}_src
+					Token.source(@full_source, @#{name})
+				end
+
+				def #{name}_val
+					Token.value(@full_source, @#{name})
+				end
+				alias_method :#{name}, :#{name}_val
+
+				def #{name}_loc
+					Token.location(@#{name})
+				end
+
+				def #{name}_tok
+					Token.token(@#{name})
+				end
+
+				def #{name}_spn
+					@#{name}
+				end
+
+				def #{name}?
+					!(@#{name}.nil? || LiteralNil.equal?(@#{name}))
+				end
+			RUBY
+		end
+
+		def self.node(name, type, **kw)
+			attribute name, _Nilable(type), **kw
+			define_node_reader(name)
+		end
+
+		def self.nodes(name, type, **kw)
+			attribute name, _Nilable(_Array(type)), **kw
+			define_node_reader(name)
+		end
+
+		# Absent children read as nil rather than the LiteralNil default
+		def self.define_node_reader(name)
+			ivar = :"@#{name}"
+			define_method(name) do
+				value = instance_variable_get(ivar)
+				LiteralNil.equal?(value) ? nil : value
+			end
+		end
+	end
+end

data/lib/plume/ast/noop_column_constraint.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plume
+	class NoOpColumnConstraint < ColumnConstraint
+		token :constraint_kw
+		token :name_tk
+
+		attribute :name, Stringy
+
+		def self.new(*, **) = super
+		def self.concrete(*, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/noop_table_constraint.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plume
+	class NoOpTableConstraint < TableConstraint
+		token :constraint_kw
+		token :name_tk
+
+		attribute :name, Stringy
+
+		def self.new(*, **) = super
+		def self.concrete(*, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/not_like_expression.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Plume
+	class NotLikeExpression < LikeExpression
+		def operator = :NOT_LIKE
+	end
+end

data/lib/plume/ast/not_null_column_constraint.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plume
+	class NotNullColumnConstraint < ColumnConstraint
+		token :constraint_kw
+		token :name_tk
+		token :not_null_kw
+
+		attribute :name, Stringy
+		node :conflict_clause, ConflictClause
+
+		def self.new(*, **) = super
+		def self.concrete(*, not_null_kw:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/null_column_constraint.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plume
+	class NullColumnConstraint < ColumnConstraint
+		token :constraint_kw
+		token :name_tk
+		token :null_kw
+
+		attribute :name, Stringy
+		node :conflict_clause, ConflictClause
+
+		def self.new(*, **) = super
+		def self.concrete(*, null_kw:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/ordering_term.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Plume
+	class OrderingTerm < Node
+		Direction = _Union(
+			:ASC, "ASC", :asc, "asc", :ASCENDING, "ASCENDING", :ascending, "ascending",
+			:DESC, "DESC", :desc, "desc", :DESCENDING, "DESCENDING", :descending, "descending",
+		)
+		Nulls = _Union(
+			:FIRST, "FIRST", :first, "first",
+			:LAST, "LAST", :last, "last",
+		)
+
+		token :collate_kw
+		token :collation_tk
+		token :direction_tk
+		token :nulls_kw
+		token :nulls_tk
+
+		node :expression, Expression
+		attribute :collation, Stringy
+		attribute :direction, Direction
+		attribute :nulls, Nulls
+
+		def self.new(*, **) = super
+		def self.concrete(*, **) = super
+
+		def collation = (@collation == LiteralNil) ? collation_tk_val&.to_sym&.upcase : @collation
+		def direction = (@direction == LiteralNil) ? direction_tk_val&.to_sym&.upcase : @direction
+		def nulls = (@nulls == LiteralNil) ? nulls_tk_val&.to_sym&.upcase : @nulls
+	end
+end

data/lib/plume/ast/over_clause.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Plume
+	class OverClause < Node
+		token :over_kw
+		token :window_lp
+		token :base_window_name_tk
+		token :partition_by_kw
+		token :order_by_kw
+		token :window_rp
+		token :window_name_tk
+
+		nodes :partitions, Expression
+		nodes :orderings, OrderingTerm
+		node :frame, FrameSpec
+		attribute :window_name, Stringy
+		attribute :base_window_name, Stringy
+
+		def self.new(*, **) = super
+		def self.concrete(*, over_kw:, **) = super
+
+		def window_name = (@window_name == LiteralNil) ? window_name_tk_val : @window_name
+		def base_window_name = (@base_window_name == LiteralNil) ? base_window_name_tk_val : @base_window_name
+	end
+end

data/lib/plume/ast/parenthetical_expression.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Plume
+	class ParentheticalExpression < Node
+		token :value_lp
+		token :value_tk
+		token :value_rp
+
+		# Hand-built trees may wrap plain Ruby values; a lambda keeps them out of the union's
+		# plain-value set, see Node.attribute
+		attribute :value, _Union(Expression, _Array(Expression), -> (v) { LiteralValue === v })
+
+		def self.new(*, value:, **) = super
+		def self.concrete(*, **) = super
+
+		# Parser may pass either tokens or attributes, so
+		# require none in `concrete` signature but ensure presence here.
+		def after_initialize
+			if @value == LiteralNil && @value_tk == LiteralNil
+				raise ArgumentError.new("missing either: :value, :value_tk")
+			end
+		end
+
+		# The child as stored - nil only for the empty list of `x IN ()`. Unlike `value`, a NULL
+		# literal stays a node, so it cannot be mistaken for that empty list
+		def contents = LiteralNil.equal?(@value) ? value_tk_val : @value
+
+		def value
+			case (v = contents)
+			when LiteralNil then nil
+			when LiteralFalse then false
+			when LiteralExpression then v.value
+			else v
+			end
+		end
+	end
+end

data/lib/plume/ast/parenthetical_source.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Plume
+	# A parenthesized join or source list used as a FROM source, like `(a JOIN b) AS ab`
+	class ParentheticalSource < Node
+		token :source_lp
+		token :source_rp
+		token :as_kw
+		token :alias_tk
+
+		node :source, _Any
+		attribute :alias, Stringy
+
+		def self.new(*, source:, **) = super
+		def self.concrete(*, source:, **) = super
+
+		def alias = (@alias == LiteralNil) ? alias_tk_val : @alias
+	end
+end

data/lib/plume/ast/pragma_statement.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/pragma.html)**
+	class PragmaStatement < Node
+		token :pragma_kw
+		token :schema_tk
+		token :dot_tk
+		token :name_tk
+		token :eq_tk # `=`, or the opening parenthesis of `PRAGMA name(value)`
+		token :value_tk
+		token :value_rp
+
+		attribute :schema, Stringy
+		attribute :name, Stringy
+
+		def self.new(*, name:, **) = super
+		def self.concrete(*, pragma_kw:, name_tk:, **) = super
+
+		def schema = (@schema == LiteralNil) ? schema_tk_val : @schema
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+
+		# As written: numbers come out as numbers, keywords and names as strings
+		inspectable def value = value_tk_val
+	end
+end

data/lib/plume/ast/primary_key_column_constraint.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Plume
+	class PrimaryKeyColumnConstraint < ColumnConstraint
+		token :constraint_kw
+		token :name_tk
+		token :primary_key_kw
+		token :direction_tk
+		token :autoincrement_kw
+
+		attribute :name, Stringy
+		attribute :direction, Stringy
+		attribute :autoincrement, _Boolean
+		node :conflict_clause, ConflictClause
+
+		def self.new(*, **) = super
+		def self.concrete(*, primary_key_kw:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+		def direction = (@direction == LiteralNil) ? direction_tk_val&.to_sym&.upcase : @direction
+		def autoincrement = (@autoincrement == LiteralNil) ? autoincrement_kw? : @autoincrement
+	end
+end

data/lib/plume/ast/primary_key_table_constraint.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Plume
+	class PrimaryKeyTableConstraint < TableConstraint
+		token :constraint_kw
+		token :name_tk
+		token :primary_key_kw
+		token :primary_key_lp
+		token :autoincrement_kw
+		token :primary_key_rp
+
+		attribute :name, Stringy
+		attribute :autoincrement, _Boolean
+		nodes :columns, IndexedColumn
+		node :conflict_clause, ConflictClause
+
+		def self.new(*, columns:, **) = super
+		def self.concrete(*, primary_key_kw:, columns:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+		def autoincrement = (@autoincrement == LiteralNil) ? autoincrement_kw? : @autoincrement
+	end
+end

data/lib/plume/ast/raise_expression.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Plume
+	class RaiseExpression < Node
+		Type = _Union(:IGNORE, :ROLLBACK, :ABORT, :FAIL)
+
+		token :raise_kw              # required
+		token :raise_lp              # required
+		token :type_kw               # required
+		token :comma                 # maybe
+		token :error_message_tk      # maybe
+		token :raise_rp              # required
+
+		attribute :type,          Type    # required
+		attribute :error_message, Expression # maybe
+
+		def self.new(*, type:, **) = super
+		def self.concrete(*, raise_kw:, raise_lp:, type_kw:, raise_rp:, **) = super
+
+		def type = (@type == LiteralNil) ? type_kw_src.to_sym.upcase : @type
+		def error_message = (@error_message == LiteralNil) ? error_message_tk_val : @error_message
+	end
+end

data/lib/plume/ast/reindex_statement.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_reindex.html)**
+	#
+	# `target` names a schema, table or index - SQLite works out which at run time
+	class ReindexStatement < Node
+		token :reindex_kw
+
+		node :target, TableName
+
+		def self.new(*, **) = super
+		def self.concrete(*, reindex_kw:, **) = super
+	end
+end

data/lib/plume/ast/release_statement.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_savepoint.html)**
+	class ReleaseStatement < Node
+		token :release_kw # RELEASE or RELEASE SAVEPOINT
+		token :name_tk
+
+		attribute :name, Stringy
+
+		def self.new(*, name:, **) = super
+		def self.concrete(*, release_kw:, name_tk:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/result_column.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plume
+	class ResultColumn < Node
+		token :as_kw
+		token :alias_tk
+		token :result_tk
+
+		node :result, Expression
+		attribute :alias, Stringy
+
+		def self.new(*, result:, **) = super
+		def self.concrete(*, **) = super
+
+		def result = (@result == LiteralNil) ? result_tk_val : @result
+		def alias = (@alias == LiteralNil) ? alias_tk_val : @alias
+	end
+end

data/lib/plume/ast/returning_clause.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Plume
+	class ReturningClause < Node
+		token :returning_kw
+
+		nodes :columns, _Union(ResultColumn, StarResultColumn)
+
+		def self.new(*, columns:, **) = super
+		def self.concrete(*, returning_kw:, columns:, **) = super
+	end
+end

data/lib/plume/ast/rollback_statement.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_transaction.html)**
+	class RollbackStatement < Node
+		token :rollback_kw
+		token :transaction_kw
+		token :name_tk
+		token :to_kw # TO or TO SAVEPOINT
+		token :savepoint_tk
+
+		attribute :savepoint, Stringy
+
+		def self.new(*, **) = super
+		def self.concrete(*, rollback_kw:, **) = super
+
+		def savepoint = (@savepoint == LiteralNil) ? savepoint_tk_val : @savepoint
+	end
+end

data/lib/plume/ast/savepoint_statement.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_savepoint.html)**
+	class SavepointStatement < Node
+		token :savepoint_kw
+		token :name_tk
+
+		attribute :name, Stringy
+
+		def self.new(*, name:, **) = super
+		def self.concrete(*, savepoint_kw:, name_tk:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end