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

Mutations

49

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

50

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

62

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