<commit_before><?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<document>
  <properties>
    <title>Examples</title>
    <author email="<EMAIL>">Apache Commons Development Team</author>
    <author email="<EMAIL>"><NAME></author>
  </properties>

  <body>
    <section name="Examples">
      <p>
         We've begun to develop some example code that demonstrates the use and
         utility of the Functor component.
      </p>
      <p>
         In order to keep the examples in sync with the rest of the code,         
         each example is written as a <a href="http://junit.org/">JUnit</a> 
         <code>TestCase</code>.  The example programs are executed along with 
         all the other unit tests, and can be invoked via <code>ant test</code>
         or <code>maven test</code> once you've set up Ant or Maven as described
         in the <a href="building.html">build instructions</a>.
      </p>
      <p>
         If you're not familiar with JUnit, don't worry. An understanding of 
         JUnit isn't important for an understanding of these examples, and 
         we'll walk you through the relevant bits anyway.
      </p>
      <p>
         Two things you'll want to know about JUnit are (a) all the methods
         whose names start with "test" will be executed automatically by the 
         test suite and (b) there are various "assert" methods that can be used
         to make assertions about the Objects being tested.  If any assertion
         fails, the JUnit framework will count (and report) this as a test 
         failure.
      </p>
      <p>You can run a specific test case or sub-suite via Ant by invoking</p>
      <pre>ant -Dtest.entry=&lt;fully-specified-test-case-name&gt; test</pre>
      <p>or in Maven by invoking</p>
      <pre>maven -Dtestcase=&lt;fully-specified-test-case-name&gt; test:single</pre>
      <p>For example, to run the Quicksort example, invoke</p>
      <pre>ant -Dtest.entry=org.apache.commons.functor.example.QuicksortExample test</pre>
      <p>or</p>
      <pre>maven -Dtestcase=org.apache.commons.functor.example.QuicksortExample test:single</pre>
      <p>To run all the examples, invoke:</p>
      <pre>ant -Dtest.entry=org.apache.commons.functor.example.TestAll test</pre>
      <p>or</p>
      <pre>maven -Dtestcase=org.apache.commons.functor.example.TestAll test:single</pre>    
      <p>
         Each example is has descriptive prose mixed right in with the source, as 
         <code>/* C++ style */</code> comments.
      </p>
      <subsection name="Code Katas">        
        <p>
          "Pragmatic" <NAME> has been 
          <a href="http://pragprog.com/pragdave/">blogging</a> 
          a series of programming exercises he calls 
          <a href="http://pragprog.com/pragdave/Practices/Kata">Code Katas</a>.
          These exercises are intended to provide "practice sesssions" that allow
          programmers to hone their craft.  The notion is borrowed from the 
          practice of Karate, where, in Dave's words 
          "a kata is an exercise where you repeat a form many, many times, 
          making little improvements in each".
        </p>
        <p>
          Here we use several of Dave's Code Katas to explore the
          Commons-Functor library.
        </p>
        <dl>
          <dt><a href="http://svn.apache.org/viewvc/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/one/">Kata One: Supermarket Pricing</a></dt>
          <dd>
            Dave's <a href="http://pragprog.com/pragdave/Practices/Kata/KataOne.rdoc,v">Kata One</a> asks how
            one might implement supermarket pricing rules, like "three for a dollar" or "buy two get one free".
            By encapsulating tiny bits of logic, functors provide a useful solution to this problem, as 
            illustrated in the 
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/one/SupermarketPricingExample.java">SupermarketPricingExample</a>.
          </dd>

          <dt><a href="http://svn.apache.org/viewvc/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/two/">Kata Two: Binary Chop</a></dt>
          <dd>
            <a href="http://pragprog.com/pragdave/Practices/Kata/KataTwo.rdoc,v">Kata Two</a> asks us
            to create several different implemenations of the binary search algorithm, which once you
            get past three or four implemenations, is more difficult that it sounds.            
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/two/TestBinaryChop.java">TestBinaryChop</a>
            presents several implementations, with functor and non-functor variations.
          </dd>


          <dt><a href="http://svn.apache.org/viewvc/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/">Kata Four: Data Munging</a></dt>
          <dd>
            <a href="http://pragprog.com/pragdave/Practices/Kata/KataFour.doc,v">Kata Four</a> asks us
            to explore extreme reuse.  Our
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/DataMunger.java">DataMunger</a>
            allows for very small implementations of the 
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/TestWeather.java">weather</a>
            and
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/TestSoccer.java">soccer (football)</a>
            parsers.
          </dd>

        </dl>
      </subsection>      
      
      <subsection name="Generators">        
        <p>
          The <a href="http://svn.apache.org/viewvc/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/lines/">lines</a>
          package demonstrates a functional approach to IO using Generators and the Algorithms class.
        </p>
      </subsection>      
      
      <subsection name="Reuse Through Composition">
         <p>
            The Functor package, and more generally, a functional approach
            to program design, supports a powerful technique for balancing 
            behavior specialization and code reuse.
         </p>
         <p>
            Traditional Object Oriented design suggests inheritence as a
            mechanism code reuse, and method overloading as a mechanism for
            specialization.  For example, one defines a general purpose, perhaps
            even abstract class, say <i>AbstractList</i>, and then extend or 
            specialize this parent via subclasses, inheriting some behaviors 
            and overloading others.
         </p>
         <p>
            Functors encourage another, complementary approach to code reuse
            and behavior specialiazation: composition.  Following a compositional
            design, we create a number of simple objects and then combine them to 
            create more complex behaviors.  For example, the 
            <a href="http://commons.apache.org/pool/">Commons Pool</a> 
            component defines an <code>ObjectPool</code> type that maintains
            a collection of pooled objects, but delegates to a 
            <code>PoolableObjectFactory</code> to create, validate and destroy 
            the objects to be pooled.  Arbitrary <code>ObjectPool</code> 
            implementations can be composed with arbitrary 
            <code>PoolableObjectFactory</code>
            implementations in order to create new types of pools.
         </p>
         <p>
            The 
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/FlexiMapExample.java">FlexiMap example</a> 
            applies this design to <code>java.util.Map</code>, demonstrating how 
            "pluggable" functors can be applied to a generic <code>Map</code> structure in order
            to introduce new behaviors.           
         </p>
         <p>
            The 
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/map">map</a>
            package is a more complete example of this, implementing a number of the Commons-Collections Maps
            derived from a base 
            <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/map/FunctoredMap.java">FunctoredMap</a>.
         </p>
      </subsection>      
      <subsection name="A Quicksort Implementation">        
        <p>
          The <a href="http://svn.apache.org/repos/asf/commons/sandbox/functor/trunk/src/test/java/org/apache/commons/functor/example/QuicksortExample.java">Quicksort example</a>
          presents an implementation of the Quicksort sorting algorithm written in a functional programming
          style using Commons Functor.
        </p>
      </subsection>      
    </section>
  </body>
</document><commit_msg>sandbox links updated to proper<commit_after><?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<document>
  <properties>
    <title>Examples</title>
    <author email="<EMAIL>">Apache Commons Development Team</author>
    <author email="<EMAIL>"><NAME></author>
  </properties>

  <body>
    <section name="Examples">
      <p>
         We've begun to develop some example code that demonstrates the use and
         utility of the Functor component.
      </p>
      <p>
         In order to keep the examples in sync with the rest of the code,         
         each example is written as a <a href="http://junit.org/">JUnit</a> 
         <code>TestCase</code>.  The example programs are executed along with 
         all the other unit tests, and can be invoked via <code>ant test</code>
         or <code>maven test</code> once you've set up Ant or Maven as described
         in the <a href="building.html">build instructions</a>.
      </p>
      <p>
         If you're not familiar with JUnit, don't worry. An understanding of 
         JUnit isn't important for an understanding of these examples, and 
         we'll walk you through the relevant bits anyway.
      </p>
      <p>
         Two things you'll want to know about JUnit are (a) all the methods
         whose names start with "test" will be executed automatically by the 
         test suite and (b) there are various "assert" methods that can be used
         to make assertions about the Objects being tested.  If any assertion
         fails, the JUnit framework will count (and report) this as a test 
         failure.
      </p>
      <p>You can run a specific test case or sub-suite via Ant by invoking</p>
      <pre>ant -Dtest.entry=&lt;fully-specified-test-case-name&gt; test</pre>
      <p>or in Maven by invoking</p>
      <pre>maven -Dtestcase=&lt;fully-specified-test-case-name&gt; test:single</pre>
      <p>For example, to run the Quicksort example, invoke</p>
      <pre>ant -Dtest.entry=org.apache.commons.functor.example.QuicksortExample test</pre>
      <p>or</p>
      <pre>maven -Dtestcase=org.apache.commons.functor.example.QuicksortExample test:single</pre>
      <p>To run all the examples, invoke:</p>
      <pre>ant -Dtest.entry=org.apache.commons.functor.example.TestAll test</pre>
      <p>or</p>
      <pre>maven -Dtestcase=org.apache.commons.functor.example.TestAll test:single</pre>    
      <p>
         Each example is has descriptive prose mixed right in with the source, as 
         <code>/* C++ style */</code> comments.
      </p>
      <subsection name="Code Katas">        
        <p>
          "Pragmatic" <NAME> has been 
          <a href="http://pragprog.com/pragdave/">blogging</a> 
          a series of programming exercises he calls 
          <a href="http://pragprog.com/pragdave/Practices/Kata">Code Katas</a>.
          These exercises are intended to provide "practice sesssions" that allow
          programmers to hone their craft.  The notion is borrowed from the 
          practice of Karate, where, in Dave's words 
          "a kata is an exercise where you repeat a form many, many times, 
          making little improvements in each".
        </p>
        <p>
          Here we use several of Dave's Code Katas to explore the
          Commons-Functor library.
        </p>
        <dl>
          <dt><a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/one/">Kata One: Supermarket Pricing</a></dt>
          <dd>
            Dave's <a href="http://pragprog.com/pragdave/Practices/Kata/KataOne.rdoc,v">Kata One</a> asks how
            one might implement supermarket pricing rules, like "three for a dollar" or "buy two get one free".
            By encapsulating tiny bits of logic, functors provide a useful solution to this problem, as 
            illustrated in the 
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/one/SupermarketPricingExample.java">SupermarketPricingExample</a>.
          </dd>

          <dt><a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/two/">Kata Two: Binary Chop</a></dt>
          <dd>
            <a href="http://pragprog.com/pragdave/Practices/Kata/KataTwo.rdoc,v">Kata Two</a> asks us
            to create several different implemenations of the binary search algorithm, which once you
            get past three or four implemenations, is more difficult that it sounds.            
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/two/TestBinaryChop.java">TestBinaryChop</a>
            presents several implementations, with functor and non-functor variations.
          </dd>


          <dt><a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/">Kata Four: Data Munging</a></dt>
          <dd>
            <a href="http://pragprog.com/pragdave/Practices/Kata/KataFour.doc,v">Kata Four</a> asks us
            to explore extreme reuse.  Our
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/DataMunger.java">DataMunger</a>
            allows for very small implementations of the 
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/TestWeather.java">weather</a>
            and
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/TestSoccer.java">soccer (football)</a>
            parsers.
          </dd>

        </dl>
      </subsection>      
      
      <subsection name="Generators">        
        <p>
          The <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/lines/">lines</a>
          package demonstrates a functional approach to IO using Generators and the Algorithms class.
        </p>
      </subsection>      
      
      <subsection name="Reuse Through Composition">
         <p>
            The Functor package, and more generally, a functional approach
            to program design, supports a powerful technique for balancing 
            behavior specialization and code reuse.
         </p>
         <p>
            Traditional Object Oriented design suggests inheritence as a
            mechanism code reuse, and method overloading as a mechanism for
            specialization.  For example, one defines a general purpose, perhaps
            even abstract class, say <i>AbstractList</i>, and then extend or 
            specialize this parent via subclasses, inheriting some behaviors 
            and overloading others.
         </p>
         <p>
            Functors encourage another, complementary approach to code reuse
            and behavior specialiazation: composition.  Following a compositional
            design, we create a number of simple objects and then combine them to 
            create more complex behaviors.  For example, the 
            <a href="http://commons.apache.org/pool/">Commons Pool</a> 
            component defines an <code>ObjectPool</code> type that maintains
            a collection of pooled objects, but delegates to a 
            <code>PoolableObjectFactory</code> to create, validate and destroy 
            the objects to be pooled.  Arbitrary <code>ObjectPool</code> 
            implementations can be composed with arbitrary 
            <code>PoolableObjectFactory</code>
            implementations in order to create new types of pools.
         </p>
         <p>
            The 
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/FlexiMapExample.java">FlexiMap example</a> 
            applies this design to <code>java.util.Map</code>, demonstrating how 
            "pluggable" functors can be applied to a generic <code>Map</code> structure in order
            to introduce new behaviors.           
         </p>
         <p>
            The 
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/map">map</a>
            package is a more complete example of this, implementing a number of the Commons-Collections Maps
            derived from a base 
            <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/map/FunctoredMap.java">FunctoredMap</a>.
         </p>
      </subsection>      
      <subsection name="A Quicksort Implementation">        
        <p>
          The <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/QuicksortExample.java">Quicksort example</a>
          presents an implementation of the Quicksort sorting algorithm written in a functional programming
          style using Commons Functor.
        </p>
      </subsection>      
    </section>
  </body>
</document>
{'fraction_non_alphanumeric': 0.10181276384405265, 'fraction_numerical': 0.0005959771542090887, 'mean_word_length': 2.447354904982024, 'pattern_counts': {'":': 0, '<': 319, '<?xml version=': 2, '>': 319, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '211386', 'n_tokens_mistral': 5855, 'n_tokens_neox': 5619, 'n_words': 1723}