/*******************************************************************************
* Copyright (c) 2009, 2012 Andrew Gvozdev and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Andrew Gvozdev - initial API and implementation
*******************************************************************************/
package org.eclipse.cdt.core.language.settings.providers;
import java.util.List;
import org.eclipse.cdt.core.model.LanguageManager;
import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
import org.eclipse.cdt.core.settings.model.ICLanguageSettingEntry;
import org.eclipse.cdt.core.settings.model.ICSettingEntry;
import org.eclipse.core.resources.IResource;
/**
* Base interface to provide list of {@link ICLanguageSettingEntry}.
* This interface is used to deliver additions to compiler options such as
* include paths (-I) or preprocessor defines (-D) and others (see
* {@link ICSettingEntry#INCLUDE_PATH} and other kinds).
* <br><br>
* To define a provider like that use extension point
* {@code org.eclipse.cdt.core.LanguageSettingsProvider} and implement this
* interface. The recommended way of implementing is to extend
* {@link LanguageSettingsSerializableProvider} and implement {@link ILanguageSettingsEditableProvider}.
* That will give the ability to persist and edit/clean entries by user in UI.
* The clone methods defined by {@link ILanguageSettingsEditableProvider} should be
* chained as done for example by {@link LanguageSettingsGenericProvider}.
* <br><br>
* CDT provides a few general use implementations in the core such as {@link LanguageSettingsBaseProvider}
* or {@link LanguageSettingsSerializableProvider} or {@link LanguageSettingsGenericProvider}
* which could be used out of the box or built upon. There are also abstract classes in build
* plugins {@code AbstractBuildCommandParser} and {@code AbstractBuiltinSpecsDetector} which
* serve as a base for output parsers and built-in compiler language settings detectors.
* See also extension point schema description LanguageSettingsProvider.exsd.
*
* @since 5.4
*/
public interface ILanguageSettingsProvider {
/**
* Id is used to keep track of the providers internally. Use unique id
* to represent the provider.
*
* @return Id of the provider.
*/
public String getId();
/**
* Name is used to present the provider to the end user in UI.
*
* @return name of the provider.
*/
public String getName();
/**
* Returns the list of setting entries for the given configuration description,
* resource and language.
* <br><br>
* Note to implementers - this method should not be used to do any long running
* operations such as extensive calculations or reading files. If you need to do
* so, the recommended way is to do the calculations outside of
* this function call - in advance and on appropriate event. For example, Build
* Output Parser prepares the list and stores it in internal cache while parsing output.
* {@link #getSettingEntries(ICConfigurationDescription, IResource, String)} will
* return cached entries when asked. You can also implement {@link ICListenerAgent}
* interface to get registered and listen to arbitrary events.
*
* @param cfgDescription - configuration description.
* @param rc - resource such as file or folder.
* If {@code null}, the default entries for all resources are returned.
* @param languageId - language id.
* If {@code null}, the default entries for all languages are returned.
* (see {@link LanguageManager#getLanguageForFile(org.eclipse.core.resources.IFile, ICConfigurationDescription)}).
*
* @return the list of setting entries or {@code null} if no settings defined.
* The list needs to be a pooled list created by {@link LanguageSettingsStorage#getPooledList(List)}
* to save memory and avoid deep equality comparisons.
*/
public List<ICLanguageSettingEntry> getSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId);
}