net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ICodeFormatter.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v0.5
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v05.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  ******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import java.util.Map;
  14
  15 /**
  16  * Specification for a generic source code formatter. Client plug-ins can
  17  * contribute an implementation for an ICodeFormatter, through the extension
  18  * point "org.phpeclipse.phpdt.core.codeFormatter". In case none is found, a
  19  * default formatter can be provided through the ToolFactory.
  20  *
  21  * @see ToolFactory#createCodeFormatter()
  22  * @see ToolFactory#createDefaultCodeFormatter(Map options)
  23  * @since 2.0
  24  */
  25 public interface ICodeFormatter {
  26
  27         /**
  28          * Formats the String <code>sourceString</code>, and returns a string
  29          * containing the formatted version.
  30          *
  31          * @param string
  32          *            the string to format
  33          * @param indentationLevel
  34          *            the initial indentation level, used to shift left/right the
  35          *            entire source fragment. An initial indentation level of zero
  36          *            has no effect.
  37          * @param positions
  38          *            an array of positions to map. These are character-based source
  39          *            positions inside the original source, for which corresponding
  40          *            positions in the formatted source will be computed (so as to
  41          *            relocate elements associated with the original source). It
  42          *            updates the positions array with updated positions. If set to
  43          *            <code>null</code>, then no positions are mapped.
  44          * @param lineSeparator
  45          *            the line separator to use in formatted source, if set to
  46          *            <code>null</code>, then the platform default one will be
  47          *            used.
  48          * @return the formatted output string.
  49          */
  50         String format(String string, int indentationLevel, int[] positions,
  51                         String lineSeparator);
  52 }