pmd / pmd / 380

Committed 29 Jan 2026 03:55PM UTC coverage: 78.964%. Remained the same

Build # 380

Build Type

push

github

Committed by

adangel

Commit Message

[doc] ADR 3: Clarify javadoc tags (#6392)

Run Details

18537 of 24358 branches covered (76.1%)

Branch coverage included in aggregate %.

40391 of 50268 relevant lines covered (80.35%)

0.81 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

73.99

/pmd-core/src/main/java/net/sourceforge/pmd/lang/LanguageModuleBase.java

/*
 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
 */

package net.sourceforge.pmd.lang;

import static net.sourceforge.pmd.util.CollectionUtil.emptyList;
import static net.sourceforge.pmd.util.CollectionUtil.setOf;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.regex.Pattern;

import org.apache.commons.lang3.StringUtils;
import org.checkerframework.checker.nullness.qual.NonNull;
import org.checkerframework.checker.nullness.qual.Nullable;

import net.sourceforge.pmd.annotation.Experimental;
import net.sourceforge.pmd.lang.LanguageModuleBase.LanguageMetadata.LangVersionMetadata;
import net.sourceforge.pmd.util.AssertionUtil;
import net.sourceforge.pmd.util.StringUtil;

/**
 * Base class for language modules.
 *
 * @author Clément Fournier
 */
public abstract class LanguageModuleBase implements Language {

    private final LanguageMetadata meta;

    private final List<LanguageVersion> distinctVersions;
    private final Map<String, LanguageVersion> byName;
    private final LanguageVersion defaultVersion;
    private final Set<String> dependencies;
    private final @Nullable String baseLanguageId;


    /**
     * Construct a module instance using the given metadata. The metadata must
     * be properly constructed.
     *
     * @throws IllegalStateException If the metadata is invalid (eg missing extensions or name or no versions)
     */
    protected LanguageModuleBase(LanguageMetadata metadata) {
        this(metadata, null);
    }

    /**
     * @since 7.13.0
     * @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
     */
    @Experimental
    protected LanguageModuleBase(DialectLanguageMetadata metadata) {
        this(metadata.metadata, metadata.baseLanguageId);
    }

    private LanguageModuleBase(LanguageMetadata metadata, String baseLanguageId) {
        this.meta = metadata;
        metadata.validate();
        this.dependencies = Collections.unmodifiableSet(metadata.dependencies);
        this.baseLanguageId = baseLanguageId;

        List<LanguageVersion> versions = new ArrayList<>();
        Map<String, LanguageVersion> byName = new HashMap<>();
        LanguageVersion defaultVersion = null;

        if (metadata.versionMetadata.isEmpty()) {
            if (this instanceof PmdCapableLanguage) {
                // pmd languages need to have versions
                throw new IllegalStateException("No versions for '" + getId() + "'");
            } else {
                // for others, a version is declared implicitly
                metadata.versionMetadata.add(new LangVersionMetadata());
            }
        }

        int i = 0;
        for (LanguageMetadata.LangVersionMetadata versionId : metadata.versionMetadata) {
            String versionStr = versionId.name;
            LanguageVersion languageVersion = new LanguageVersion(this, versionStr, i++, versionId.aliases);

            versions.add(languageVersion);

            checkNotPresent(byName, versionStr);
            byName.put(versionStr, languageVersion);
            for (String alias : versionId.aliases) {
                checkNotPresent(byName, alias);
                byName.put(alias, languageVersion);
            }

            if (versionId.isDefault) {
                if (defaultVersion != null) {
                    throw new IllegalStateException(
                        "Default version already set to " + defaultVersion + ", cannot set it to " + languageVersion);
                }
                defaultVersion = languageVersion;
            }
        }

        this.byName = Collections.unmodifiableMap(byName);
        this.distinctVersions = Collections.unmodifiableList(versions);
        this.defaultVersion = Objects.requireNonNull(defaultVersion, "No default version for " + getId());
    }

    private static void checkNotPresent(Map<String, ?> map, String alias) {
        if (map.containsKey(alias)) {
            throw new IllegalArgumentException("Version key '" + alias + "' is duplicated");
        }
    }

    @Override
    public @Nullable String getBaseLanguageId() {
        return baseLanguageId;
    }

    @Override
    public List<LanguageVersion> getVersions() {
        return distinctVersions;
    }

    @Override
    public @NonNull LanguageVersion getDefaultVersion() {
        return defaultVersion;
    }

    @Override
    public LanguageVersion getVersion(String version) {
        return byName.get(version);
    }

    @Override
    public Set<String> getVersionNamesAndAliases() {
        return Collections.unmodifiableSet(byName.keySet());
    }

    @Override
    public Set<String> getDependencies() {
        return dependencies;
    }

    @Override
    public String getName() {
        return meta.name;
    }

    @Override
    public String getShortName() {
        return meta.getShortName();
    }

    @Override
    public String getId() {
        return meta.id;
    }

    @Override
    public @NonNull List<String> getExtensions() {
        return Collections.unmodifiableList(meta.extensions);
    }

    @Override
    public String toString() {
        return getId();
    }

    @Override
    public int compareTo(Language o) {
        return getName().compareTo(o.getName());
    }

    @Override
    public int hashCode() {
        return getId().hashCode();
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        LanguageModuleBase other = (LanguageModuleBase) obj;
        return Objects.equals(getId(), other.getId());
    }

    /**
     * Metadata about a language, basically a builder pattern for the
     * language instance.
     *
     * <p>Some of the metadata are mandatory:
     * <ul>
     * <li>The id ({@link #withId(String)})
     * <li>The display name ({@link #name(String)})
     * <li>The file extensions ({@link #extensions(String, String...)}
     * </ul>
     */
    public static final class LanguageMetadata {

        /** Language IDs should be conventional Java package names. */
        private static final Pattern VALID_LANG_ID = Pattern.compile("[a-z][_a-z0-9]*");
        private static final Pattern SPACE_PAT = Pattern.compile("\\s");

        private final Set<String> dependencies = new HashSet<>();
        private String name;
        private @Nullable String shortName;
        private final @NonNull String id;
        private List<String> extensions;
        private final List<LangVersionMetadata> versionMetadata = new ArrayList<>();

        private LanguageMetadata(@NonNull String id) {
            this.id = id;
            checkValidLangId(id);
        }

        void validate() {
            AssertionUtil.validateState(name != null, "Language " + id + " should have a name");
            AssertionUtil.validateState(
                extensions != null, "Language " + id + " has not registered any file extensions");
        }

        String getShortName() {
            return shortName == null ? name : shortName;
        }

        /**
         * Factory method to create an ID.
         *
         * @param id The language id. Must be usable as a Java package name segment,
         *           ie be lowercase, alphanumeric, starting with a letter.
         *
         * @return A builder for language metadata
         *
         * @throws IllegalArgumentException If the parameter is not a valid ID
         * @throws NullPointerException     If the parameter is null
         */
        public static LanguageMetadata withId(@NonNull String id) {
            return new LanguageMetadata(id);
        }

        /**
         * Record the {@linkplain Language#getName() display name} of
         * the language. This also serves as the {@linkplain Language#getShortName() short name}
         * if {@link #shortName(String)} is not called.
         *
         * @param name Display name of the language
         *
         * @throws NullPointerException     If the parameter is null
         * @throws IllegalArgumentException If the parameter is not a valid language name
         */
        public LanguageMetadata name(@NonNull String name) {
            AssertionUtil.requireParamNotNull("name", name);
            if (StringUtils.isBlank(name)) {
                throw new IllegalArgumentException("Not a valid language name: " + StringUtil.inSingleQuotes(name));
            }
            this.name = name.trim();
            return this;
        }

        /**
         * Record the {@linkplain Language#getShortName() short name} of the language.
         *
         * @param shortName Short name of the language
         *
         * @throws NullPointerException     If the parameter is null
         * @throws IllegalArgumentException If the parameter is not a valid language name
         */

        public LanguageMetadata shortName(@NonNull String shortName) {
            AssertionUtil.requireParamNotNull("short name", shortName);
            if (StringUtils.isBlank(name)) {
                throw new IllegalArgumentException("Not a valid language name: " + StringUtil.inSingleQuotes(name));
            }
            this.shortName = shortName.trim();
            return this;
        }

        /**
         * Record the {@linkplain Language#getExtensions() extensions}
         * assigned to the language. Extensions should not start with a period
         * {@code .}.
         *
         * @param extensionWithoutPeriod First extensions
         * @param others                 Other extensions (optional)
         *
         * @throws NullPointerException If any extension is null
         */
        public LanguageMetadata extensions(String extensionWithoutPeriod, String... others) {
            this.extensions = new ArrayList<>(setOf(extensionWithoutPeriod, others));
            AssertionUtil.requireContainsNoNullValue("extensions", this.extensions);
            return this;
        }

        /**
         * Record the {@linkplain Language#getExtensions() extensions}
         * assigned to the language. Extensions should not start with a period
         * {@code .}. At least one extension must be provided.
         *
         * @param extensions the extensions
         *
         * @throws NullPointerException     If any extension is null
         * @throws IllegalArgumentException If no extensions are provided
         */
        public LanguageMetadata extensions(Collection<String> extensions) {
            this.extensions = new ArrayList<>(new HashSet<>(extensions));
            AssertionUtil.requireContainsNoNullValue("extensions", this.extensions);
            if (this.extensions.isEmpty()) {
                throw new IllegalArgumentException("At least one extension is required.");
            }
            return this;
        }

        /**
         * Add a new version by its name.
         *
         * @param name    Version name. Must contain no spaces.
         * @param aliases Additional names that are mapped to this version. Must contain no spaces.
         *
         * @throws NullPointerException     If any parameter is null
         * @throws IllegalArgumentException If the name or aliases are empty or contain spaces
         */

        public LanguageMetadata addVersion(String name, String... aliases) {
            versionMetadata.add(new LangVersionMetadata(name, Arrays.asList(aliases), false));
            return this;
        }

        /**
         * Add a new version by its name and make it the default version.
         *
         * @param name    Version name. Must contain no spaces.
         * @param aliases Additional names that are mapped to this version. Must contain no spaces.
         *
         * @throws NullPointerException     If any parameter is null
         * @throws IllegalArgumentException If the name or aliases are empty or contain spaces
         */
        public LanguageMetadata addDefaultVersion(String name, String... aliases) {
            versionMetadata.add(new LangVersionMetadata(name, Arrays.asList(aliases), true));
            return this;
        }


        /**
         * Add all the versions of the given language, including the
         * default version.
         *
         * @param language Other language
         *
         * @throws NullPointerException     If any parameter is null
         * @throws IllegalArgumentException If the name or aliases are empty or contain spaces
         */
        public LanguageMetadata addAllVersionsOf(Language language) {
            for (LanguageVersion version : language.getVersions()) {
                versionMetadata.add(new LangVersionMetadata(version.getVersion(),
                                                            version.getAliases(),
                                                            version.equals(language.getDefaultVersion())));
            }
            return this;
        }

        /**
         * Defines the language as a dialect of another language.
         *
         * @param baseLanguageId The id of the base language this is a dialect of.
         * @return A new dialect language metadata model.
         * @since 7.13.0
         * @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
         */
        @Experimental
        public DialectLanguageMetadata asDialectOf(String baseLanguageId) {
            checkValidLangId(baseLanguageId);
            dependsOnLanguage(baseLanguageId); // a dialect automatically depends on it's base language at runtime
            return new DialectLanguageMetadata(this, baseLanguageId);
        }

        private static void checkValidLangId(String id) {
            if (!VALID_LANG_ID.matcher(id).matches()) {
                throw new IllegalArgumentException(
                    "ID '" + id + "' is not a valid language ID (should match " + VALID_LANG_ID + ").");
            }
        }

        /**
         * Record that this language depends on another language, identified
         * by its id. This means any {@link LanguageProcessorRegistry} that
         * contains a processor for this language is asserted upon construction
         * to also contain a processor for the language depended on.
         *
         * @param id ID of the language to depend on.
         *
         * @throws NullPointerException     If any parameter is null
         * @throws IllegalArgumentException If the name is not a valid language Id
         */

        public LanguageMetadata dependsOnLanguage(String id) {
            checkValidLangId(id);
            dependencies.add(id);
            return this;
        }

        static final class LangVersionMetadata {

            final String name;
            final List<String> aliases;
            final boolean isDefault;

            private LangVersionMetadata() {
                this.name = "";
                this.aliases = emptyList();
                this.isDefault = true;
            }

            private LangVersionMetadata(String name, List<String> aliases, boolean isDefault) {
                checkVersionName(name);
                for (String alias : aliases) {
                    checkVersionName(alias);
                }

                this.name = name;
                this.aliases = aliases;
                this.isDefault = isDefault;
            }

            private static void checkVersionName(String name) {
                if (StringUtils.isBlank(name) || SPACE_PAT.matcher(name).find()) {
                    throw new IllegalArgumentException("Invalid version name: " + StringUtil.inSingleQuotes(name));
                }
            }
        }
    }

    /**
     * Expresses the language as a dialect of another language.
     * @since 7.13.0
     * @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
     */
    @Experimental
    public static final class DialectLanguageMetadata {
        private final @NonNull LanguageMetadata metadata;
        private final @NonNull String baseLanguageId;

        private DialectLanguageMetadata(LanguageMetadata metadata, String baseLanguageId) {
            this.metadata = metadata;
            this.baseLanguageId = baseLanguageId;
        }
    }
}

1	/*
2	* BSD-style license; for more info see http://pmd.sourceforge.net/license.html
3	*/
4
5	package net.sourceforge.pmd.lang;
6
7	import static net.sourceforge.pmd.util.CollectionUtil.emptyList;
8	import static net.sourceforge.pmd.util.CollectionUtil.setOf;
9
10	import java.util.ArrayList;
11	import java.util.Arrays;
12	import java.util.Collection;
13	import java.util.Collections;
14	import java.util.HashMap;
15	import java.util.HashSet;
16	import java.util.List;
17	import java.util.Map;
18	import java.util.Objects;
19	import java.util.Set;
20	import java.util.regex.Pattern;
21
22	import org.apache.commons.lang3.StringUtils;
23	import org.checkerframework.checker.nullness.qual.NonNull;
24	import org.checkerframework.checker.nullness.qual.Nullable;
25
26	import net.sourceforge.pmd.annotation.Experimental;
27	import net.sourceforge.pmd.lang.LanguageModuleBase.LanguageMetadata.LangVersionMetadata;
28	import net.sourceforge.pmd.util.AssertionUtil;
29	import net.sourceforge.pmd.util.StringUtil;
30
31	/**
32	* Base class for language modules.
33	*
34	* @author Clément Fournier
35	*/
36	public abstract class LanguageModuleBase implements Language {
37
38	private final LanguageMetadata meta;
39
40	private final List<LanguageVersion> distinctVersions;
41	private final Map<String, LanguageVersion> byName;
42	private final LanguageVersion defaultVersion;
43	private final Set<String> dependencies;
44	private final @Nullable String baseLanguageId;
45
46
47	/**
48	* Construct a module instance using the given metadata. The metadata must
49	* be properly constructed.
50	*
51	* @throws IllegalStateException If the metadata is invalid (eg missing extensions or name or no versions)
52	*/
53	protected LanguageModuleBase(LanguageMetadata metadata) {
54	this(metadata, null);	1✔
55	}	1✔
56
57	/**
58	* @since 7.13.0
59	* @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
60	*/
61	@Experimental
62	protected LanguageModuleBase(DialectLanguageMetadata metadata) {
63	this(metadata.metadata, metadata.baseLanguageId);	1✔
64	}	1✔
65
66	private LanguageModuleBase(LanguageMetadata metadata, String baseLanguageId) {	1✔
67	this.meta = metadata;	1✔
68	metadata.validate();	1✔
69	this.dependencies = Collections.unmodifiableSet(metadata.dependencies);	1✔
70	this.baseLanguageId = baseLanguageId;	1✔
71
72	List<LanguageVersion> versions = new ArrayList<>();	1✔
73	Map<String, LanguageVersion> byName = new HashMap<>();	1✔
74	LanguageVersion defaultVersion = null;	1✔
75
76	if (metadata.versionMetadata.isEmpty()) {	1✔
77	if (this instanceof PmdCapableLanguage) {	1!
78	// pmd languages need to have versions
79	throw new IllegalStateException("No versions for '" + getId() + "'");	1✔
80	} else {
81	// for others, a version is declared implicitly
82	metadata.versionMetadata.add(new LangVersionMetadata());	×
83	}
84	}
85
86	int i = 0;	1✔
87	for (LanguageMetadata.LangVersionMetadata versionId : metadata.versionMetadata) {	1✔
88	String versionStr = versionId.name;	1✔
89	LanguageVersion languageVersion = new LanguageVersion(this, versionStr, i++, versionId.aliases);	1✔
90
91	versions.add(languageVersion);	1✔
92
93	checkNotPresent(byName, versionStr);	1✔
94	byName.put(versionStr, languageVersion);	1✔
95	for (String alias : versionId.aliases) {	1✔
96	checkNotPresent(byName, alias);	1✔
97	byName.put(alias, languageVersion);	1✔
98	}	1✔
99
100	if (versionId.isDefault) {	1✔
101	if (defaultVersion != null) {	1!
102	throw new IllegalStateException(	×
103	"Default version already set to " + defaultVersion + ", cannot set it to " + languageVersion);
104	}
105	defaultVersion = languageVersion;	1✔
106	}
107	}	1✔
108
109	this.byName = Collections.unmodifiableMap(byName);	1✔
110	this.distinctVersions = Collections.unmodifiableList(versions);	1✔
111	this.defaultVersion = Objects.requireNonNull(defaultVersion, "No default version for " + getId());	1✔
112	}	1✔
113
114	private static void checkNotPresent(Map<String, ?> map, String alias) {
115	if (map.containsKey(alias)) {	1!
116	throw new IllegalArgumentException("Version key '" + alias + "' is duplicated");	×
117	}
118	}	1✔
119
120	@Override
121	public @Nullable String getBaseLanguageId() {
122	return baseLanguageId;	1✔
123	}
124
125	@Override
126	public List<LanguageVersion> getVersions() {
127	return distinctVersions;	1✔
128	}
129
130	@Override
131	public @NonNull LanguageVersion getDefaultVersion() {
132	return defaultVersion;	1✔
133	}
134
135	@Override
136	public LanguageVersion getVersion(String version) {
137	return byName.get(version);	1✔
138	}
139
140	@Override
141	public Set<String> getVersionNamesAndAliases() {
142	return Collections.unmodifiableSet(byName.keySet());	×
143	}
144
145	@Override
146	public Set<String> getDependencies() {
147	return dependencies;	1✔
148	}
149
150	@Override
151	public String getName() {
152	return meta.name;	1✔
153	}
154
155	@Override
156	public String getShortName() {
157	return meta.getShortName();	×
158	}
159
160	@Override
161	public String getId() {
162	return meta.id;	1✔
163	}
164
165	@Override
166	public @NonNull List<String> getExtensions() {
167	return Collections.unmodifiableList(meta.extensions);	1✔
168	}
169
170	@Override
171	public String toString() {
172	return getId();	1✔
173	}
174
175	@Override
176	public int compareTo(Language o) {
177	return getName().compareTo(o.getName());	1✔
178	}
179
180	@Override
181	public int hashCode() {
182	return getId().hashCode();	1✔
183	}
184
185	@Override
186	public boolean equals(Object obj) {
187	if (this == obj) {	1✔
188	return true;	1✔
189	}
190	if (obj == null) {	1!
191	return false;	×
192	}
193	if (getClass() != obj.getClass()) {	1!
194	return false;	1✔
195	}
196	LanguageModuleBase other = (LanguageModuleBase) obj;	×
197	return Objects.equals(getId(), other.getId());	×
198	}
199
200	/**
201	* Metadata about a language, basically a builder pattern for the
202	* language instance.
203	*
204	* <p>Some of the metadata are mandatory:
205	* <ul>
206	* <li>The id ({@link #withId(String)})
207	* <li>The display name ({@link #name(String)})
208	* <li>The file extensions ({@link #extensions(String, String...)}
209	* </ul>
210	*/
211	public static final class LanguageMetadata {
212
213	/** Language IDs should be conventional Java package names. */
214	private static final Pattern VALID_LANG_ID = Pattern.compile("[a-z][_a-z0-9]*");	1✔
215	private static final Pattern SPACE_PAT = Pattern.compile("\\s");	1✔
216
217	private final Set<String> dependencies = new HashSet<>();	1✔
218	private String name;
219	private @Nullable String shortName;
220	private final @NonNull String id;
221	private List<String> extensions;
222	private final List<LangVersionMetadata> versionMetadata = new ArrayList<>();	1✔
223
224	private LanguageMetadata(@NonNull String id) {	1✔
225	this.id = id;	1✔
226	checkValidLangId(id);	1✔
227	}	1✔
228
229	void validate() {
230	AssertionUtil.validateState(name != null, "Language " + id + " should have a name");	1!
231	AssertionUtil.validateState(	1✔
232	extensions != null, "Language " + id + " has not registered any file extensions");
233	}	1✔
234
235	String getShortName() {
236	return shortName == null ? name : shortName;	1!
237	}
238
239	/**
240	* Factory method to create an ID.
241	*
242	* @param id The language id. Must be usable as a Java package name segment,
243	* ie be lowercase, alphanumeric, starting with a letter.
244	*
245	* @return A builder for language metadata
246	*
247	* @throws IllegalArgumentException If the parameter is not a valid ID
248	* @throws NullPointerException If the parameter is null
249	*/
250	public static LanguageMetadata withId(@NonNull String id) {
251	return new LanguageMetadata(id);	1✔
252	}
253
254	/**
255	* Record the {@linkplain Language#getName() display name} of
256	* the language. This also serves as the {@linkplain Language#getShortName() short name}
257	* if {@link #shortName(String)} is not called.
258	*
259	* @param name Display name of the language
260	*
261	* @throws NullPointerException If the parameter is null
262	* @throws IllegalArgumentException If the parameter is not a valid language name
263	*/
264	public LanguageMetadata name(@NonNull String name) {
265	AssertionUtil.requireParamNotNull("name", name);	1✔
266	if (StringUtils.isBlank(name)) {	1!
267	throw new IllegalArgumentException("Not a valid language name: " + StringUtil.inSingleQuotes(name));	×
268	}
269	this.name = name.trim();	1✔
270	return this;	1✔
271	}
272
273	/**
274	* Record the {@linkplain Language#getShortName() short name} of the language.
275	*
276	* @param shortName Short name of the language
277	*
278	* @throws NullPointerException If the parameter is null
279	* @throws IllegalArgumentException If the parameter is not a valid language name
280	*/
281
282	public LanguageMetadata shortName(@NonNull String shortName) {
283	AssertionUtil.requireParamNotNull("short name", shortName);	×
284	if (StringUtils.isBlank(name)) {	×
285	throw new IllegalArgumentException("Not a valid language name: " + StringUtil.inSingleQuotes(name));	×
286	}
287	this.shortName = shortName.trim();	×
288	return this;	×
289	}
290
291	/**
292	* Record the {@linkplain Language#getExtensions() extensions}
293	* assigned to the language. Extensions should not start with a period
294	* {@code .}.
295	*
296	* @param extensionWithoutPeriod First extensions
297	* @param others Other extensions (optional)
298	*
299	* @throws NullPointerException If any extension is null
300	*/
301	public LanguageMetadata extensions(String extensionWithoutPeriod, String... others) {
302	this.extensions = new ArrayList<>(setOf(extensionWithoutPeriod, others));	1✔
303	AssertionUtil.requireContainsNoNullValue("extensions", this.extensions);	1✔
304	return this;	1✔
305	}
306
307	/**
308	* Record the {@linkplain Language#getExtensions() extensions}
309	* assigned to the language. Extensions should not start with a period
310	* {@code .}. At least one extension must be provided.
311	*
312	* @param extensions the extensions
313	*
314	* @throws NullPointerException If any extension is null
315	* @throws IllegalArgumentException If no extensions are provided
316	*/
317	public LanguageMetadata extensions(Collection<String> extensions) {
318	this.extensions = new ArrayList<>(new HashSet<>(extensions));	×
319	AssertionUtil.requireContainsNoNullValue("extensions", this.extensions);	×
320	if (this.extensions.isEmpty()) {	×
321	throw new IllegalArgumentException("At least one extension is required.");	×
322	}
323	return this;	×
324	}
325
326	/**
327	* Add a new version by its name.
328	*
329	* @param name Version name. Must contain no spaces.
330	* @param aliases Additional names that are mapped to this version. Must contain no spaces.
331	*
332	* @throws NullPointerException If any parameter is null
333	* @throws IllegalArgumentException If the name or aliases are empty or contain spaces
334	*/
335
336	public LanguageMetadata addVersion(String name, String... aliases) {
337	versionMetadata.add(new LangVersionMetadata(name, Arrays.asList(aliases), false));	1✔
338	return this;	1✔
339	}
340
341	/**
342	* Add a new version by its name and make it the default version.
343	*
344	* @param name Version name. Must contain no spaces.
345	* @param aliases Additional names that are mapped to this version. Must contain no spaces.
346	*
347	* @throws NullPointerException If any parameter is null
348	* @throws IllegalArgumentException If the name or aliases are empty or contain spaces
349	*/
350	public LanguageMetadata addDefaultVersion(String name, String... aliases) {
351	versionMetadata.add(new LangVersionMetadata(name, Arrays.asList(aliases), true));	1✔
352	return this;	1✔
353	}
354
355
356	/**
357	* Add all the versions of the given language, including the
358	* default version.
359	*
360	* @param language Other language
361	*
362	* @throws NullPointerException If any parameter is null
363	* @throws IllegalArgumentException If the name or aliases are empty or contain spaces
364	*/
365	public LanguageMetadata addAllVersionsOf(Language language) {
366	for (LanguageVersion version : language.getVersions()) {	×
367	versionMetadata.add(new LangVersionMetadata(version.getVersion(),	×
368	version.getAliases(),	×
369	version.equals(language.getDefaultVersion())));	×
370	}	×
371	return this;	×
372	}
373
374	/**
375	* Defines the language as a dialect of another language.
376	*
377	* @param baseLanguageId The id of the base language this is a dialect of.
378	* @return A new dialect language metadata model.
379	* @since 7.13.0
380	* @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
381	*/
382	@Experimental
383	public DialectLanguageMetadata asDialectOf(String baseLanguageId) {
384	checkValidLangId(baseLanguageId);	1✔
385	dependsOnLanguage(baseLanguageId); // a dialect automatically depends on it's base language at runtime	1✔
386	return new DialectLanguageMetadata(this, baseLanguageId);	1✔
387	}
388
389	private static void checkValidLangId(String id) {
390	if (!VALID_LANG_ID.matcher(id).matches()) {	1✔
391	throw new IllegalArgumentException(	1✔
392	"ID '" + id + "' is not a valid language ID (should match " + VALID_LANG_ID + ").");
393	}
394	}	1✔
395
396	/**
397	* Record that this language depends on another language, identified
398	* by its id. This means any {@link LanguageProcessorRegistry} that
399	* contains a processor for this language is asserted upon construction
400	* to also contain a processor for the language depended on.
401	*
402	* @param id ID of the language to depend on.
403	*
404	* @throws NullPointerException If any parameter is null
405	* @throws IllegalArgumentException If the name is not a valid language Id
406	*/
407
408	public LanguageMetadata dependsOnLanguage(String id) {
409	checkValidLangId(id);	1✔
410	dependencies.add(id);	1✔
411	return this;	1✔
412	}
413
414	static final class LangVersionMetadata {
415
416	final String name;
417	final List<String> aliases;
418	final boolean isDefault;
419
420	private LangVersionMetadata() {	×
421	this.name = "";	×
422	this.aliases = emptyList();	×
423	this.isDefault = true;	×
424	}	×
425
426	private LangVersionMetadata(String name, List<String> aliases, boolean isDefault) {	1✔
427	checkVersionName(name);	1✔
428	for (String alias : aliases) {	1✔
429	checkVersionName(alias);	1✔
430	}	1✔
431
432	this.name = name;	1✔
433	this.aliases = aliases;	1✔
434	this.isDefault = isDefault;	1✔
435	}	1✔
436
437	private static void checkVersionName(String name) {
438	if (StringUtils.isBlank(name) \|\| SPACE_PAT.matcher(name).find()) {	1!
439	throw new IllegalArgumentException("Invalid version name: " + StringUtil.inSingleQuotes(name));	1✔
440	}
441	}	1✔
442	}
443	}
444
445	/**
446	* Expresses the language as a dialect of another language.
447	* @since 7.13.0
448	* @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
449	*/
450	@Experimental
451	public static final class DialectLanguageMetadata {
452	private final @NonNull LanguageMetadata metadata;
453	private final @NonNull String baseLanguageId;
454
455	private DialectLanguageMetadata(LanguageMetadata metadata, String baseLanguageId) {	1✔
456	this.metadata = metadata;	1✔
457	this.baseLanguageId = baseLanguageId;	1✔
458	}	1✔
459	}
460	}

pmd / pmd / 380

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous