001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.text.diff;
018
019/**
020 * Walks through {@link EditScript EditScript} objects.
021 * <p>
022 * Users should implement this interface in order to walk through
023 * the {@link EditScript EditScript} object created by the comparison
024 * of two sequences. This is a direct application of the visitor
025 * design pattern. The {@link EditScript#visit EditScript.visit}
026 * method takes an object implementing this interface as an argument,
027 * it will perform the loop over all commands in the script and the
028 * proper methods of the user class will be called as the commands are
029 * encountered.
030 * </p>
031 * <p>
032 * The implementation of the user visitor class will depend on the
033 * need. Here are two examples.
034 * </p>
035 * <p>
036 * The first example is a visitor that build the longest common
037 * subsequence:
038 * </p>
039 * <pre>
040 * import org.apache.commons.text.diff.CommandVisitor;
041 *
042 * import java.util.ArrayList;
043 *
044 * public class LongestCommonSubSequence implements CommandVisitor {
045 *
046 *   public LongestCommonSubSequence() {
047 *     a = new ArrayList();
048 *   }
049 *
050 *   public void visitInsertCommand(Object object) {
051 *   }
052 *
053 *   public void visitKeepCommand(Object object) {
054 *     a.add(object);
055 *   }
056 *
057 *   public void visitDeleteCommand(Object object) {
058 *   }
059 *
060 *   public Object[] getSubSequence() {
061 *     return a.toArray();
062 *   }
063 *
064 *   private ArrayList a;
065 *
066 * }
067 * </pre>
068 * <p>
069 * The second example is a visitor that shows the commands and the way
070 * they transform the first sequence into the second one:
071 * </p>
072 * <pre>
073 * import org.apache.commons.text.diff.CommandVisitor;
074 *
075 * import java.util.Arrays;
076 * import java.util.ArrayList;
077 * import java.util.Iterator;
078 *
079 * public class ShowVisitor implements CommandVisitor {
080 *
081 *   public ShowVisitor(Object[] sequence1) {
082 *     v = new ArrayList();
083 *     v.addAll(Arrays.asList(sequence1));
084 *     index = 0;
085 *   }
086 *
087 *   public void visitInsertCommand(Object object) {
088 *     v.insertElementAt(object, index++);
089 *     display("insert", object);
090 *   }
091 *
092 *   public void visitKeepCommand(Object object) {
093 *     ++index;
094 *     display("keep  ", object);
095 *   }
096 *
097 *   public void visitDeleteCommand(Object object) {
098 *     v.remove(index);
099 *     display("delete", object);
100 *   }
101 *
102 *   private void display(String commandName, Object object) {
103 *     System.out.println(commandName + " " + object + ": " + this);
104 *   }
105 *
106 *   public String toString() {
107 *     StringBuffer buffer = new StringBuffer();
108 *     for (Iterator iter = v.iterator(); iter.hasNext();) {
109 *       buffer.append(' ').append(iter.next());
110 *     }
111 *     return buffer.toString();
112 *   }
113 *
114 *   private ArrayList v;
115 *   private int index;
116 *
117 * }
118 * </pre>
119 *
120 * @param <T> object type
121 * @since 1.0
122 */
123public interface CommandVisitor<T> {
124
125    /**
126     * Method called when a delete command is encountered.
127     *
128     * @param object object to delete (this object comes from the first sequence).
129     */
130    void visitDeleteCommand(T object);
131
132    /**
133     * Method called when an insert command is encountered.
134     *
135     * @param object object to insert (this object comes from the second sequence).
136     */
137    void visitInsertCommand(T object);
138
139    /**
140     * Method called when a keep command is encountered.
141     *
142     * @param object object to keep (this object comes from the first sequence).
143     */
144    void visitKeepCommand(T object);
145
146}