chore(docs): Update docs for namespaces

README.md

@@ -1,6 +1,6 @@
 # Sufficiently Advanced XML Eventing Editor
 
-Your user-friendly SAX wrapper to transform XML files easily, with memory consumption in mind.
+Your user-friendly, namespace aware SAX wrapper to transform XML files easily, with memory consumption in mind.
 
 [![Saxeed CI](https://github.com/olivergondza/saxeed/actions/workflows/ci.yaml/badge.svg)](https://github.com/olivergondza/saxeed/actions/workflows/ci.yaml)
 [![Maven Central Version](https://img.shields.io/maven-central/v/com.github.olivergondza/saxeed)](https://central.sonatype.com/artifact/com.github.olivergondza/saxeed)
@@ -22,7 +22,7 @@ Saxeed strives to add as much convenience on top of plain old SAX, while adding
 
 Each tag visitor do the following: 
 
-|                                         | Tag Start              | Tag End                | Text Content |
+| operation / event                       | Tag Start              | Tag End                | Text Content |
 |-----------------------------------------|------------------------|------------------------|--------------|
 | Access Tag attributes                   | ☑                      | ☑                      | ☑            |
 | Access Parent(s) Tag attributes         | ☑                      | ☑                      | ☑            |
@@ -51,6 +51,6 @@ Saxeed is an Open Source library, and we welcome contribution. File your Issue o
 
 The library is released to maven central.
 
-To produce a new release, run ` git tag X.Y.Z` and then `mvn deploy`.
+To produce a new release, run `git tag X.Y.Z` and then `mvn deploy`.
 
 To deploy `-SNAPSHOT`, run `mvn deploy` on a commit without tag.

docs/BASICS.md

@@ -22,6 +22,7 @@ Targets specifies where the resulting XML stream should be written.
 It can be a `File` or `Path` instance to write it to a file system, or an `OutputStream` or `XMLStreamWriter` if more control is needed.
 
 Saxeed always closes the targets that it had opened (files), and never closes targets opened by the client (streams or writers).
+Likewise, it applies output buffering for target it controls, while for the client provided ones, this is a responsibility of the customer.
 
 ## Visitors
 
@@ -46,6 +47,10 @@ Each visitor can either be subscribed to all the tags in the document (`Subscrib
 
 ## Subscriptions
 
-Same as single visitor can be subscribed to multiple tag names, multiple visitors are subscribed for the same tag name.
+Same as single visitor can be subscribed to multiple tag names, multiple visitors can be subscribed the same tag name.
 Then, they are executed in the order of their addition for "opening events" and in reversed addition order for "closing events".
-So for example on `</entry>` all the visitors subscribed to "entry" (or all the tags) have their `endTag(Tag)` method called.
+So for example on `</entry>` all the visitors subscribed to "entry" have their `endTag(Tag)` method called.
+
+The subscription is declared by an instance of `Subscribed` functional interface.
+There is a convenient builder to declare the tags of interest, based on namespace, local tag name, etc.
+Customers can also provide a custom implementation if needed.

src/main/java/com/github/olivergondza/saxeed/Tag.java

@@ -19,6 +19,10 @@ public interface Tag {
      * Determine if current tag's name is @name.
      */
     boolean isNamed(String name);
+
+    /**
+     * Determine if current tag's name is @name.
+     */
     boolean isNamed(TagName name);
 
     /**
@@ -34,14 +38,26 @@ public interface Tag {
      * @return null for root tag, or when parent name differs, parent otherwise.
      */
     Tag getParent(String name);
+
+    /**
+     * Get Tag's parent iff its name is @name;
+     *
+     * @return null for root tag, or when parent name differs, parent otherwise.
+     */
     Tag getParent(TagName name);
 
     /**
      * Get the closest ancestor (wrapping tag) its name is @name.
      *
-     * @return null if there is no such ancestor, ancestor otherwise.
+     * @return null if there is no such ancestor, first ancestor otherwise.
      */
     Tag getAncestor(String name);
+
+    /**
+     * Get the closest ancestor (wrapping tag) its name is @name.
+     *
+     * @return null if there is no such ancestor, first ancestor otherwise.
+     */
     Tag getAncestor(TagName name);
 
     /**
@@ -101,6 +117,13 @@ interface Start extends Tag {
          */
         Tag.Start addChild(String name);
 
+        /**
+         * Add new child element.
+         *
+         * Its attributes and children can be added after.
+         *
+         * @return Tag instance added.
+         */
         Tag.Start addChild(TagName name);
 
         /**
@@ -112,6 +135,13 @@ interface Start extends Tag {
          */
         Tag.Start wrapWith(String name);
 
+        /**
+         * Add new parent element for the current tag.
+         *
+         * Its attributes and children can be added after.
+         *
+         * @return Tag instance created.
+         */
         Tag.Start wrapWith(TagName name);
 
         /**
@@ -141,6 +171,13 @@ interface Chars extends Tag {
          */
         Tag.Start addChild(String name);
 
+        /**
+         * Add new child element.
+         *
+         * Its attributes and children can be added after.
+         *
+         * @return Tag instance added.
+         */
         Tag.Start addChild(TagName name);
 
         /**
@@ -164,6 +201,13 @@ interface End extends Tag {
          */
         Tag.Start addChild(String name);
 
+        /**
+         * Add new child element.
+         *
+         * Its attributes and children can be added after.
+         *
+         * @return Tag instance added.
+         */
         Tag.Start addChild(TagName name);
 
         /**

src/main/java/com/github/olivergondza/saxeed/TagName.java

@@ -4,6 +4,20 @@
 
 /**
  * Namespace aware tag name.
+ *
+ * Each tag name consists of namespace URI, namespace prefix, and local name.
+ * For convenience, the qualified name is defined as "namespace prefix" + ':' + "local name".
+ *
+ * The tag name, is uniquely identified by the namespace URI and the local name.
+ * It is discouraged to base subscriptions or transformations based on the name prefix - as that is freely chosen by the document author as a shorthand for the URI.
+ *
+ * Example:
+ *
+ * <pre>
+ *     `&lt;a>` := uri=""; prefix=""; local="a"
+ *     `&lt;a xmlns="XXX">` := uri="XXX"; prefix=""; local="a" (`xmlns` can be declared on a parent tag)
+ *     `&lt;x:a xmlns:x="XXX">` := uri="XXX"; prefix="x"; local="a" (`xmlns:x` can be declared on a parent tag)
+ * </pre>
  */
 public class TagName {
 
@@ -80,6 +94,9 @@ public String getQualifiedName() {
         return qName;
     }
 
+    /**
+     * Create new TagName inheriting eventual namespace.
+     */
     public TagName inheritNamespace(String name) {
         return new TagName(uri, prefix, name);
     }

src/main/java/com/github/olivergondza/saxeed/internal/TransformationHandler.java

@@ -319,10 +319,4 @@ public void close() throws FailedWriting {
             throw new FailedWriting("Failed closing stream", e);
         }
     }
-
-    public static final class DeleteFileException extends FailedTransforming {
-        public DeleteFileException(String message) {
-            super(message);
-        }
-    }
 }