1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.text.diff;
18
19 /**
20 * Walks through {@link EditScript EditScript} objects.
21 * <p>
22 * Users should implement this interface in order to walk through
23 * the {@link EditScript EditScript} object created by the comparison
24 * of two sequences. This is a direct application of the visitor
25 * design pattern. The {@link EditScript#visit EditScript.visit}
26 * method takes an object implementing this interface as an argument,
27 * it will perform the loop over all commands in the script and the
28 * proper methods of the user class will be called as the commands are
29 * encountered.
30 * </p>
31 * <p>
32 * The implementation of the user visitor class will depend on the
33 * need. Here are two examples.
34 * </p>
35 * <p>
36 * The first example is a visitor that build the longest common
37 * subsequence:
38 * </p>
39 * <pre>
40 * import org.apache.commons.text.diff.CommandVisitor;
41 *
42 * import java.util.ArrayList;
43 *
44 * public class LongestCommonSubSequence implements CommandVisitor {
45 *
46 * public LongestCommonSubSequence() {
47 * a = new ArrayList();
48 * }
49 *
50 * public void visitInsertCommand(Object object) {
51 * }
52 *
53 * public void visitKeepCommand(Object object) {
54 * a.add(object);
55 * }
56 *
57 * public void visitDeleteCommand(Object object) {
58 * }
59 *
60 * public Object[] getSubSequence() {
61 * return a.toArray();
62 * }
63 *
64 * private ArrayList a;
65 *
66 * }
67 * </pre>
68 * <p>
69 * The second example is a visitor that shows the commands and the way
70 * they transform the first sequence into the second one:
71 * </p>
72 * <pre>
73 * import org.apache.commons.text.diff.CommandVisitor;
74 *
75 * import java.util.Arrays;
76 * import java.util.ArrayList;
77 * import java.util.Iterator;
78 *
79 * public class ShowVisitor implements CommandVisitor {
80 *
81 * public ShowVisitor(Object[] sequence1) {
82 * v = new ArrayList();
83 * v.addAll(Arrays.asList(sequence1));
84 * index = 0;
85 * }
86 *
87 * public void visitInsertCommand(Object object) {
88 * v.insertElementAt(object, index++);
89 * display("insert", object);
90 * }
91 *
92 * public void visitKeepCommand(Object object) {
93 * ++index;
94 * display("keep ", object);
95 * }
96 *
97 * public void visitDeleteCommand(Object object) {
98 * v.remove(index);
99 * 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 */
123 public 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 }