net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/formatter/CodeFormatter.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2004 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core.formatter;
  12
  13 import org.eclipse.text.edits.TextEdit;
  14
  15 /**
  16  * Specification for a generic source code formatter.
  17  *
  18  * @since 3.0
  19  */
  20 public abstract class CodeFormatter {
  21
  22         /**
  23          * Unknown kind
  24          */
  25         public static final int K_UNKNOWN = 0x00;
  26
  27         /**
  28          * Kind used to format an expression
  29          */
  30         public static final int K_EXPRESSION = 0x01;
  31
  32         /**
  33          * Kind used to format a set of statements
  34          */
  35         public static final int K_STATEMENTS = 0x02;
  36
  37         /**
  38          * Kind used to format a set of class body declarations
  39          */
  40         public static final int K_CLASS_BODY_DECLARATIONS = 0x04;
  41
  42         /**
  43          * Kind used to format a compilation unit
  44          */
  45         public static final int K_COMPILATION_UNIT = 0x08;
  46
  47         /**
  48          * Format <code>source</code>, and returns a text edit that correspond to
  49          * the difference between the given string and the formatted string. It
  50          * returns null if the given string cannot be formatted.
  51          *
  52          * If the offset position is matching a whitespace, the result can include
  53          * whitespaces. It would be up to the caller to get rid of preceeding
  54          * whitespaces.
  55          *
  56          * @param kind
  57          *            Use to specify the kind of the code snippet to format. It can
  58          *            be any of these: K_EXPRESSION, K_STATEMENTS,
  59          *            K_CLASS_BODY_DECLARATIONS, K_COMPILATION_UNIT, K_UNKNOWN
  60          * @param source
  61          *            the source to format
  62          * @param offset
  63          *            the given offset to start recording the edits (inclusive).
  64          * @param length
  65          *            the given length to stop recording the edits (exclusive).
  66          * @param indentationLevel
  67          *            the initial indentation level, used to shift left/right the
  68          *            entire source fragment. An initial indentation level of zero
  69          *            or below has no effect.
  70          * @param lineSeparator
  71          *            the line separator to use in formatted source, if set to
  72          *            <code>null</code>, then the platform default one will be
  73          *            used.
  74          * @return the text edit
  75          * @throws IllegalArgumentException
  76          *             if offset is lower than 0, length is lower than 0 or length
  77          *             is greater than source length.
  78          */
  79         public abstract TextEdit format(int kind, String source, int offset,
  80                         int length, int indentationLevel, String lineSeparator);
  81 }