/*******************************************************************************
 * Copyright (c) 2000, 2008 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.jface.text.formatter;

import org.eclipse.jface.text.IDocument;

/**
 * Extension interface for {@link IContentFormatter}.
 * <p>
 * Updates the content formatter to be able to pass {@link IFormattingContext} context objects to
 * {@link IFormattingStrategyExtension} objects operating in context based mode.
 * </p>
 * Clients using context based formatting call the method
 * <code>format(IDocument, IFormattingContext)</code> with a properly initialized formatting
 * context.<br>
 * The formatting context must be set up according to the desired formatting mode:
 * <ul>
 * <li>For whole document formatting set the property
 * {@link FormattingContextProperties#CONTEXT_DOCUMENT}. This is equivalent to setting
 * {@link FormattingContextProperties#CONTEXT_REGION} with a region spanning the whole
 * document.</li>
 * <li>For multiple region formatting set the property
 * {@link FormattingContextProperties#CONTEXT_REGION}. Note that the content formatter automatically
 * aligns the region to a block selected region, and if the region spans multiple partitions, it
 * also completes eventual partitions covered only partially by the region.</li>
 * </ul>
 * Depending on the registered formatting strategies, more context information must be passed in the
 * formatting context, like e.g. {@link FormattingContextProperties#CONTEXT_PREFERENCES}.
 * <p>
 * Note that in context based mode the content formatter is fully reentrant, but not thread-safe.
 * </p>
 *
 * @see IFormattingContext
 * @see FormattingContextProperties
 * @since 3.0
 */
public interface IContentFormatterExtension {

	/**
	 * Formats the given region of the specified document.
	 * <p>
	 * The formatter may safely assume that it is the only subject that modifies the document at
	 * this point in time. This method is fully reentrant, but not thread-safe.
	 * </p>
	 * <p>
	 * The formatting process performed by <code>format(IDocument, IFormattingContext)</code>
	 * happens as follows:
	 * </p>
	 * <ul>
	 * <li>In a first pass the content formatter formats the range of the document to be formatted
	 * by using the master formatting strategy. This happens regardless of the content type of the
	 * underlying partition.</li>
	 * <li>In the second pass, the range is formatted again, this time using the registered slave
	 * formatting strategies. For each partition contained in the range to be formatted, the content
	 * formatter determines its content type and formats the partition with the correct formatting
	 * strategy.</li>
	 * </ul>
	 *
	 * @param document the document to be formatted
	 * @param context the formatting context to pass to the formatting strategies. This argument
	 *            must not be <code>null</code>.
	 */
	void format(IDocument document, IFormattingContext context);
}
