table

README

Table Token

Part of Entiqon / Database / Token

🌱 Overview

The token.Table type represents a SQL table (or subquery) token with optional alias.
It delegates parsing and classification to the shared resolver and expression_kind modules,
enforcing strict construction rules and exposing multiple forms for logging, debugging, and SQL rendering.

---

Construction Rules

Tables are created using table.New(...):

1. Plain table

   • table.New("users") → users

2. Aliased (inline)

   • table.New("users u") → users AS u
   • table.New("users AS u") → users AS u

3. Aliased (explicit arguments)

   • table.New("users", "u") → users AS u
   • Alias may also be any fmt.Stringer implementation
   • Always validated via resolver

4. Subquery

   • table.New("(SELECT COUNT(*) FROM users) AS t") → subquery with alias
   • table.New("(SELECT COUNT(*) FROM users)", "t") → subquery with alias
     ⚠️ Subqueries must have an alias, otherwise the token is errored.

5. Errors

   • Empty input → errored
   • Invalid alias (including reserved keywords such as AS, FROM, SELECT) → errored
   • Passing a token directly (e.g. table.New(table.New("users"))) → errored, with hint to use Clone()
   • Invalid types (e.g. table.New(123)) → errored
   • Too many tokens or malformed input → errored

---

Contracts Implemented

• TableToken →
• Clonable → Clone() (safe duplication)
• Debuggable → Debug() (developer diagnostics with flags)
• Errorable → IsErrored(), Error()
• Rawable → Raw() (generic SQL fragment), IsRaw()
• Renderable → Render() (canonical SQL form)
• Stringable → String() (human-facing logs)
• Validable → IsValid() (validity check based on resolver rules)

---

Logging

• String()
  Concise, log-friendly:

  ✅ table(users AS u)
  ❌ table("users AS"): invalid format "users AS"
  

• Debug()
  Verbose developer output with flags:

  ✅ table("users AS u"): [raw:false, aliased:true, errored:false]
  ❌ table("users AS"): [raw:false, aliased:false, errored:true] {err=invalid format "users AS"}
  

---

📄 License

MIT — © Entiqon Project

Documentation

Overview

Package table defines the token.Table type, which represents a SQL table or subquery source with optional alias. It provides strict construction rules, error preservation, and multiple forms of string output.

A Table always preserves the original user input (for auditability), normalizes name and alias when possible, and never panics. Invalid inputs produce an errored Table that can be inspected via the Errorable contract.

Construction

Tables are created using New(...):

• Plain table: table.New("users") → users

• Aliased (inline): table.New("users u") → users AS u table.New("users AS u") → users AS u

• Aliased (explicit arguments): table.New("users", "u") → users AS u

• Subquery: table.New("(SELECT COUNT(*) FROM users) AS t") → subquery with alias table.New("(SELECT COUNT(*) FROM users)", "t") → subquery with alias

• Errors: table.New("") → errored table.New("users AS") → errored table.New("users x y z") → errored

Contracts

Table implements the following contracts from db/contract:

• Renderable → Render()
• Rawable → Raw(), IsRaw()
• Stringable → String()
• Debuggable → Debug()
• Clonable → Clone()
• Errorable → IsErrored(), Error()

Logging

• String() → concise, audit-friendly logs
• Debug() → verbose, developer diagnostics

Philosophy

• Never panic: always returns a *Table, even if errored.
• Auditability: preserves user input in all cases.
• Strict rules: invalid forms are rejected early.
• Delegation: parsing logic resides in table.New, not in builders.

Index

• type Token
  • func New(input ...any) Token

Examples

• New (ExplicitAlias)
• New (InlineAlias)
• New (Plain)
• New (Subquery)
• Token (Clone)
• Token (CloneHint)
• Token (Debug)
• Token (Error)
• Token (InvalidType)
• Token (IsAliased)
• Token (IsRaw)
• Token (IsValid)
• Token (Raw)
• Token (String)

Types

type Token

type Token interface {
	// BaseToken provides identity information:
	//   - Input()   → original input string
	//   - Expr()    → resolved core expression (e.g. table name)
	//   - Alias()   → alias if present
	//   - ExpressionKind()    → classified expression kind
	//   - IsAliased() → true if alias is present
	//   - IsValid()   → true if structurally valid
	contract.BaseToken

	// Clonable provides safe duplication of a table token,
	// preserving its state without sharing underlying pointers.
	contract.Clonable[Token]

	// Debuggable produces verbose developer-oriented diagnostics
	// including raw/alias/errored flags.
	contract.Debuggable

	// Errorable surfaces explicit error states and never panics.
	// SetError(err) preserves input for auditability.
	contract.Errorable[Token]

	// Rawable returns a dialect-agnostic raw fragment
	// suitable for embedding directly in SQL.
	contract.Rawable

	// Renderable produces canonical SQL output (expr + alias).
	contract.Renderable

	// Stringable produces a concise log/debug string
	// prefixed with validity markers (✅/❌).
	contract.Stringable

	// Validable exposes structural validation via IsValid().
	contract.Validable

	// Name returns the normalized table identifier
	// (base name without alias). For subqueries, this is
	// the unaliased expression string.
	Name() string
}

Token defines the contract implemented by all table tokens. A table token represents a SQL source (table or subquery) with optional alias, and supports rendering, cloning, validation, and debugging.

Responsibilities:

• Enforce strict construction and validation of table sources.
• Provide canonical SQL output (Render) and raw fragments (Raw).
• Surface validation errors explicitly (Errorable).
• Expose identity and structural details (BaseToken, Name).

This contract is consumed by higher-level builders (e.g. SelectBuilder) to safely assemble SQL FROM and JOIN clauses.

Implementations:

• *table (default constructor: table.New(...))

Example (Clone)

ExampleTable_Clone demonstrates the Clone() method.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users u")
	clone := t.Clone()
	fmt.Println(clone.Render())
}

Output:
users AS u

Example (CloneHint)

ExampleToken_cloneHint demonstrates passing a token directly (unsupported).

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New(table.New("users"))
	fmt.Println(t.IsErrored())
	fmt.Println(t.Error())
}

Output:
true
unsupported type; if you want to create a copy, use Clone() instead

Example (Debug)

ExampleTable_Debug demonstrates Debug() output for diagnostics.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users u")
	fmt.Println(t.Debug())

}

Output:
Table("users u"): [raw:false, aliased:true, errored:false]

Example (Error)

ExampleTable_Error demonstrates handling of invalid input.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users AS") // invalid alias
	fmt.Println(t.String())
	fmt.Println(t.IsErrored())
	fmt.Println(t.Error())

}

Output:
Table("users AS"): invalid alias: AS
true
invalid alias: AS

Example (InvalidType)

ExampleToken_invalidType demonstrates handling of non-string input.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New(123)
	fmt.Println(t.IsErrored())
	fmt.Println(t.Error())
}

Output:
true
expr has invalid format (type int)

Example (IsAliased)

ExampleTable_IsAliased demonstrates the IsAliased() method.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users u")
	fmt.Println(t.IsAliased())
}

Output:
true

Example (IsRaw)

ExampleTable_IsRaw demonstrates the IsRaw() method.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t1 := table.New("users u")
	fmt.Println(t1.IsRaw())

	t2 := table.New("(SELECT COUNT(id) FROM users)", "t")
	fmt.Println(t2.IsRaw())
}

Output:
false
true

Example (IsValid)

ExampleTable_IsValid demonstrates the IsValid() method.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users u")
	fmt.Println(t.IsValid())

	bad := table.New("users AS") // invalid
	fmt.Println(bad.IsValid())
}

Output:
true
false

Example (Raw)

ExampleTable_Raw demonstrates the Raw() method.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users u")
	fmt.Println(t.Raw())
}

Output:
users AS u

Example (String)

ExampleTable_String demonstrates String() output for logging.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users", "u")
	fmt.Println(t.String())

}

Output:
Table(users AS u)

func New

func New(input ...any) Token

New constructs a new Table from user input.

Accepted forms:

• table.New("users") → name="users"
• table.New("users u") → name="users", alias="u"
• table.New("users AS u") → name="users", alias="u"
• table.New("users", "u") → name="users", alias="u", isRaw=true
• table.New("(SELECT ...)", "t") → name="(SELECT ...)", alias="t", isRaw=true
• table.New("(SELECT ...) AS t") → name="(SELECT ...)", alias="t", isRaw=true

The first argument is always preserved verbatim in input. If construction fails, the returned table is errored but still carries the original input for diagnostics.

Example (ExplicitAlias)

ExampleNew_explicitAlias demonstrates explicit aliasing with two arguments.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users", "u")
	fmt.Println(t.Render())
}

Output:
users AS u

Example (InlineAlias)

ExampleNew_inlineAlias demonstrates inline aliasing.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users u")
	fmt.Println(t.Render())
}

Output:
users AS u

Example (Plain)

ExampleNew_plain demonstrates creating a plain table.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("users")
	fmt.Println(t.Render())
}

Output:
users

Example (Subquery)

ExampleNew_subquery demonstrates creating a subquery table with alias.

package main

import (
	"fmt"

	"github.com/entiqon/db/token/table"
)

func main() {
	t := table.New("(SELECT COUNT(id) FROM users)", "t")
	fmt.Println(t.Render())
}

Output:
(SELECT COUNT(id) FROM users) AS t