Fix UTF8 bug, create first executable JAR file
[jvcard.git] / src / com / googlecode / lanterna / input / CharacterPattern.java
... / ...
CommitLineData
1/*
2 * This file is part of lanterna (http://code.google.com/p/lanterna/).
3 *
4 * lanterna is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this program. If not, see <http://www.gnu.org/licenses/>.
16 *
17 * Copyright (C) 2010-2015 Martin
18 */
19package com.googlecode.lanterna.input;
20
21import java.util.List;
22
23/**
24 * Used to compare a list of character if they match a particular pattern, and in that case, return the kind of
25 * keystroke this pattern represents
26 *
27 * @author Martin, Andreas
28 */
29@SuppressWarnings("WeakerAccess")
30public interface CharacterPattern {
31
32 /**
33 * Given a list of characters, determine whether it exactly matches
34 * any known KeyStroke, and whether a longer sequence can possibly match.
35 * @param seq of characters to check
36 * @return see {@code Matching}
37 */
38 Matching match(List<Character> seq);
39
40 /**
41 * This immutable class describes a matching result. It wraps two items,
42 * partialMatch and fullMatch.
43 * <dl>
44 * <dt>fullMatch</dt><dd>
45 * The resulting KeyStroke if the pattern matched, otherwise null.<br>
46 * Example: if the tested sequence is {@code Esc [ A}, and if the
47 * pattern recognized this as {@code ArrowUp}, then this field has
48 * a value like {@code new KeyStroke(KeyType.ArrowUp)}</dd>
49 * <dt>partialMatch</dt><dd>
50 * {@code true}, if appending appropriate characters at the end of the
51 * sequence <i>can</i> produce a match.<br>
52 * Example: if the tested sequence is "Esc [", and the Pattern would match
53 * "Esc [ A", then this field would be set to {@code true}.</dd>
54 * </dl>
55 * In principle, a sequence can match one KeyStroke, but also say that if
56 * another character is available, then a different KeyStroke might result.
57 * This can happen, if (e.g.) a single CharacterPattern-instance matches
58 * both the Escape key and a longer Escape-sequence.
59 */
60 class Matching {
61 public final KeyStroke fullMatch;
62 public final boolean partialMatch;
63
64 /**
65 * Re-usable result for "not yet" half-matches
66 */
67 public static final Matching NOT_YET = new Matching( true, null );
68
69 /**
70 * Convenience constructor for exact matches
71 *
72 * @param fullMatch the KeyStroke that matched the sequence
73 */
74 public Matching(KeyStroke fullMatch) {
75 this(false,fullMatch);
76 }
77 /**
78 * General constructor<p>
79 * For mismatches rather use {@code null} and for "not yet" matches use NOT_YET.
80 * Use this constructor, where a sequence may yield both fullMatch and
81 * partialMatch or for merging result Matchings of multiple patterns.
82 *
83 * @param partialMatch true if further characters could lead to a match
84 * @param fullMatch The perfectly matching KeyStroke
85 */
86 public Matching(boolean partialMatch, KeyStroke fullMatch) {
87 this.partialMatch = partialMatch;
88 this.fullMatch = fullMatch;
89 }
90
91 @Override
92 public String toString() {
93 return "Matching{" + "partialMatch=" + partialMatch + ", fullMatch=" + fullMatch + '}';
94 }
95 }
96}