1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 */
19 package org.apache.rat.analysis;
20
21 import org.apache.rat.configuration.builders.AllBuilder;
22 import org.apache.rat.configuration.builders.AnyBuilder;
23 import org.apache.rat.configuration.builders.CopyrightBuilder;
24 import org.apache.rat.configuration.builders.MatcherRefBuilder;
25 import org.apache.rat.configuration.builders.NotBuilder;
26 import org.apache.rat.configuration.builders.RegexBuilder;
27 import org.apache.rat.configuration.builders.SpdxBuilder;
28 import org.apache.rat.configuration.builders.TextBuilder;
29
30 /**
31 * Performs explicit checks against a line from the header of a file.
32 * For implementations that need to check multiple lines the implementation must cache the earlier lines.
33 */
34 public interface IHeaderMatcher {
35 /**
36 * The state of the matcher.
37 * <ul>
38 * <li>{@code t} - The matcher has located a match.</li>
39 * <li>{@code f} - The matcher has determined that it will not match the
40 * document.</li>
41 * <li>{@code i} - The matcher can not yet determine if a matche is made or
42 * not.</li>
43 * </ul>
44 */
45 enum State {
46 t("true"), f("false"), i("indeterminent");
47
48 private final String desc;
49
50 State(String desc) {
51 this.desc = desc;
52 }
53
54 public boolean asBoolean() {
55 switch (this) {
56 case t : return true;
57 case f : return false;
58 default:
59 case i : throw new IllegalStateException( "'asBoolean' should never be called on an indeterminate state");
60 }
61 }
62
63 @Override
64 public String toString() {
65 return super.toString()+" "+desc;
66 }
67 }
68
69 /**
70 * Get the identifier for this matcher.
71 * <p>All matchers must have unique identifiers</p>
72 *
73 * @return the Identifier for this matcher.
74 */
75 String getId();
76
77 /**
78 * Resets this state {@code State.i}.
79 * If text is being cached this method should clear that cache.
80 */
81 void reset();
82
83 /**
84 * Attempts to match {@code line} and returns the State after
85 * the match is attempted.
86 *
87 * @param line next line of text, not null
88 * @return the new state after the matching was attempted.
89 */
90 State matches(String line);
91
92 /**
93 * Gets the final state for this matcher. This is called after the EOF on the
94 * input. At this point there should be no matchers in an {@code State.i} state.
95 */
96 State finalizeState();
97
98 /**
99 * Gets the the current state of the matcher. All matchers should be
100 * in {@code State.i} at the start.
101 *
102 * @return the current state of the matcher.
103 */
104 State currentState();
105
106 /**
107 * An IHeaderMatcher builder.
108 */
109 @FunctionalInterface
110 interface Builder {
111 /**
112 * Build the IHeaderMatcher.
113 * @return a new IHeaderMatcher.
114 */
115 IHeaderMatcher build();
116
117 /**
118 * @return an instance of the standard TextBuilder.
119 * @see TextBuilder
120 */
121 static TextBuilder text() {
122 return new TextBuilder();
123 }
124
125 /**
126 * @return an instance of the standard AnyBuilder.
127 * @see AnyBuilder
128 */
129 static AnyBuilder any() {
130 return new AnyBuilder();
131 }
132
133 /**
134 * @return an instance of the standard AllBuilder.
135 * @see AllBuilder
136 */
137 static AllBuilder all() {
138 return new AllBuilder();
139 }
140
141 /**
142 * @return an instance of the standard CopyrightBuilder.
143 * @see CopyrightBuilder
144 */
145 static CopyrightBuilder copyright() {
146 return new CopyrightBuilder();
147 }
148
149 /**
150 * @return an instance of the standard SpdxBuilder.
151 * @see SpdxBuilder
152 */
153 static SpdxBuilder spdx() {
154 return new SpdxBuilder();
155 }
156
157 /**
158 * @return an instance of the standard MatcherRefBuilder.
159 * @see MatcherRefBuilder
160 */
161 static MatcherRefBuilder matcherRef() {
162 return new MatcherRefBuilder();
163 }
164
165 /**
166 * @return an instance of the standard NotBuilder.
167 * @see NotBuilder
168 */
169 static NotBuilder not() {
170 return new NotBuilder();
171 }
172
173 /**
174 * @return an instance of the standard RegexBuilder.
175 * @see RegexBuilder
176 */
177 static RegexBuilder regex() {
178 return new RegexBuilder();
179 }
180 }
181 }