/*##############################################################################

FUNNNELWEB COPYRIGHT
====================
FunnelWeb is a literate-programming macro preprocessor.
The FunnelWeb web is at http://www.ross.net/funnelweb/

Copyright (c) Ross N. Williams 1992. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of Version 2 of the GNU General Public License as
published by the Free Software Foundation (http://www.gnu.org/).

This program is distributed WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See Version 2 of the GNU General Public License for more details.

You should have received a copy of Version 2 of the GNU General Public
License along with this program. If not, you can obtain a copy as follows:
   ftp://prep.ai.mit.edu/pub/gnu/COPYING-2.0
or write to:
    Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Section 2a of the license requires that all changes to this file be
recorded prominently in this file. Please record all changes here.

Programmers:
   RNW  Ross N. Williams (ross@ross.net)

Changes:
   07-May-1992  RNW  Program prepared for release under GNU GPL V2.

##############################################################################*/


/******************************************************************************/
/*                                   SECTION.H                                */
/******************************************************************************/
/*                                                                            */
/* This package provides a very simple, very small abstraction for a section  */
/* number. A section number is a hierarchical group of numbers such as is     */
/* used to number the sections in documents. For example: 4.5.1.3 is a        */
/* section number. This package provides an abstraction for these numbers     */
/* that assists in their incrementing at different levels and in writing them */
/* out. The package also checks for hierarchical inconsistencies.             */
/*                                                                            */
/******************************************************************************/

/* Ensure that the body of this header file is included at most once.         */
#ifndef DONE_SECTION
#define DONE_SECTION

/******************************************************************************/

#include "style.h"

/******************************************************************************/

/* The following constant defines the maximum number of levels that a         */
/* FunnelWeb document can have. @A corresponds to level 1.                    */
#define SECLEV_MAX 5

/* The following constant defines the maximum length of a string representing */
/* a section. This is calculated as the maximum number of levels multiplied   */
/* by 1 (for the separating dots) plus a safe size for a decimal number.      */
#define SECSTR_MAX (SECLEV_MAX*(1+10))

/* The following structure stores a single section number. The sc_level       */
/* field is the level of this field and is in the range [1,SECLEV_MAX]. The   */
/* sc_num field is defined only for elements [1,level] and contains the       */
/* hierarchy number at each level.                                            */
/* Example: For SECLEVMAX=4 and "3.4.1", level=3 and num=[?,3,4,1,?].         */
/* Note: The first question mark is for element zero which is always unknown. */
typedef struct
  {
   ulong  sn_magic;              /* Used to detect uninitialized sn objects.  */
   ubyte_ sn_lev;                /* Level number of section.                  */
   uword_ sn_num[SECLEV_MAX+1];  /* Hierarchical level numbers.               */
  } sn_t;

typedef sn_t *p_sn_t;

/******************************************************************************/

EXPORT void sn_ini P_((p_sn_t));
/* Initializes the specified section object to the empty section at level 0.  */
/* All sections must be initialized before any other operations are performed.*/

EXPORT void sn_set P_((p_sn_t,ubyte));
/* Sets the specified section to 1.1.1.1.1.1... at the given level.           */
/* Example: sn_set(p_sn,3) yields a section set to 1.1.1.                     */
/* Raises an error if the specified level is out of range.                    */

EXPORT void sn_inc P_((p_sn_t,ubyte));
/* Increments the number of the specified section object at the specified     */
/* level. This also has the effect of setting all lower levels to 0. For      */
/* example, 3.4.5.1 followed by sn_inc(&sn,2) would become 3.5.               */
/* Raises an error if the level is two or more lower than the current level   */
/* Example: You can't increment 2.4.1 at level 5.                             */
/* Raises an error if the specified level is out of range.                    */
/* Raises an error if a number at any level becomes too large (>60000).       */

EXPORT ubyte sn_lev P_((p_sn_t));
/* Returns the level number of the specified section.                         */

EXPORT void sn_str P_((p_sn_t,char *));
/* Writes a textual representation of the specified section into the given    */
/* string. The string must be able to hold at least SECSTRMAX characters.     */

/******************************************************************************/

/* For #ifndef preventing multiple inclusion of the body of this header file. */
#endif

/******************************************************************************/
/*                               End of SECTION.H                             */
/******************************************************************************/