/*
** Module   : Indentable.java
** Abstract : API for indent management 
**
** Copyright (c) 2008-2009, Golden Code Development Corporation.
**
** -#- -I- --Date-- -----------------------Description------------------------
** 001 GES 20080309 Created initial version which allows indent state
**                  management.
*/

/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU Affero General Public License for more details.
**
** You should have received a copy of the GNU Affero General Public License
** along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

package com.goldencode.io;

/**
 * Provides an API for management of indention state.
 * <p>
 * The <code>0</code> indent level is equivalent to no indents. For each
 * positive indent level, the number of space characters written will be
 * equivalent to the indent level times the width of a single indent level
 * (which defaults to 3 spaces).
 * <p>
 * So at the <code>0</code> indent level, no spaces are written.  At the
 * <code>1</code> indent level, 3 spaces (by default) are written.  At the
 * <code>2</code> indent level, 6 spaces (by default) are written and so on.
 * By changing the width and indent level, the exact indent results can be
 * completely controlled.
 * <p>
 * This class is not thread-safe.
 *
 * @author    GES
 */
public interface Indentable
{
   /**
    * Accesses the current indent level.
    *
    * @return   Indent level.
    */
   public int getIndent();

   /**
    * Sets the current indent level.
    *
    * @param    indent
    *           New indent level.
    */
   public void setIndent(int indent);

   /**
    * Increments the indent level by 1.
    */
   public void increment();

   /**
    * Decrements the indent level by 1.
    */
   public void decrement();

   /**
    * Accesses the number of spaces in a single indent level.
    *
    * @return   Width of each indent level.
    */
   public int getWidth();

   /**
    * Sets the number of spaces in a single indent level.
    *
    * @param    width
    *           New indent width.
    */
   public void setWidth(int width);

   /**
    * Sets both the indent level and the number of spaces in a single indent
    * level. This is a convenience function to avoid 2 separate calls and
    * the small amount of shared overhead that would have been incurred in
    * those calls.
    *
    * @param    indent
    *           New indent level.
    * @param    width
    *           New indent width.
    */
   public void setPad(int indent, int width);
   
   /**
    * Get the current pad.
    *
    * @return   The pad string for the next line of output.
    */
   public String getPad();
}