/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -
 * 
 * The "License" shall be the Mozilla Public License Version 1.1, except
 * Sections 6.2 and 11, but with the addition of the below defined Section 14.
 * You may obtain a copy of the Mozilla Public License Version 1.1 at
 * <http://www.mozilla.org/MPL/>. The contents of this file are subject to the
 * License; you may not use this file except in compliance with the License.
 * 
 * Section 14: MISCELLANEOUS.
 * This License represents the complete agreement concerning subject matter
 * hereof. If any provision of this License is held to be unenforceable, such
 * provision shall be reformed only to the extent necessary to make it
 * enforceable. This License shall be governed by German law provisions. Any
 * litigation relating to this License shall be subject to German jurisdiction.
 * 
 * Once Covered Code has been published under a particular version of the
 * License, You may always continue to use it under the terms of that version.
 + The Initial Developer and no one else has the right to modify the terms
 * applicable to Covered Code created under this License.
 * (End of Section 14)
 * 
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Original Code is the Text to HTML converter code.
 * 
 * The Initial Developer of the Original Code is Ben Bucksch
 * <http://www.bucksch.org>. Portions created by Ben Bucksch are Copyright
 * (C) 1999 Ben Bucksch. All Rights Reserved.
 * 
 * Contributor(s):
 */

/*
  Description: Currently only functions to enhance plain text with HTML tags.
  <p>
  Wrapper class for various parsing routines, that convert plain text to HTML.
  They try to recognize cites, URLs, plain text formattting like *bold* etc.
  <p>
  Use the nsString versions of these functions in the mozTXTToHTMLConv
  implementation when calling from C++.
  <p>
  There're a lot of protected virtual functions in the mozTXTToHTMLConv
  implementation, that might be helpful, too. Add wrappers for them to this or
  any other interface, if you need them. It's easier to add a function than to
  remove it, so I don't add them now. Here's the list:

  nsAutoString EscapeChar(const PRUnichar ch)
  nsAutoString EscapeStr(const nsAutoString& aString)
  nsAutoString UnescapeStr(const nsAutoString& aString)
  nsAutoString CompleteAbbreviatedURL(const nsAutoString& text, PRUint32 pos)
  PRBool FindURL(const nsAutoString& text, PRUint32 pos,
       PRUint32 whathasbeendone, nsAutoString& outputHTML,
       PRInt32& replaceBefore, PRInt32& replaceAfter)
  nsAutoString Right(const nsAutoString& text, PRUint32 start)
  PRBool ItMatchesDelimited(const nsAutoString& text, const nsAutoString& rep,
       LIMTYPE before, LIMTYPE after)
  PRUint32 NumberOfMatches(const nsAutoString& text, const nsAutoString& rep,
       LIMTYPE before, LIMTYPE after)
 */

#include "nsIStreamConverter.idl"
#include "nsrootidl.idl"

%{C++
// {77c0e42a-1dd2-11b2-8ebf-edc6606f2f4b}
#define MOZITXTTOHTMLCONV_CID \
    { 0x77c0e42a, 0x1dd2, 0x11b2, \
    { 0x8e, 0xbf, 0xed, 0xc6, 0x60, 0x6f, 0x2f, 0x4b } }
%}

[scriptable, uuid(77c0e42a-1dd2-11b2-8ebf-edc6606f2f4b)]
interface mozITXTToHTMLConv : nsIStreamConverter {

  const unsigned long kURLs = 1 << 1;
  const unsigned long kGlyphSubstitution = 1 << 2;  // Smilies, &reg; etc.
  const unsigned long kStructPhrase = 1 << 3;       // E.g. *bold* -> <strong>

/*
  @param text: plain text to scan. May be a line, paragraph (recommended)
              or just a substring.<p>
    	      <em>Note:</em> ScanTXT(a, o) + ScanTXT(b, o) may be !=
    	      Scan(a + b, o)
  @param whattodo: Bitfield describing the modes of operation
 */
  wstring   scanTXT([const] in wstring text, in unsigned long whattodo);

/*
  Adds additional formatting to user edited text, that the user was too lazy
  "unknowledged" (DELETEME: is that a word?) to make.
  <p>
  <em>Note:</em> Don't use kGlyphSubstitution with this function. This option
  generates tags, that are unuseable for UAs other than Mozilla. This would
  be a data loss bug.

  @param text: HTML source to scan. May be a line, paragraph (recommended)
              or just a substring.
	          <em>Note:</em> ScanTXT(a, o) + ScanTXT(b, o) may be !=
	          Scan(a + b, o)
  @param whattodo: Bitfield describing the modes of operation
 */
  wstring   scanHTML([const] in wstring text, in unsigned long whattodo);

/*
  @param line: line in original msg, possibly starting starting with
              txt quote tags like ">"
  @param logLineStart: pos in line, where the real content (logical line)
              begins, i.e. pos after all txt quote tags.
              E.g. position of "t" in "> > text".
              Initial value must be 0, unless line is not real line.
  @return Cite Level, i.e. number of txt quote tags found, i.e. number of
              nested quotes.
 */
  unsigned long   citeLevelTXT([const] in wstring line,
                               out unsigned long logLineStart);
};
