src/com/googlecode/lanterna/input/CharacterPattern.java

   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 }