Commit | Line | Data |
---|---|---|
a3b510ab NR |
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 | */ | |
19 | package com.googlecode.lanterna.input; | |
20 | ||
21 | import 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") | |
30 | public 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 | } |