Paragraph.java

1 
package pro.verron.officestamper.api;
2
3 
import org.docx4j.wml.Comments;
4 
import org.docx4j.wml.P;
5 
import org.docx4j.wml.R;
6
7 
import java.util.Collection;
8 
import java.util.List;
9 
import java.util.Optional;
10 
import java.util.function.Consumer;
11
12 
/**
13 
 * The Paragraph interface represents a paragraph in a text document.
14 
 * It provides methods for replacing a placeholder within the paragraph and retrieving the paragraph as a string.
15 
 */
16 
public interface Paragraph {
17
18 
    /**
19 
     * Creates a processor context for the given placeholder within this paragraph.
20 
     *
21 
     * @param placeholder The placeholder to create a context for.
22 
     * @return The processor context for the specified placeholder.
23 
     */
24 
    ProcessorContext processorContext(Placeholder placeholder);
25
26 
    /**
27 
     * Replaces specified contiguous elements within the paragraph with new elements.
28 
     *
29 
     * @param toRemove The list of elements to be removed from the paragraph.
30 
     * @param toAdd The list of elements to be added to the paragraph.
31 
     */
32 
    void replace(List<P> toRemove, List<P> toAdd);
33
34 
    /**
35 
     * Removes the paragraph from the document.
36 
     * This method is intended to be used when a paragraph needs to be deleted.
37 
     */
38 
    void remove();
39
40 
    /**
41 
     * Retrieves the paragraph associated with this object.
42 
     * TODO replace with API not exposing the docx4j API directly
43 
     *
44 
     * @return the paragraph object
45 
     *
46 
     * @deprecated As of version 2.6, due to its direct exposure of the docx4j API. It is scheduled for removal in
47 
     * the future.
48 
     */
49 
    @Deprecated(since = "2.6", forRemoval = true)
50 
    P getP(); // TODO replace with API not exposing the docx4j API directly
51
52 
    /**
53 
     * Replaces all occurrences of a placeholder with a specified replacement value within a paragraph.
54 
     *
55 
     * @param placeholder The placeholder to be replaced.
56 
     * @param replacement The replacement value for the placeholder.
57 
     *
58 
     * @deprecated was used by the core to deal with multiline paragraphs, users should fallback to
59 
     * {@link #replace(Placeholder, Object)} only
60 
     */
61 
    @Deprecated(since = "2.4", forRemoval = true) default void replaceAll(Placeholder placeholder, R replacement) {
62 1 1. replaceAll : negated conditional → NO_COVERAGE
 
        while (contains(placeholder.expression())) {
63 1 1. replaceAll : removed call to pro/verron/officestamper/api/Paragraph::replace → NO_COVERAGE
 
            replace(placeholder, replacement);
64 
        }
65 
    }
66
67 
    /**
68 
     * Returns true if the given expression is found within the paragraph, otherwise returns false.
69 
     *
70 
     * @param expression The string to search for within the paragraph.
71 
     *
72 
     * @return true if the given expression is found within the paragraph, otherwise false.
73 
     *
74 
     * @deprecated was used by the core to deal with multiline paragraphs
75 
     */
76 
    @Deprecated(since = "2.4", forRemoval = true) default boolean contains(String expression) {
77 2 1. contains : replaced boolean return with false for pro/verron/officestamper/api/Paragraph::contains → NO_COVERAGE
2. contains : replaced boolean return with true for pro/verron/officestamper/api/Paragraph::contains → NO_COVERAGE
 
        return asString().contains(expression);
78 
    }
79
80 
    /**
81 
     * Replaces a placeholder in the given paragraph with the specified replacement.
82 
     *
83 
     * @param placeholder The placeholder to be replaced.
84 
     * @param replacement The replacement for the placeholder.
85 
     */
86 
    void replace(Placeholder placeholder, Object replacement);
87
88 
    /**
89 
     * Returns the paragraph as a string.
90 
     *
91 
     * @return the paragraph as a string
92 
     */
93 
    String asString();
94
95 
    /**
96 
     * Applies the specified consumer function to the paragraph content.
97 
     *
98 
     * @param pConsumer The consumer function to apply to the paragraph content.
99 
     */
100 
    void apply(Consumer<P> pConsumer);
101
102 
    /**
103 
     * Retrieves the parent of the current paragraph that matches the specified class type.
104 
     *
105 
     * @param aClass The class type to match for the parent element.
106 
     * @param <T> The type of the parent element to be returned.
107 
     * @return An {@code Optional} containing the matched parent element if found, otherwise an empty {@code Optional}.
108 
     */
109 
    <T> Optional<T> parent(Class<T> aClass);
110
111 
    /**
112 
     * Retrieves a collection of comments associated with the paragraph.
113 
     *
114 
     * @return a collection of {@code Comments.Comment} objects related to the paragraph
115 
     */
116 
    Collection<Comments.Comment> getComment();
117 
}

Mutations

62

1.1
Location : replaceAll
Killed by : none negated conditional → NO_COVERAGE

63

1.1
Location : replaceAll
Killed by : none removed call to pro/verron/officestamper/api/Paragraph::replace → NO_COVERAGE

77

1.1
Location : contains
Killed by : none replaced boolean return with false for pro/verron/officestamper/api/Paragraph::contains → NO_COVERAGE

2.2
Location : contains
Killed by : none replaced boolean return with true for pro/verron/officestamper/api/Paragraph::contains → NO_COVERAGE

Active mutators

Tests examined


Report generated by PIT 1.20.0