//
//   COMPONENT_NAME: some
//
//   ORIGINS: 27
//
//
//    25H7912  (C)  COPYRIGHT International Business Machines Corp. 1992,1994,1996 
//   All Rights Reserved
//   Licensed Materials - Property of IBM
//   US Government Users Restricted Rights - Use, duplication or
//   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
//
//#  @(#) somc/sctmplt.idl 2.10 5/9/96 15:31:32 [12/22/96 21:12:04]


#ifndef sctmplt_idl
#define sctmplt_idl

#include <somobj.idl>
interface SOMStringTableC;

enum somtCommentStyleT { somtDashesE, somtCPPE, somtCSimpleE, somtCBlockE };

interface SOMTTemplateOutputC : SOMObject
{
  const long MAX_INPUT_LINE_LENGTH = 1024;
  const long MAX_OUTPUT_LINE_LENGTH = 4096;
  attribute somtCommentStyleT somtCommentStyle;
  
  // Controls the style in which comments are wrtten as follows:
  //   somtDashesE: "--" at the start of each line
  //   somtCPPE: C++ style, "//" at the start of each line
  //   somtCSimpleE: simple C style, each line wrapped in / * and * /
  //   somtCBlockE: block C style, block style, ie leading / * then a * on each
  //              line and then a final * /

  attribute long somtLineLength;
  
  // Controls list output only.  Default is 72.
  // At least one list item will be output on each line, so making
  // this value very short will cause list items to be placed on
  // separate lines.

  attribute boolean somtCommentNewline;
  string somtGetSymbol(in string name);
  
  // Returns the value associated with <name>.  If no value is
  // associated with <name> then NULL is returned

  void somtSetSymbol(in string name, 
                    in string value);
  
  // Makes the symbol with name <name> have value <value>.  This will
  // overwrite any previous value the symbol had, and add the symbol
  // if necessary.
  // Takes over ownership of both name and value.

  void somtSetSymbolCopyName(in string name, 
                            in string value);
  
  // See somtSetSymbol
  // Only takes over ownership of value.

  void somtSetSymbolCopyValue(in string name, 
                             in string value);
  
  // See somtSetSymbol
  // Only takes over ownership of name.

  void somtSetSymbolCopyBoth(in string name, 
                            in string value);
  
  // See somtSetSymbol
  // Does not take over ownership of either <name> or <value>

  boolean somtCheckSymbol(in string name);
  
  // Returns 1 (true) if the indicated symbol has non-null, non-zero
  // length value, and 0 (false) otherwise.

  void somtSetOutputFile(inout FILE fp);
  
  // All template output will be directed to <fp>. Default is <stdout>.

  void somto(in string tmplt);
  
  // Outputs a template, <tmplt>, after substitution for any symbols
  // that occur in it.  Five substitutions are supported: simple,
  // list, comment, tab, and conditional.
  // Substitutable items in the template are bracketed with angle
  // brackets. (Backslash can be used to escape an angle bracket.)
  // Simple substitutions just replace a symbol with its value. If
  // the symbol has no value in this template object then the symbol
  // is replaced error string but no error is raised.
  // List substitution assumes that the symbol has a value in output
  // template list form. This is a newline separated string of
  // values. The list substitution specification consists of four
  // parts, a prefix, a symbol, a separator, and a list indicator.
  // prefixes and separators can only be composed of blanks, comma,
  // colons, and semi-colons.  The list indicator is "..." (three
  // periods).  For example, the list substitution
  // specification "<, name, ...> has a prefix of ", ", a symbol of
  // "name" and a separator of ", ".  The prefix will be used
  // whenever there is at least one item in the list and the separator
  // will be used between any two list items.  After the first items
  // of a list is placed each additional item is evaluated to see if
  // it would begin after the line length limit (set by
  // _set_somtLineLength), if it would then a new line is begun and the
  // value is placed directly under the first item.
  // Comment substitution assumes that the symbol has a value in
  // output template list form.  A comment specification consists of
  // a comment indicator followed by a symbol name. The comment
  // indicator is "--".  Eg, <-- classComment> is a valid comment
  // substitution specification.  The lines of the comment are output
  // according to the current comment style (see <somtCommentStyle>)
  // and alined with the starting column of the comment
  // specification.
  // Tab substitution is specified by <@dd> where "dd" is a valid
  // positive integer. Blanks will be inserted into the output stream
  // if necessary to position the next character of output at the
  // column indicated by "dd".
  // Conditional substitution is specified by puting a question mark,
  // "?", in column one of the template line.  The line will not be
  // output at all unless at least one valid, non-blank,  symbol
  // substitution  occurs on the line.

  void somtOutputComment(in string comment);
  
  // Inserts a comment into the output stream.  <comment> must be a
  // string containing the comment with lines in the comment
  // seperated by newlines.
  // The style of output is controlled by <somtCommentStyle>

  void somtOutputSection(in string sectionName);
  
  // Just like <somto> above, except <sectionName> must be a symbol
  // whose value will be used as the template.

  void somtAddSectionDefinitions(in string defString);
  
  // <defString> must be a string of the form:
  // :section1
  // value 1 line 1
  // value 1 line 2
  // :section2
  // value 2 line 1
  // :section3
  // value 3 line 1
  // Where the lines that contain a ":" in column 1 immediately followed
  // by a single name are used to intro the start of a new section.
  // The section is named by the name on the colon line.  A backslash
  // can be used to escape a colon in column one that is not supposed
  // to start a new section.
  // Adds the indicated section definitions to this template.

  void somtReadSectionDefinitions(inout FILE fp);
  
  // Reads section definitions from the indicated file.  The section
  // definitions must be in the form defined above in
  // <somtAddSectionDefinitions>.

  string somtExpandSymbol(in string s, 
                         in string buf);
  
  // Expands simple symbols in an already expanded string.  Thus if you
  // have a symbol which is itself a Section in a template file, and this
  // section could have other sections in it then you should call this
  // method.

#ifdef __SOMIDL__
  implementation {
    releaseorder: _get_somtCommentStyle,_set_somtCommentStyle,_get_somtLineLength, 
                  _set_somtLineLength,_set_somtCommentNewline,_get_somtCommentNewline, 
                  somtGetSymbol,somtSetSymbol,somtSetSymbolCopyName,somtSetSymbolCopyValue, 
                  somtSetSymbolCopyBoth,somtCheckSymbol,somtSetOutputFile, 
                  somto,somtOutputComment,somtOutputSection, 
                  somtAddSectionDefinitions,somtReadSectionDefinitions, 
                  somtExpandSymbol;
  
    //# Class Modifiers
    majorversion = 2;
    minorversion = 1;
    filestem = sctmplt;
#ifdef _WIN32
    dllname = "some.dll";
#endif
    callstyle = oidl;
  
    passthru C_h =        "#include <stdio.h>"
"typedef enum somtCommentStyleT { somtDashesE, somtCPPE, somtCSimpleE, somtCBlockE } somtCommentStyleT;";
    passthru C_xh =        "#include <stdio.h>"
"typedef enum somtCommentStyleT { somtDashesE, somtCPPE, somtCSimpleE, somtCBlockE } somtCommentStyleT;";
  
    //# Internal Instance Variables
    SOMStringTableC stab;           
    FILE *fp;                       
    long currentColumn;             
    boolean conditionalLine;            
    boolean anyExpansions;              
    char oBuf[MAX_OUTPUT_LINE_LENGTH];     
    long oBufPos;                   
  
    //# Method Modifiers
    somInit: override;
    somUninit: override;
    somPrintSelf: override;
    somDumpSelfInt: override;
    somtSetOutputFile: mplan=none;
    somtReadSectionDefinitions: mplan=none;
  };
#endif /* __SOMIDL__ */
};


#endif  /* sctmplt_idl */
