P

engine/src/main/java/pro/verron/officestamper/api/AbstractCommentProcessor.java

@@ -56,11 +56,6 @@ public R getCurrentRun() {
         this.currentRun = run;
     }
 
-    //TODO replace api
-    @Override public Object getParent() {
-        return paragraph.parent();
-    }
-
     public Paragraph getParagraph() {
         return paragraph;
     }
@@ -71,7 +66,7 @@ public Paragraph getParagraph() {
      * @deprecated use {@link #setParagraph(Paragraph)} instead
      */
     @Deprecated(since = "2.6", forRemoval = true) public void setParagraph(P paragraph) {
-        this.paragraph = StandardParagraph.from(paragraph);
+        this.paragraph = StandardParagraph.from((DocxPart) paragraph.getParent(), paragraph);
     }
 
     public void setParagraph(Paragraph paragraph) {

engine/src/main/java/pro/verron/officestamper/api/Comment.java

@@ -46,7 +46,7 @@ public interface Comment {
      *
      * @param commentRangeEnd the {@link CommentRangeEnd} object to set
      */
-    // TODO_LATER: Remove the setting method from interface to increase immutability
+    // TODO: Remove the setting method from interface to increase immutability
     void setCommentRangeEnd(CommentRangeEnd commentRangeEnd);
 
     /**
@@ -61,7 +61,7 @@ public interface Comment {
      *
      * @param commentRangeStart the CommentRangeStart object to set
      */
-    // TODO_LATER: Remove the setting method from interface to increase immutability
+    // TODO: Remove the setting method from interface to increase immutability
     void setCommentRangeStart(CommentRangeStart commentRangeStart);
 
     /**
@@ -76,7 +76,7 @@ public interface Comment {
      *
      * @param commentReference the comment reference to set
      */
-    // TODO_LATER: Remove the setting method from interface to increase immutability
+    // TODO: Remove the setting method from interface to increase immutability
     void setCommentReference(R.CommentReference commentReference);
 
     /**
@@ -91,7 +91,7 @@ public interface Comment {
      *
      * @param comments the set of Comment objects representing the children of the comment
      */
-    // TODO_LATER: Remove the setting method from interface to increase immutability
+    // TODO: Remove the setting method from interface to increase immutability
     void setChildren(Set<Comment> comments);
 
     /**
@@ -106,7 +106,7 @@ public interface Comment {
      *
      * @param comment the comment to set
      */
-    // TODO_LATER: Remove the setting method from interface to increase immutability
+    // TODO: Remove the setting method from interface to increase immutability
     void setComment(Comments.Comment comment);
 
     /**

engine/src/main/java/pro/verron/officestamper/api/CommentProcessor.java

@@ -22,8 +22,6 @@ public interface CommentProcessor {
      */
     void setCurrentRun(@Nullable R run);
 
-    Object getParent();
-
     /**
      * This method is called after all comments in the .docx template have been passed to the comment processor.
      * All manipulations of the .docx document SHOULD BE done in this method.

engine/src/main/java/pro/verron/officestamper/api/DocxDocument.java

@@ -1,12 +1,10 @@
 package pro.verron.officestamper.api;
 
 import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
-import org.docx4j.openpackaging.parts.WordprocessingML.CommentsPart;
 
 import java.util.stream.Stream;
 
 public interface DocxDocument {
     WordprocessingMLPackage document();
     Stream<DocxPart> streamParts(String type);
-    CommentsPart commentsPart();
 }

engine/src/main/java/pro/verron/officestamper/api/OfficeStamperException.java

@@ -1,5 +1,7 @@
 package pro.verron.officestamper.api;
 
+import java.util.function.Supplier;
+
 /**
  * OfficeStamperException is a subclass of RuntimeException that represents an exception that can be thrown during the
  * processing of an Office document using the OfficeStamper library.
@@ -51,4 +53,7 @@ public OfficeStamperException() {
         super("Unexpected exception");
     }
 
+    public static Supplier<OfficeStamperException> throwing(String message) {
+        return () -> new OfficeStamperException(message);
+    }
 }

engine/src/main/java/pro/verron/officestamper/api/Paragraph.java

@@ -1,21 +1,51 @@
 package pro.verron.officestamper.api;
 
+import org.docx4j.wml.Comments;
 import org.docx4j.wml.P;
 import org.docx4j.wml.R;
-import pro.verron.officestamper.core.StandardComment;
 
 import java.util.List;
+import java.util.Optional;
+import java.util.function.Consumer;
 
 /**
  * The Paragraph interface represents a paragraph in a text document.
  * It provides methods for replacing a placeholder within the paragraph and retrieving the paragraph as a string.
  */
 public interface Paragraph {
 
-    StandardComment fakeComment(DocxPart source, Placeholder placeholder);
+    /**
+     * Creates a processor context for the given placeholder within this paragraph.
+     *
+     * @param placeholder The placeholder to create a context for.
+     * @return The processor context for the specified placeholder.
+     */
+    ProcessorContext processorContext(Placeholder placeholder);
+
+    /**
+     * Replaces specified contiguous elements within the paragraph with new elements.
+     *
+     * @param toRemove The list of elements to be removed from the paragraph.
+     * @param toAdd The list of elements to be added to the paragraph.
+     */
+    void replace(List<P> toRemove, List<P> toAdd);
 
-    R firstRun(); // TODO replace with API not exposing the docx4j API directly
+    /**
+     * Removes the paragraph from the document.
+     * This method is intended to be used when a paragraph needs to be deleted.
+     */
+    void remove();
 
+    /**
+     * Retrieves the paragraph associated with this object.
+     * TODO replace with API not exposing the docx4j API directly
+     *
+     * @return the paragraph object
+     *
+     * @deprecated As of version 2.6, due to its direct exposure of the docx4j API. It is scheduled for removal in
+     * the future.
+     */
+    @Deprecated(since = "2.6", forRemoval = true)
     P getP(); // TODO replace with API not exposing the docx4j API directly
 
     /**
@@ -61,7 +91,21 @@ public interface Paragraph {
      */
     String asString();
 
-    List<Object> paragraphContent(); // TODO replace with API not exposing the docx4j API directly
+    /**
+     * Applies the specified consumer function to the paragraph content.
+     *
+     * @param pConsumer The consumer function to apply to the paragraph content.
+     */
+    void apply(Consumer<P> pConsumer);
+
+    /**
+     * Retrieves the parent of the current paragraph that matches the specified class type.
+     *
+     * @param aClass The class type to match for the parent element.
+     * @param <T> The type of the parent element to be returned.
+     * @return An {@code Optional} containing the matched parent element if found, otherwise an empty {@code Optional}.
+     */
+    <T> Optional<T> parent(Class<T> aClass);
 
-    Object parent(); // TODO replace with API not exposing the docx4j API directly
+    Optional<Comments.Comment> getComment();
 }

engine/src/main/java/pro/verron/officestamper/api/ProcessorContext.java

@@ -2,6 +2,13 @@
 
 import org.docx4j.wml.R;
 
-public record ProcessorContext(
-        Paragraph paragraph, R run, Comment comment, Placeholder placeholder
-) {}
+/**
+ * Represents the context in which a processor operates in a text document.
+ * Contains information about the paragraph, run, comment, and placeholder being processed.
+ *
+ * @param paragraph   The paragraph associated with this context.
+ * @param run         The run object representing a run of text.
+ * @param comment     The comment associated with this context.
+ * @param placeholder The placeholder being processed in this context.
+ */
+public record ProcessorContext(Paragraph paragraph, R run, Comment comment, Placeholder placeholder) {}

engine/src/main/java/pro/verron/officestamper/core/CommentCollectorWalker.java

@@ -1,25 +1,18 @@
 package pro.verron.officestamper.core;
 
-import org.docx4j.TextUtils;
 import org.docx4j.wml.CommentRangeEnd;
 import org.docx4j.wml.CommentRangeStart;
 import org.docx4j.wml.Comments;
 import org.docx4j.wml.R;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 import pro.verron.officestamper.api.Comment;
 import pro.verron.officestamper.api.DocxPart;
 import pro.verron.officestamper.api.OfficeStamperException;
 
 import java.math.BigInteger;
 import java.util.*;
 
-import static java.util.stream.Collectors.joining;
-import static java.util.stream.Collectors.toSet;
-
 class CommentCollectorWalker
         extends BaseDocumentWalker {
-    private static final Logger logger = LoggerFactory.getLogger(CommentCollectorWalker.class);
     private final DocxPart document;
     private final Map<BigInteger, Comment> allComments;
     private final Queue<Comment> stack;
@@ -51,56 +44,9 @@ static Map<BigInteger, Comment> collectComments(DocxPart docxPart) {
                    .filter(comment -> allComments.containsKey(comment.getId()))
                    .forEach(comment -> allComments.get(comment.getId())
                                                   .setComment(comment));
-        return cleanMalformedComments(rootComments);
-    }
-
-    private static Map<BigInteger, Comment> cleanMalformedComments(Map<BigInteger, Comment> rootComments) {
-        Map<BigInteger, Comment> filteredCommentEntries = new HashMap<>();
-
-        rootComments.forEach((key, comment) -> {
-            if (isCommentMalformed(comment)) {
-                var commentContent = getCommentContent(comment);
-                logger.error("Skipping malformed comment, missing range start and/or range end : {}", commentContent);
-            }
-            else {
-                filteredCommentEntries.put(key, comment);
-                comment.setChildren(cleanMalformedComments(comment.getChildren()));
-            }
-        });
-        return filteredCommentEntries;
-    }
-
-    private static Set<Comment> cleanMalformedComments(Set<Comment> children) {
-        return children
-                .stream()
-                .filter(comment -> {
-                    if (isCommentMalformed(comment)) {
-                        var commentContent = getCommentContent(comment);
-                        logger.error("Skipping malformed comment, missing range start and/or range end : {}",
-                                commentContent);
-                        return false;
-                    }
-                    comment.setChildren(cleanMalformedComments(comment.getChildren()));
-                    return true;
-                })
-                .collect(toSet());
+        return new HashMap<>(rootComments);
     }
 
-    private static boolean isCommentMalformed(Comment comment) {
-        return comment.getCommentRangeStart() == null
-               || comment.getCommentRangeEnd() == null
-               || comment.getComment() == null;
-    }
-
-    private static String getCommentContent(Comment comment) {
-        return comment.getComment() == null
-                ? "<no content>"
-                : comment.getComment()
-                         .getContent()
-                         .stream()
-                         .map(TextUtils::getText)
-                         .collect(joining(""));
-    }
 
     @Override
     protected void onCommentRangeStart(CommentRangeStart commentRangeStart) {

engine/src/main/java/pro/verron/officestamper/core/CommentProcessorRegistry.java

@@ -11,7 +11,6 @@
 
 import java.math.BigInteger;
 import java.util.ArrayList;
-import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 
@@ -63,7 +62,7 @@ public <T> void runProcessors(T expressionContext) {
         source.streamRun()
               .forEach(run -> {
                   var comments = collectComments(source);
-                  var runParent = StandardParagraph.from((P) run.getParent());
+                  var runParent = StandardParagraph.from(source, (P) run.getParent());
                   var optional = runProcessorsOnRunComment(comments, expressionContext, run, runParent);
                   commentProcessors.commitChanges(source);
                   optional.ifPresent(proceedComments::add);
@@ -73,9 +72,12 @@ public <T> void runProcessors(T expressionContext) {
         source.streamParagraphs()
               .forEach(p -> {
                   var comments = collectComments(source);
-                  var optional = runProcessorsOnParagraphComment(comments, expressionContext, p, p.paragraphContent());
-                  commentProcessors.commitChanges(source);
-                  optional.ifPresent(proceedComments::add);
+                  var paragraphComment = p.getComment();
+                  paragraphComment.ifPresent((pc -> {
+                      var optional = runProcessorsOnParagraphComment(comments, expressionContext, p, pc.getId());
+                      commentProcessors.commitChanges(source);
+                      optional.ifPresent(proceedComments::add);
+                  }));
               });
 
         source.streamParagraphs()
@@ -112,18 +114,18 @@ private <T> Optional<Comment> runProcessorsOnParagraphComment(
             Map<BigInteger, Comment> comments,
             T expressionContext,
             Paragraph paragraph,
-            List<Object> paragraphContent
+            BigInteger paragraphCommentId
     ) {
-        return CommentUtil.getCommentFor(paragraphContent, source.document())
-                          .flatMap(c -> Optional.ofNullable(comments.get(c.getId())))
-                          .flatMap(c -> {
-                              var context = new ProcessorContext(paragraph, null, c, c.asPlaceholder());
-                              commentProcessors.setContext(context);
-                              var comment = runCommentProcessors(expressionContext, c);
-                              comments.remove(c.getComment()
-                                               .getId());
-                              return comment;
-                          });
+        if (!comments.containsKey(paragraphCommentId)) return Optional.empty();
+
+        var c = comments.get(paragraphCommentId);
+        var cPlaceholder = c.asPlaceholder();
+        var cComment = c.getComment();
+        var context = new ProcessorContext(paragraph, null, c, cPlaceholder);
+        commentProcessors.setContext(context);
+        var comment = runCommentProcessors(expressionContext, c);
+        comments.remove(cComment.getId());
+        return comment;
     }
 
     /**
@@ -135,10 +137,9 @@ private <T> Optional<Comment> runProcessorsOnParagraphComment(
      * @param <T>       type of the context root object
      */
     private <T> void runProcessorsOnInlineContent(T context, Paragraph paragraph) {
-        var processorContexts = findProcessors(paragraph.asString())
-                .stream()
-                .map(p -> newProcessorContext(paragraph, p))
-                .toList();
+        var processorContexts = findProcessors(paragraph.asString()).stream()
+                                                                    .map(paragraph::processorContext)
+                                                                    .toList();
         for (var processorContext : processorContexts) {
             commentProcessors.setContext(processorContext);
             var placeholder = processorContext.placeholder();
@@ -160,7 +161,7 @@ private <T> Optional<Comment> runCommentProcessors(T context, Comment comment) {
         try {
             expressionResolver.setContext(context);
             expressionResolver.resolve(placeholder);
-            logger.debug("Comment '{}' successfully processed by a comment processor.", placeholder.expression());
+            logger.debug("Comment '{}' successfully processed by a comment processor.", placeholder);
             return Optional.of(comment);
         } catch (SpelEvaluationException | SpelParseException e) {
             var message = "Comment '%s' failed to process.".formatted(placeholder.expression());
@@ -169,9 +170,4 @@ private <T> Optional<Comment> runCommentProcessors(T context, Comment comment) {
         }
     }
 
-    private ProcessorContext newProcessorContext(Paragraph paragraph, Placeholder placeholder) {
-        var firstRun = paragraph.firstRun();
-        var fakedComment = paragraph.fakeComment(source, placeholder);
-        return new ProcessorContext(paragraph, firstRun, fakedComment, placeholder);
-    }
 }

engine/src/main/java/pro/verron/officestamper/core/CommentUtil.java

@@ -73,7 +73,8 @@ else if (possibleComment != null && foundChild && unwrap(contentElement) instanc
             }
             // else restart
             else {
-                possibleComment = null;
+                possibleComment = null;// TODO There is  bug here when looking for a commented run and the run has
+                // ProofErr issues
                 foundChild = false;
             }
         }

engine/src/main/java/pro/verron/officestamper/core/DocxImageExtractor.java

@@ -58,7 +58,7 @@ private static Pic getPic(R run) {
 	}
 
 	private String getImageRelPartName(String imageRelId) {
-		// TODO_LATER: find a better way to find image rel part name in source part store
+		// TODO: find a better way to find image rel part name in source part store
 		return wordprocessingMLPackage
 				.getMainDocumentPart()
 				.getRelationshipsPart()