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

Mutations

61

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

62

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

76

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.17.1