plume 0.1.0 → 0.3.0

data/lib/plume/ast/generated_as_column_constraint.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Plume
+	class GeneratedAsColumnConstraint < ColumnConstraint
+		Type = _Union(:STORED, :VIRTUAL)
+
+		token :constraint_kw
+		token :name_tk
+		token :as_kw
+		token :as_lp
+		token :as_rp
+		token :type_tk
+
+		attribute :name, Stringy
+		attribute :type, Type
+		node :expression, Expression
+
+		def self.new(*, expression:, **) = super
+		def self.concrete(*, as_kw:, as_lp:, expression:, as_rp:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+		def type = (@type == LiteralNil) ? type_tk_val&.to_sym&.upcase : @type
+	end
+end

data/lib/plume/ast/indexed_column.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Plume
+	class IndexedColumn < Node
+		token :name_tk
+		token :collate_kw
+		token :collation_tk
+		token :direction_tk
+		token :nulls_tk
+
+		attribute :name, Stringy
+		attribute :collation, Stringy
+		attribute :direction, Stringy
+		attribute :nulls, OrderingTerm::Nulls
+
+		def self.new(*, name:, **) = super
+		def self.concrete(*, name_tk:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+		def collation = (@collation == LiteralNil) ? Node.collation_name(collation_tk_val) : @collation
+		def direction = (@direction == LiteralNil) ? direction_tk_val&.to_sym&.upcase : @direction
+		def nulls = (@nulls == LiteralNil) ? nulls_tk_tok&.last : @nulls
+	end
+end

data/lib/plume/ast/insert_statement.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_insert.html)**
+	#
+	# ```sql
+	# insert or ignore into t (a, b) select x, y from u on conflict (a) do nothing returning *
+	# ```
+	#
+	# Rows come from `select` (a SelectStatement, VALUES included) or are DEFAULT VALUES.
+	class InsertStatement < Node
+		include ConflictResolution
+
+		token :insert_kw # INSERT [OR …], or REPLACE
+		token :into_kw
+		token :columns_lp
+		token :columns_rp
+		token :default_values_kw
+
+		node :with_clause, WithClause
+		node :table, TableName
+		nodes :columns, ColumnName
+		node :select, SelectStatement
+		nodes :upserts, UpsertClause
+		node :returning, ReturningClause
+
+		def self.new(*, table:, **) = super
+		def self.concrete(*, insert_kw:, into_kw:, table:, **) = super
+
+		inspectable def or_action = TOKEN_TO_RESOLUTION[insert_kw_tok]
+		inspectable def default_values = default_values_kw?
+
+		def column_names = columns&.map(&:column)
+	end
+end

data/lib/plume/ast/join.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Plume
+	class Join < Node
+		node :operator, JoinOperator
+		node :source, _Any
+		node :constraint, _Union(JoinOnConstraint, JoinUsingConstraint)
+
+		def self.new(*, operator:, source:, **) = super
+		def self.concrete(*, operator:, source:, **) = super
+	end
+end

data/lib/plume/ast/join_clause.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plume
+	# `left` followed by one or more joins. Comma-separated sources are joins too,
+	# with a `:COMMA` operator
+	class JoinClause < Node
+		node :left, _Any
+		nodes :joins, Join
+
+		def self.new(*, left:, joins:, **) = super
+		def self.concrete(*, left:, joins:, **) = super
+
+		def sources = [left, *joins.map(&:source)]
+	end
+end

data/lib/plume/ast/join_on_constraint.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Plume
+	class JoinOnConstraint < Node
+		token :on_kw
+
+		node :expression, Expression
+
+		def self.new(*, expression:, **) = super
+		def self.concrete(*, on_kw:, expression:, **) = super
+	end
+end

data/lib/plume/ast/join_operator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Plume
+	class JoinOperator < Node
+		Kind = _Union(:COMMA, :INNER, :LEFT, :RIGHT, :FULL, :CROSS)
+
+		token :operator_tk
+
+		attribute :kind, Kind
+		attribute :natural, _Boolean
+
+		def self.new(*, kind:, **) = super
+		def self.concrete(*, operator_tk:, **) = super
+
+		def kind
+			return @kind unless @kind == LiteralNil
+
+			keywords = operator_keywords
+			return :COMMA if keywords == [:COMMA]
+
+			(keywords & [:LEFT, :RIGHT, :FULL, :CROSS]).first || :INNER
+		end
+
+		def natural = (@natural == LiteralNil) ? operator_keywords.include?(:NATURAL) : @natural
+		def outer? = [:LEFT, :RIGHT, :FULL].include?(kind)
+
+		private
+
+		def operator_keywords = Array(operator_tk_tok)
+	end
+end

data/lib/plume/ast/join_using_constraint.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Plume
+	class JoinUsingConstraint < Node
+		token :using_kw
+		token :columns_lp
+		token :columns_rp
+
+		nodes :columns, ColumnName
+
+		def self.new(*, columns:, **) = super
+		def self.concrete(*, using_kw:, columns:, **) = super
+
+		def column_names = columns.map(&:column)
+	end
+end

data/lib/plume/ast/like_expression.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Plume
+	# `left [NOT] LIKE right [ESCAPE escape]`. GLOB, REGEXP and MATCH have no ESCAPE
+	# and are plain `BinaryExpression`s
+	class LikeExpression < Node
+		token :operator_tk
+		token :escape_kw
+
+		node :left, Expression
+		node :right, Expression
+		node :escape, Expression
+
+		def self.new(*, left:, right:, **) = super
+		def self.concrete(*, operator_tk:, left:, right:, **) = super
+
+		def operator = :LIKE
+	end
+end

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,330 @@
+# frozen_string_literal: true
+
+module Plume
+	class Node < Literal::Struct
+		extend Union::Types
+
+		Stringy = _Union(String, Symbol)
+
+		def self.literal_properties
+			super
+		rescue => error
+			raise unless defined?(Ractor::IsolationError) && Ractor::IsolationError === error
+
+			raise Ractor::IsolationError, "#{name} is not shareable yet, call Plume.eager_load! from the main Ractor first " \
+				"(or #{name}.make_shareable! for a class defined after it)"
+		end
+
+		def self.make_shareable!
+			Plume.make_shareable(literal_properties)
+			Plume.make_shareable(@inspectable_props)
+			Plume.make_shareable(@token_names)
+			self
+		end
+
+		def self.prop(name, ...)
+			raise FrozenError, "cannot add #{name} to #{self.name} after Plume.eager_load! has frozen its props" if literal_properties.frozen?
+
+			super
+		end
+
+		singleton_class.prepend(LiteralPatches::NodeSchema) if LiteralPatches::SCHEMA_HOLDS_MUTEX
+
+		prop :full_source, _Nilable(String)
+		prop :leading, _Nilable(Token)
+		prop :trailing, _Nilable(Token)
+
+		# A collation's name, upcased as a symbol. A symbol cannot hold bytes that
+		# are not valid UTF-8, so a name with those stays the string it was
+		def self.collation_name(name) = name&.valid_encoding? ? name.to_sym.upcase : name
+
+		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 each direct child with the prop it sits in, and its index when that prop holds an array
+		def each_child
+			# Each as one array: TruffleRuby's Enumerator hands only the first of several yielded values to `count`
+			return Enumerator.new { |y| each_child { |*slot| y << slot } } unless block_given?
+
+			self.class.literal_properties.each do |property|
+				case (value = instance_variable_get(:"@#{property.name}"))
+				when Node then yield value, property.name, nil
+				when Array then value.each_with_index { |v, i| yield v, property.name, i if Node === v }
+				end
+			end
+			self
+		end
+
+		# Yields every node in the subtree depth-first, parents before their children,
+		# along with the parent (nil for the receiver). Without recursing, so a tree as
+		# deep as SQLite allows does not run out of stack
+		def walk(parent = nil)
+			return enum_for(:walk, parent) unless block_given?
+
+			stack = [[self, parent]]
+			while (node, up = stack.pop)
+				yield node, up
+				node.children.reverse_each { |child| stack << [child, node] }
+			end
+			self
+		end
+
+		# Like `walk`, but also says where under the parent each node sits: the prop's name,
+		# and the index into it when it holds an array
+		def walk_with_slots(parent = nil)
+			return Enumerator.new { |y| walk_with_slots(parent) { |*slot| y << slot } } unless block_given?
+
+			stack = [[self, parent, nil, nil]]
+			while (node, up, prop, index = stack.pop)
+				yield node, up, prop, index
+				start = stack.size
+				node.each_child { |child, name, i| stack << [child, node, name, i] }
+				stack[start..] = stack[start..].reverse
+			end
+			self
+		end
+
+		# A copy of the tree with nodes replaced. The block sees every node as `walk_with_slots` does,
+		# and returns it to keep it, or another node to put in its place - which is not descended into.
+		# Nodes on the way to a replacement are copied, everything else is shared with the original,
+		# which stays as it was. A replacement built with `.new` has no source, so print the result
+		# with `to_sql` rather than reading its `source_text`
+		def transform
+			replaced = {}.compare_by_identity
+			kept = []
+			stack = [[self, nil, nil, nil]]
+			while (node, up, prop, index = stack.pop)
+				replacement = yield node, up, prop, index
+				if replacement.equal?(node)
+					kept << node
+					node.each_child.reverse_each { |child, name, i| stack << [child, node, name, i] }
+				else
+					replaced[node] = replacement
+				end
+			end
+
+			# Parents come before their children in `kept`, so going backwards rebuilds children first
+			kept.reverse_each do |node|
+				changes = {}
+				node.each_child do |child, name, i|
+					next unless replaced.key?(child)
+
+					changes[name] ||= node.instance_variable_get(:"@#{name}").dup if i
+					i ? changes[name][i] = replaced[child] : changes[name] = replaced[child]
+				end
+				replaced[node] = node.with_props(changes) unless changes.empty?
+			end
+			replaced.fetch(self, self)
+		end
+
+		# A copy with some props set to new values, checked against their types
+		def with_props(changes)
+			copy = dup
+			changes.each do |name, value|
+				property = self.class.literal_properties[name]
+				raise TypeError, "#{self.class.name}##{name} cannot be #{value.inspect}" unless property.type === value
+
+				copy.instance_variable_set(:"@#{name}", value)
+			end
+			copy
+		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
+
+		# `pretty: true` lays the SQL out over lines, see PrettyPrinter for `indent_size:`, `max_line_length:`
+		# and `commas_start_of_line:`. With `comments: true`, the comments right before and after the node
+		# in its source come along - a header above a statement, or the sqlcommenter tags after it. Those
+		# inside it are left out. A `--` comment after it becomes a `/* */` one, so a semicolon after it is
+		# not swallowed
+		def to_sql(pretty: false, comments: false, **layout)
+			sql = pretty ? PrettyPrinter.print(self, **layout) : Printer.print(self)
+			return sql unless comments
+
+			before, after = Comments.around(self)
+			lead = before.map { |c| c.text + (c.block? ? " " : "\n") }.join
+			tail = after.map { |c| " #{((c.block? || c.body.include?("*/")) ? c.text : "/*#{c.body} */")}" }.join
+			lead + sql + tail
+		end
+
+		# A plain hash of the whole tree that JSON can carry, which `Plume.load` turns back into it
+		def dump = Dump.dump(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. Evaluated from a string
+		# because a method defined with a block cannot be called from another Ractor
+		def self.define_node_reader(name)
+			class_eval <<-RUBY, __FILE__, __LINE__ + 1
+				def #{name}
+					LiteralNil.equal?(@#{name}) ? nil : @#{name}
+				end
+			RUBY
+		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