to_table is now the reference user API

Author: VEZY

README.md

@@ -56,8 +56,9 @@ write_mtg("test.mtg",mtg)
 You can expose an MTG as a `Tables.jl` source:
 
 ```julia
-mtg_table(mtg)
-symbol_table(mtg, :Leaf)
+to_table(mtg)
+to_table(mtg, symbol=:Leaf)
+to_table(mtg, vars=[:Length, :Width])
 ```
 
 If you use `DataFrames.jl`, `DataFrame(mtg)` works out of the box through the `Tables.jl` interface.

docs/src/api.md

@@ -7,7 +7,7 @@ Notable attribute APIs:
 - `attribute`, `attribute!`, `attributes`, `attribute_names`
 - `add_column!`, `drop_column!`, `rename_column!`
 - `descendants_strategy`, `descendants_strategy!` (choose automatic/direct/indexed descendants retrieval)
-- `to_table`, `symbol_table`, `mtg_table` (`Tables.jl` sources)
+- `to_table` (`Tables.jl` source/sink entry-point)
 
 ```@index
 ```

docs/src/get_started.md

@@ -53,13 +53,13 @@ descendants(mtg, :length_mm)
 Or by getting a tabular view of your MTG:
 
 ```@example usepkg
-mtg_table(mtg)
+to_table(mtg)
 ```
 
 You can also select only a subset of attributes:
 
 ```@example usepkg
-mtg_table(mtg, [:Length, :Width])
+to_table(mtg, vars=[:Length, :Width])
 ```
 
 Or directly transforming the MTG into a DataFrame:

docs/src/tutorials/2.descendants_ancestors_filters.md

@@ -87,7 +87,7 @@ get_attributes(get_root(node_5))
 A simple way to get all nodes and their attributes is to use the unified table view:
 
 ```@example usepkg
-mtg_table(mtg)
+to_table(mtg)
 ```
 
 ## Descendants

docs/src/tutorials/3.transform_mtg.md

@@ -111,7 +111,7 @@ descendants(mtg, :length_m)
 We can also inspect values through the MTG table view:
 
 ```@example usepkg
-mtg_table(mtg)
+to_table(mtg)
 ```
 
 We can also provide several input variables if we need:
@@ -125,7 +125,7 @@ Here we provide the input attributes as a Vector of Symbols (could be String als
 Let's see the results:
 
 ```@example usepkg
-mtg_table(mtg)
+to_table(mtg)
 ```
 
 The new name of the attribute (the RHS) is optional though. We could write our first example as:
@@ -241,15 +241,15 @@ mtg_select = deepcopy(mtg)
 
 select!(mtg_select, :Length => (x -> x / 10) => :length_m, :Width, ignore_nothing = true)
 
-mtg_table(mtg_select)
+to_table(mtg_select)
 ```
 
 There is also a copy-returning version of the function (`select`, without `!`):
 
 ```@example usepkg
 mtg_select = select(mtg, :Length => (x -> x / 10) => :length_m, :Width, ignore_nothing = true)
 
-mtg_table(mtg_select)
+to_table(mtg_select)
 ```
 
 ## Traverse an MTG

docs/src/tutorials/4.convert_mtg.md

@@ -15,7 +15,7 @@ That's why `MultiScaleTreeGraph.jl` provides functions to expose an MTG as a `Ta
 To get a unified table view of the MTG, you can use:
 
 ```@example usepkg
-tbl = mtg_table(mtg)
+tbl = to_table(mtg)
 ```
 
 The unified table reports MTG topology columns plus all attributes:
@@ -30,19 +30,26 @@ The unified table reports MTG topology columns plus all attributes:
 If you only need a few attributes, you can select them directly:
 
 ```@example usepkg
-mtg_table(mtg, [:Width, :Length])
+to_table(mtg, vars=[:Width, :Length])
 ```
 
 It is also possible to get a per-symbol table:
 
 ```@example usepkg
-leaf_tbl = symbol_table(mtg, :Leaf)
+leaf_tbl = to_table(mtg, symbol=:Leaf)
 ```
 
 Per-symbol tables can also select attributes:
 
 ```@example usepkg
-symbol_table(mtg, :Leaf, [:Width, :Length])
+to_table(mtg, symbol=:Leaf, vars=[:Width, :Length])
+```
+
+You can also materialize directly into a sink when available in your environment:
+
+```julia
+using DataFrames
+df = to_table(mtg, vars=[:Width, :Length], sink=DataFrame)
 ```
 
 If you use `DataFrames.jl` in your own project, `DataFrame(mtg)` still works because MTGs implement the `Tables.jl` interface.

docs/src/tutorials/6.add_remove_nodes.md

@@ -70,7 +70,7 @@ mtg
 And the attributes:
 
 ```@example usepkg
-mtg_table(mtg)
+to_table(mtg)
 ```
 
 ### Inserting nodes

src/MultiScaleTreeGraph.jl

@@ -96,7 +96,6 @@ export attribute, attribute!, attributes, attribute_names
 export add_column!, drop_column!, rename_column!
 export descendants_strategy, descendants_strategy!
 export columnarize!
-export symbol_table, mtg_table
 export to_table
 export list_nodes
 export get_classes

src/conversion/Tables.jl

@@ -227,18 +227,45 @@ function mtg_table(mtg::Node, vars=nothing)
     ColumnTable(names_, cols_)
 end
 
+@inline function _materialize_table(source, sink)
+    sink === nothing && return source
+
+    # Preferred path for Tables-compatible sinks (e.g. DataFrame type/instance).
+    materializer = try
+        Tables.materializer(sink)
+    catch
+        try
+            Tables.materializer(typeof(sink))
+        catch
+            nothing
+        end
+    end
+    materializer !== nothing && return materializer(source)
+
+    # Generic fallback for callable sinks, e.g. sink = x -> MyType(x)
+    applicable(sink, source) && return sink(source)
+
+    error(
+        "Unsupported sink $(sink). ",
+        "Provide a Tables.jl sink (type or instance, e.g. DataFrame) or a callable that accepts a table."
+    )
+end
+
 """
-    to_table(mtg::Node; symbol=nothing, vars=nothing)
+    to_table(mtg::Node; symbol=nothing, vars=nothing, sink=nothing)
+
+Generic table conversion entry-point.
 
-Convenience helper to get a Tables.jl-compatible view from an MTG.
-- `symbol=nothing`: unified traversal-ordered table (`mtg_table`)
-- `symbol=<symbol>`: per-symbol table (`symbol_table`)
+- `symbol=nothing`: unified traversal-ordered table
+- `symbol=<symbol>`: per-symbol table
 - `vars`: optional attribute selection (`Symbol`/`String`/vector/tuple)
+- `sink`: optional sink materialization (e.g. `sink=DataFrame` if `DataFrames.jl` is loaded)
 """
-function to_table(mtg::Node; symbol=nothing, vars=nothing)
-    symbol === nothing ? mtg_table(mtg, vars) : symbol_table(mtg, symbol, vars)
+function to_table(mtg::Node; symbol=nothing, vars=nothing, sink=nothing)
+    source = symbol === nothing ? mtg_table(mtg, vars) : symbol_table(mtg, symbol, vars)
+    _materialize_table(source, sink)
 end
 
 Tables.istable(::Type{<:Node}) = true
 Tables.columnaccess(::Type{<:Node}) = true
-Tables.columns(mtg::Node) = mtg_table(mtg)
+Tables.columns(mtg::Node) = to_table(mtg)

src/print_MTG/print.jl

@@ -31,7 +31,7 @@ function Base.print(node::Node; leading::AbstractString="", io::IO=stdout, limit
 end
 
 function Base.print(node::Node, vars; leading::AbstractString="", io::IO=stdout)
-    table = mtg_table(node)
+    table = to_table(node)
     vars_ = vars isa Union{Tuple,AbstractVector} ? Symbol.(vars) : Symbol[Symbol(vars)]
     keep = Symbol[:node_id, :symbol, :scale, :index, :link, :parent_id]
     append!(keep, vars_)