Add append! and prepend! methods for NodeChildren

Author: mortenpi

docs/src/node.md

@@ -53,6 +53,8 @@ insert_before!
 insert_after!
 Base.push!(::NodeChildren{T}, ::T) where {T <: Node}
 Base.pushfirst!(::NodeChildren{T}, ::T) where {T <: Node}
+Base.append!(::NodeChildren{T}, ::Any) where T
+Base.prepend!(::NodeChildren{T}, ::Any) where T
 ```
 
 !!! note "Mutating the .children property"

src/node.jl

@@ -60,8 +60,10 @@ should only rely on the following documented APIs:
   [`last`](@ref Base.last(::NodeChildren)),
   [`isempty`](@ref Base.isempty(::NodeChildren))
 - Appending or prepending new children to a parent node can be done with the
-  [`push!`](@ref Base.push!(children::NodeChildren{T}, child::T) where {T <: Node}) and
-  [`pushfirst!`](@ref Base.pushfirst!(children::NodeChildren{T}, child::T) where {T <: Node})
+  [`push!`](@ref Base.push!(children::NodeChildren{T}, child::T) where {T <: Node}),
+  [`pushfirst!`](@ref Base.pushfirst!(children::NodeChildren{T}, child::T) where {T <: Node}),
+  [`append!`](@ref Base.append!(::NodeChildren{T}, ::Any) where T),
+  and [`prepend!`](@ref Base.prepend!(::NodeChildren{T}, ::Any) where T)
   methods
 
 Other ways to work with child nodes that do not directly reference `.children` are:
@@ -401,6 +403,50 @@ function insert_before!(node::T, sibling::T) where {T <: Node}
     return node
 end
 
+"""
+    append!(node.children::NodeChildren, children) -> NodeChildren
+
+Adds all the elements of the iterable `children` to the end of the list of children of `node`.
+If any of `children` are part of another tree, then they are unlinked from that tree first
+(see [`unlink!`](@ref)). Returns the iterator over children.
+
+!!! warning "Error during an append"
+
+    The operation is not atomic, and an error during an `append!` (e.g. due to an element of
+    the wrong type in `children`) can result in a partial append of the new children, similar
+    to how `append!` behaves with arrays
+    (see [JuliaLang/julia#15868](https://github.com/JuliaLang/julia/issues/15868)).
+"""
+function Base.append!(nodechildren::NodeChildren{T}, children) where T
+    for child in children
+        isa(child, T) || throw(ArgumentError("invalid element type ($(typeof(child))) in children, expected $T"))
+        push!(nodechildren, child)
+    end
+    return nodechildren
+end
+
+"""
+    prepend!(node.children::NodeChildren, children) -> NodeChildren
+
+Adds all the elements of the iterable `children` to the beginning of the list of children of `node`.
+If any of `children` are part of another tree, then they are unlinked from that tree first
+(see [`unlink!`](@ref)). Returns the iterator over children.
+
+!!! warning "Error during a prepend"
+
+    The operation is not atomic, and an error during a `prepend!` (e.g. due to an element of
+    the wrong type in `children`) can result in a partial prepend of the new children, similar
+    to how `append!` behaves with arrays
+    (see [JuliaLang/julia#15868](https://github.com/JuliaLang/julia/issues/15868)).
+"""
+function Base.prepend!(nodechildren::NodeChildren{T}, children) where T
+    for child in Iterators.reverse(children)
+        isa(child, T) || throw(ArgumentError("invalid element type ($(typeof(child))) in children, expected $T"))
+        pushfirst!(nodechildren, child)
+    end
+    return nodechildren
+end
+
 # Check if this is a root node. Next and previous should also be nothing, but this is not
 # enforced. This function is currently not part of the public API.
 isrootnode(node::Node) = isnothing(node.parent)

test/node.jl

@@ -1,6 +1,6 @@
 using MarkdownAST: MarkdownAST,
     Node, haschildren, @ast, copy_tree,
-    Document, Paragraph, Strong, Link, BlockQuote, CodeBlock, HTMLBlock,
+    Document, Paragraph, Strong, Link, BlockQuote, CodeBlock, HTMLBlock, Heading, Code, DisplayMath,
     NodeChildren
 using Test
 
@@ -193,4 +193,18 @@ _startswith(prefix) = s -> startswith(s, prefix)
       end
     end
     """
+
+    # append! and prepend!
+    n = @ast Document() do
+        DisplayMath("")
+        DisplayMath("")
+    end
+    cs = Node.([Paragraph(), CodeBlock("", ""), BlockQuote()])
+    @test append!(n.children, cs) isa NodeChildren
+    @test typeof.(getproperty.(n.children, :element)) == [DisplayMath, DisplayMath, Paragraph, CodeBlock, BlockQuote]
+    @test prepend!(n.children, cs) isa NodeChildren
+    @test typeof.(getproperty.(n.children, :element)) == [Paragraph, CodeBlock, BlockQuote, DisplayMath, DisplayMath]
+    # test, but with a generic iterator
+    @test append!(n.children, c for c in cs) isa NodeChildren
+    @test typeof.(getproperty.(n.children, :element)) == [DisplayMath, DisplayMath, Paragraph, CodeBlock, BlockQuote]
 end