From 78aed433db6af67b530c0f7dbc8a0acf1d6afb9a Mon Sep 17 00:00:00 2001
From: Mathieu BISKUPSKI <mathieu19g@icloud.com>
Date: Sun, 5 Jul 2026 10:57:48 +0200
Subject: [PATCH] =?UTF-8?q?Add=20eachelement/elements=20=E2=80=94=20elemen?=
 =?UTF-8?q?t-only=20child=20iteration=20(#78)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

v0.4 preserves inter-element whitespace, so children() on pretty-printed
documents interleaves whitespace Text nodes with elements; two
downstream migrations reimplemented the element-only loop by hand.
eachelement(node) is a lazy Iterators.filter over children — generic, so
it works with both Node and LazyNode — with a LazyNode specialization
built on eachchildnode so no intermediate child Vector is materialized
(-55% allocations at equal speed on a 20k-children document).
elements(node) is the collected counterpart. Tested on both readers in
the whitespace testset; version bumped to 0.4.1 (non-breaking addition).

Assisted-by: Claude (Anthropic)
---
 CHANGELOG.md     |  9 +++++++++
 Project.toml     |  2 +-
 src/XML.jl       | 26 ++++++++++++++++++++++++++
 src/lazynode.jl  |  4 ++++
 test/runtests.jl | 15 +++++++++++++++
 5 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 862b18c..7c156e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,15 @@ All notable changes to XML.jl will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-07-05
+
+### Added
+
+- `eachelement(node)` / `elements(node)` — element-only child iteration for `Node` and
+  `LazyNode`, skipping the whitespace `Text` nodes that v0.4 preserves on pretty-printed
+  documents (and any other non-element node). The explicit idiom for the common
+  "iterate the child elements" loop ([#78](https://github.com/JuliaData/XML.jl/issues/78)).
+
 ## [0.4.0] - 2026-07-03
 
 > **Upgrading from 0.3.x?** See the standalone [v0.4 migration guide](MIGRATING_TO_v0.4.md).
diff --git a/Project.toml b/Project.toml
index 33647a9..15055e3 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,6 +1,6 @@
 name = "XML"
 uuid = "72c71f33-b9b6-44de-8c94-c961784809e2"
-version = "0.4.0"
+version = "0.4.1"
 authors = ["Josh Day <emailjoshday@gmail.com> and contributors"]
 
 [weakdeps]
diff --git a/src/XML.jl b/src/XML.jl
index 981855b..c397370 100644
--- a/src/XML.jl
+++ b/src/XML.jl
@@ -4,6 +4,7 @@ export
     Node, LazyNode, NodeType, Attributes,
     CData, Comment, Declaration, Document, DTD, Element, ProcessingInstruction, Text,
     nodetype, tag, attributes, value, children, children!, eachchildnode, eachattribute,
+    eachelement, elements,
     foreach_attr,
     is_simple, simple_value, is_simple_value, sourcetext,
     depth, siblings,
@@ -233,6 +234,31 @@ that cannot have children (e.g. `Text`, `Comment`, `CData`).
 """
 children(o::Node) = something(o.children, ())
 
+"""
+    eachelement(node)
+
+Lazy iterator over the child *elements* of `node`, skipping every other node type
+(`Text`, `Comment`, `CData`, `ProcessingInstruction`, …). Since v0.4 preserves
+inter-element whitespace, `children` on pretty-printed documents interleaves
+whitespace `Text` nodes with elements — `eachelement` is the idiomatic way to
+iterate the elements only. Works with both `Node` and `LazyNode`.
+
+    for el in eachelement(node)
+        # el isa Element node
+    end
+
+See also [`elements`](@ref).
+"""
+eachelement(node) = Iterators.filter(n -> nodetype(n) === Element, children(node))
+
+"""
+    elements(node) -> Vector
+
+The child *elements* of `node` in document order — the collected counterpart of
+[`eachelement`](@ref).
+"""
+elements(node) = collect(eachelement(node))
+
 """
     is_simple(node) -> Bool
 
diff --git a/src/lazynode.jl b/src/lazynode.jl
index e48059d..cefcb6a 100644
--- a/src/lazynode.jl
+++ b/src/lazynode.jl
@@ -444,6 +444,10 @@ function eachchildnode(n::LazyNode{S}) where {S}
     LazyChildIterator{S, typeof(iter)}(n.data, iter, Ref(true))
 end
 
+# eachelement's generic definition filters children(node); for LazyNode, build on the
+# lazy child iterator instead so no intermediate Vector is materialized.
+eachelement(node::LazyNode) = Iterators.filter(n -> nodetype(n) === Element, eachchildnode(node))
+
 function Base.iterate(ci::LazyChildIterator, _ = nothing)
     ci.done[] && return nothing
     for tok in ci.iter
diff --git a/test/runtests.jl b/test/runtests.jl
index c38cdb3..bc4d2d8 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -472,6 +472,21 @@ end
         @test value(doc[1][3][1]) == "y"
     end
 
+    @testset "eachelement/elements skip non-element children" begin
+        xml = "<root>\n  <a>x</a>\n  <!-- note -->\n  <b>y</b>\n</root>"
+        for T in (Node, LazyNode)
+            doc = parse(xml, T)
+            root = only(elements(doc))
+            @test tag(root) == "root"
+            @test length(children(root)) == 7  # 4 Text runs + Comment + 2 Elements
+            @test [tag(el) for el in eachelement(root)] == ["a", "b"]
+            @test elements(root) == collect(eachelement(root))
+            @test all(n -> nodetype(n) === XML.Element, elements(root))
+            a = first(eachelement(root))
+            @test isempty(elements(children(a)[1]))  # Text leaf has no elements
+        end
+    end
+
     @testset "xml:space attribute is preserved during parsing" begin
         doc = parse("""<root xml:space="preserve"><child>  text  </child></root>""", Node)
         @test doc[1]["xml:space"] == "preserve"