XBN-Java:Insert Example Code: The basics

------------------------------------------------
Original JavaDoc with unfilled "IXC blocks" (Insert Example Code):
------------------------------------------------
   package  com.github.xbn.examples.insertexample.adder;
   /**
      <P>Adds an array of zero or more numbers. This class would normally have a license block and at-author tag--they're eliminated for brevity.</P>

      <H3>Example</H3>

   [([EXAMPLE-CODE-START:com.github.xbn.examples.insertexample.adder.AdderDemo#main()
   <PRE>[[source:getAllSourceLines_tabTo3Spcs_escForHtml_withIndent("   ")]]</PRE>

      <P><B>Output:</B></P>

   <PRE>   [C:\java_code\]java %fqclassname%
   [[output:getAllOutputLinesWithIndent("   ")]]</PRE>
   :EXAMPLE-CODE-END])]
    **/
   public class Adder_withIxcBlock01  {
      private final int sum;

      public Adder_withIxcBlock01(int... numbers_to_add)  {
         int sum2 = 0;
         for(int i : numbers_to_add)  {
            sum2 += i;
         }
         sum = sum2;
      }

      public int getSum()  {
         return  sum;
      }
   }

------------------------------------------------
It has three gaps:

   - [[source:getAllSourceLines_tabTo3Spcs_escForHtml_withIndent("   ")]]
   - %fqclassname%
   - [[output:getAllOutputLinesWithIndent("   ")]]

The function after the colon is the "output line processor". These are basic ones already created. You can also create your own, such as at the bottom of this document.

Example code to insert:
------------------------------------------------
   package  com.github.xbn.examples.insertexample.adder;
      import  com.github.xbn.examples.insertexample.adder.Adder;
   /**
      <P>Demonstration of {@code com.github.xbn.examples.insertexample.adder.}{@link #com.github.xbn.examples.insertexample.adder.Adder Adder}.</P>
    **/
   public class AdderDemo  {
      public static final void main(String[] ignored)  {
         Adder adder = new Adder();
         System.out.println(adder.getSum());

         adder = new Adder(5, -7, 20, 27);
         System.out.println(adder.getSum());
      }
   }

------------------------------------------------
Resulting JavaDoc:
------------------------------------------------

   package  com.github.xbn.examples.insertexample.adder;
   /**
      <P>Adds an array of zero or more numbers. This class would normally have a license block and at-author tag--they're eliminated for brevity.</P>

      <H3>Example</H3>

   <PRE>   package  com.github.xbn.examples.insertexample.adder;
      import  com.github.xbn.examples.insertexample.adder.Adder;
      /&#42;&#42;
       &nbsp; &nbsp; &nbsp;&lt;P&gt;Demonstration of {@code com.github.xbn.examples.insertexample.adder.}{@link #com.github.xbn.examples.insertexample.adder.Adder Adder}.&lt;/P&gt;
        &nbsp; &nbsp;&#42;&#42;/
      public class AdderDemo  {
         public static final void main(String[] ignored)  {
            Adder adder = new Adder();
            System.out.println(adder.getSum());

            adder = new Adder(5, -7, 20, 27);
            System.out.println(adder.getSum());
         }
      }</PRE>

      <P><B>Output:</B></P>

   <PRE>   [C:\java_code\]java com.github.xbn.examples.insertexample.adder.AdderDemo
      0
      45</PRE>
    **/
   public class Adder_withIxcBlock01  {
      private final int sum;

      public Adder_withIxcBlock01(int... numbers_to_add)  {
         int sum2 = 0;
         for(int i : numbers_to_add)  {
            sum2 += i;
         }
         sum = sum2;
      }

      public int getSum()  {
         return  sum;
      }
   }
------------------------------------------------
A custom output processor, which would be referenced in the IXC-block with

   <PRE>[[source:getSource_AdderDemo("   ")]]</PRE>

------------------------------------------------
      Adder adder = new Adder();
      System.out.println(adder.getSum());


   static final String getSource_AdderDemo(int start_lineNum, Iterator<String> xmplSrc_lineItr, String base_dir, Class<?> xmpl_class, String indent, String rplc_tabWith)  {

      String adderFqName = "com.github.xbn.examples.insertexample.adder.Adder";

      //Line alterers in order
      //   Final two parameters are debugging: on=System.out, off=null

         TextLineAlterer[] lineAlterers = new TextLineAlterer[] {
            //Indent tab to 3 spaces:
            NewAlterLineFor.regexReplacement(Pattern.compile("\t"), rplc_tabWith, ReplacesWhat.ALL, null, null),
            NewAlterLineFor.regexReplacement(Pattern.compile("^"), indent, ReplacesWhat.FIRST, null, null),
            NewAlterLineFor.escapeHtml(),

            //JavaDoc links for *first occurance* of function/class/object names:
            NewSrcOutLineAltererFor.firstFuncNameToJDLinkLineReplacer(adderFqName, "Adder", "", null, null)};
            NewSrcOutLineAltererFor.firstFuncNameToJDLinkLineReplacer(adderFqName, "getSum", "", null, null)};

      ExpirableTextLineAlterList alterTxtLnList = new ExpirableTextLineAlterList(
         MultiAlterType.CUMULATIVE, lineAlterers);
      //alterTxtLnList.setDebug(System.out, true);

      Iterator<LineObject<String>> lineItr = NewTextLineModeForIxc.exampleCodeElimLicenseBlkAuthorTag
            (null,     //debug_licenseStart (on=System.out, off=null)
             null,     //debug_licenseEnd
             null,     //debug_authorLine
             null).    //debug_mode
         activeLineIterator(xmplSrc_lineItr);

      //For each line returned by the text-line-mode iterator
      //(which suppresses the license block and @author tag line),
      //change them with the alteres in lineAlterers
      return  (new AllTextLineAlterer(alterTxtLnList)).getAlteredLineObjects(start_lineNum, lineItr);
   }