1 /*
2 * Copyright (c) 2020 bahlef.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v2.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v20.html
7 * Contributors:
8 * bahlef - initial API and implementation and/or initial documentation
9 */
10 package de.funfried.netbeans.plugins.external.formatter;
11
12 import java.util.List;
13 import java.util.SortedSet;
14
15 import javax.swing.text.BadLocationException;
16 import javax.swing.text.Document;
17 import javax.swing.text.StyledDocument;
18
19 import org.apache.commons.lang3.tuple.Pair;
20 import org.netbeans.api.annotations.common.CheckForNull;
21 import org.netbeans.api.annotations.common.NonNull;
22 import org.netbeans.api.project.Project;
23
24 import de.funfried.netbeans.plugins.external.formatter.exceptions.FormattingFailedException;
25 import de.funfried.netbeans.plugins.external.formatter.ui.options.FormatterOptionsPanel;
26
27 /**
28 * Service interface for external formatter implementations.
29 *
30 * @author bahlef
31 */
32 public interface FormatterService {
33 /**
34 * Returns {@code true} if and only if this implementation would be able to
35 * format the given {@link Document}, otherwise {@code false}.
36 *
37 * @param document the {@link Document} to check
38 *
39 * @return {@code true} if and only if this implementation would be able to
40 * format the given {@link Document}, otherwise {@code false}
41 */
42 default boolean canHandle(Document document) {
43 if (document == null) {
44 return false;
45 }
46
47 return MimeType.canHandle(getSupportedMimeTypes(), MimeType.getMimeTypeAsString(document));
48 }
49
50 /**
51 * Formats the given {@link StyledDocument} in regard to the given {@code changedElements}.
52 *
53 * @param document the {@link StyledDocument} which should be formatted
54 * @param changedElements a {@link SortedSet} containing ranges as {@link Pair} objects that should be formatted
55 *
56 * @return if {@code true} formatting was done, otherwise formatting was rejected and needs to be done by NetBeans internal formatter
57 *
58 * @throws BadLocationException if something goes wrong while applying the formatted code
59 * @throws FormattingFailedException if the given {@link StyledDocument} cannot be formatted by the given formatter
60 */
61 boolean format(StyledDocument document, SortedSet<Pair<Integer, Integer>> changedElements) throws BadLocationException, FormattingFailedException;
62
63 /**
64 * Returns the continuation indent size configured for the given {@link Document},
65 * or {@code null} if it should not affect the editor behavior.
66 *
67 * @param document the {@link Document} for which the continuation indent size
68 * is requested
69 *
70 * @return the continuation indent size configured for the given {@link Document},
71 * or {@code null} if it should not affect the editor behavior
72 */
73 @CheckForNull
74 Integer getContinuationIndentSize(Document document);
75
76 /**
77 * Retruns the display name of this formatter implementation.
78 *
79 * @return the display name of this formatter implementation
80 */
81 @NonNull
82 String getDisplayName();
83
84 /**
85 * Retruns the unique identifier of this formatter implementation.
86 *
87 * @return the unique identifier of this formatter implementation
88 */
89 @NonNull
90 String getId();
91
92 /**
93 * Returns the indent size configured for the given {@link Document}, or
94 * {@code null} if it should not affect the editor behavior.
95 *
96 * @param document the {@link Document} for which the indent size is requested
97 *
98 * @return the indent size configured for the given {@link Document}, or
99 * {@code null} if it should not affect the editor behavior
100 */
101 @CheckForNull
102 Integer getIndentSize(Document document);
103
104 /**
105 * Creates and returns the {@link FormatterOptionsPanel} for this formatter
106 * which will be displayed in the overall options dialog underneath this
107 * formatters selection.
108 *
109 * @param project the {@link Project} if the panel which is created is used
110 * to modify project specific settings, otherwise
111 * {@code null}
112 *
113 * @return the {@link FormatterOptionsPanel} for this formatter, or
114 * {@code null} if there are no options a user could make for
115 * this formatter
116 */
117 FormatterOptionsPanel createOptionsPanel(Project project);
118
119 /**
120 * Returns the right margin (position of the red line in the editor) configured
121 * for the given {@link Document}, or {@code null} if it should not affect the
122 * editor behavior.
123 *
124 * @param document the {@link Document} for which the right margin is requested
125 *
126 * @return the right margin (position of the red line in the editor) configured
127 * for the given {@link Document}, or {@code null} if it should not
128 * affect the editor behavior
129 */
130 @CheckForNull
131 Integer getRightMargin(Document document);
132
133 /**
134 * Returns the spaces per tab configured for the given {@link Document}, or
135 * {@code null} if it should not affect the editor behavior.
136 *
137 * @param document the {@link Document} for which the spaces per tab is
138 * requested
139 *
140 * @return the spaces per tab configured for the given {@link Document}, or
141 * {@code null} if it should not affect the editor behavior
142 */
143 @CheckForNull
144 Integer getSpacesPerTab(Document document);
145
146 /**
147 * Returns a {@link List} of supported {@link MimeType}s for this {@link FormatterService}.
148 *
149 * @return a {@link List} of supported {@link MimeType}s for this {@link FormatterService}
150 */
151 @NonNull
152 List<MimeType> getSupportedMimeTypes();
153
154 /**
155 * Returns the expand tab to spaces flag configured for the given
156 * {@link Document}, or {@code null} if it should not affect the editor behavior.
157 *
158 * @param document the {@link Document} for which the expand tab to spaces flag
159 * is requested
160 *
161 * @return the expand tab to spaces flag configured for the given
162 * {@link Document}, or {@code null} if it should not affect the editor
163 * behavior
164 */
165 @CheckForNull
166 Boolean isExpandTabToSpaces(Document document);
167
168 /**
169 * Organizes the imports of the given {@link StyledDocument}.
170 *
171 * @param document the {@link StyledDocument}
172 * @param afterFixImports {@code true} if this method was called after fixing imports,
173 * otherwise {@code false}
174 *
175 * @return {@code true} if the imports have been reorganized, if something went wrong
176 * it will return {@code false}, if it wasn't executed, e.g. because it is not
177 * activated through its configuration, it will return {@code null}
178 *
179 * @throws BadLocationException if something goes wrong while applying the reorganized imports code
180 */
181 @CheckForNull
182 Boolean organizeImports(StyledDocument document, boolean afterFixImports) throws BadLocationException;
183 }