/*******************************************************************************
 * Copyright (c) 2000, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.ui.keys;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.StringTokenizer;
import org.eclipse.ui.internal.util.Util;

/**
 * <p>
 * A <code>KeySequence</code> is defined as a list of zero or more
 * <code>KeyStrokes</code>, with the stipulation that all <code>KeyStroke</code>
 * objects must be complete, save for the last one, whose completeness is
 * optional. A <code>KeySequence</code> is said to be complete if all of its
 * <code>KeyStroke</code> objects are complete.
 * </p>
 * <p>
 * All <code>KeySequence</code> objects have a formal string representation
 * available via the <code>toString()</code> method. There are a number of
 * methods to get instances of <code>KeySequence</code> objects, including one
 * which can parse this formal string representation.
 * </p>
 * <p>
 * All <code>KeySequence</code> objects, via the <code>format()</code> method,
 * provide a version of their formal string representation translated by
 * platform and locale, suitable for display to a user.
 * </p>
 * <p>
 * <code>KeySequence</code> objects are immutable. Clients are not permitted to
 * extend this class.
 * </p>
 *
 * @deprecated Please use org.eclipse.jface.bindings.keys.KeySequence
 * @since 3.0
 */
@Deprecated
public final class KeySequence implements Comparable {

	/**
	 * The delimiter between multiple key strokes in a single key sequence --
	 * expressed in the formal key stroke grammar. This is not to be displayed to
	 * the user. It is only intended as an internal representation.
	 */
	public static final String KEY_STROKE_DELIMITER = "\u0020"; //$NON-NLS-1$

	/**
	 * An empty key sequence instance for use by everyone.
	 */
	private static final KeySequence EMPTY_KEY_SEQUENCE = new KeySequence(Collections.EMPTY_LIST);

	/**
	 * An internal constant used only in this object's hash code algorithm.
	 */
	private static final int HASH_FACTOR = 89;

	/**
	 * An internal constant used only in this object's hash code algorithm.
	 */
	private static final int HASH_INITIAL = KeySequence.class.getName().hashCode();

	/**
	 * The set of delimiters for <code>KeyStroke</code> objects allowed during
	 * parsing of the formal string representation.
	 */
	public static final String KEY_STROKE_DELIMITERS = KEY_STROKE_DELIMITER + "\b\r\u007F\u001B\f\n\0\t\u000B"; //$NON-NLS-1$

	/**
	 * Gets an instance of <code>KeySequence</code>.
	 *
	 * @return a key sequence. This key sequence will have no key strokes.
	 *         Guaranteed not to be <code>null</code>.
	 */
	public static KeySequence getInstance() {
		return EMPTY_KEY_SEQUENCE;
	}

	/**
	 * Gets an instance of <code>KeySequence</code> given a key sequence and a key
	 * stroke.
	 *
	 * @param keySequence a key sequence. Must not be <code>null</code>.
	 * @param keyStroke   a key stroke. Must not be <code>null</code>.
	 * @return a key sequence that is equal to the given key sequence with the given
	 *         key stroke appended to the end. Guaranteed not to be
	 *         <code>null</code>.
	 */
	public static KeySequence getInstance(KeySequence keySequence, KeyStroke keyStroke) {
		if (keySequence == null || keyStroke == null) {
			throw new NullPointerException();
		}

		List<KeyStroke> keyStrokes = new ArrayList<>(keySequence.getKeyStrokes());
		keyStrokes.add(keyStroke);
		return new KeySequence(keyStrokes);
	}

	/**
	 * Gets an instance of <code>KeySequence</code> given a single key stroke.
	 *
	 * @param keyStroke a single key stroke. Must not be <code>null</code>.
	 * @return a key sequence. Guaranteed not to be <code>null</code>.
	 */
	public static KeySequence getInstance(KeyStroke keyStroke) {
		return new KeySequence(Collections.singletonList(keyStroke));
	}

	/**
	 * Gets an instance of <code>KeySequence</code> given an array of key strokes.
	 *
	 * @param keyStrokes the array of key strokes. This array may be empty, but it
	 *                   must not be <code>null</code>. This array must not contain
	 *                   <code>null</code> elements.
	 * @return a key sequence. Guaranteed not to be <code>null</code>.
	 */
	public static KeySequence getInstance(KeyStroke[] keyStrokes) {
		return new KeySequence(Arrays.asList(keyStrokes));
	}

	/**
	 * Gets an instance of <code>KeySequence</code> given a list of key strokes.
	 *
	 * @param keyStrokes the list of key strokes. This list may be empty, but it
	 *                   must not be <code>null</code>. If this list is not empty,
	 *                   it must only contain instances of <code>KeyStroke</code>.
	 * @return a key sequence. Guaranteed not to be <code>null</code>.
	 */
	public static KeySequence getInstance(List keyStrokes) {
		return new KeySequence(keyStrokes);
	}

	/**
	 * Gets an instance of <code>KeySequence</code> given a new-style key sequence.
	 *
	 * @param newKeySequence The new-style key sequence to convert into a legacy key
	 *                       sequence; must not be <code>null</code>.
	 * @return a key sequence; never <code>null</code>.
	 */
	public static KeySequence getInstance(final org.eclipse.jface.bindings.keys.KeySequence newKeySequence) {
		final org.eclipse.jface.bindings.keys.KeyStroke[] newKeyStrokes = newKeySequence.getKeyStrokes();
		final int newKeyStrokesCount = newKeyStrokes.length;
		final List<KeyStroke> legacyKeyStrokes = new ArrayList<>(newKeyStrokesCount);

		for (int i = 0; i < newKeyStrokesCount; i++) {
			final org.eclipse.jface.bindings.keys.KeyStroke newKeyStroke = newKeyStrokes[i];
			legacyKeyStrokes.add(SWTKeySupport
					.convertAcceleratorToKeyStroke(newKeyStroke.getModifierKeys() | newKeyStroke.getNaturalKey()));
		}

		return new KeySequence(legacyKeyStrokes);
	}

	/**
	 * Gets an instance of <code>KeySequence</code> by parsing a given a formal
	 * string representation.
	 *
	 * @param string the formal string representation to parse.
	 * @return a key sequence. Guaranteed not to be <code>null</code>.
	 * @throws ParseException if the given formal string representation could not be
	 *                        parsed to a valid key sequence.
	 */
	public static KeySequence getInstance(String string) throws ParseException {
		if (string == null) {
			throw new NullPointerException();
		}

		List<KeyStroke> keyStrokes = new ArrayList<>();
		StringTokenizer stringTokenizer = new StringTokenizer(string, KEY_STROKE_DELIMITERS);

		while (stringTokenizer.hasMoreTokens()) {
			keyStrokes.add(KeyStroke.getInstance(stringTokenizer.nextToken()));
		}

		try {
			return new KeySequence(keyStrokes);
		} catch (Throwable t) {
			throw new ParseException("Could not construct key sequence with these key strokes: " //$NON-NLS-1$
					+ keyStrokes);
		}
	}

	/**
	 * The cached hash code for this object. Because <code>KeySequence</code>
	 * objects are immutable, their hash codes need only to be computed once. After
	 * the first call to <code>hashCode()</code>, the computed value is cached here
	 * for all subsequent calls.
	 */
	private transient int hashCode;

	/**
	 * A flag to determine if the <code>hashCode</code> field has already been
	 * computed.
	 */
	private transient boolean hashCodeComputed;

	/**
	 * The list of key strokes for this key sequence.
	 */
	private List<KeyStroke> keyStrokes;

	/**
	 * Constructs an instance of <code>KeySequence</code> given a list of key
	 * strokes.
	 *
	 * @param keyStrokes the list of key strokes. This list may be empty, but it
	 *                   must not be <code>null</code>. If this list is not empty,
	 *                   it must only contain instances of <code>KeyStroke</code>.
	 */
	private KeySequence(List<KeyStroke> keyStrokes) {
		this.keyStrokes = Util.safeCopy(keyStrokes, KeyStroke.class);

		for (int i = 0; i < this.keyStrokes.size() - 1; i++) {
			KeyStroke keyStroke = this.keyStrokes.get(i);

			if (!keyStroke.isComplete()) {
				throw new IllegalArgumentException();
			}
		}
	}

	@Override
	public int compareTo(Object object) {
		KeySequence castedObject = (KeySequence) object;
		return Util.compare(keyStrokes, castedObject.keyStrokes);
	}

	/**
	 * Returns whether or not this key sequence ends with the given key sequence.
	 *
	 * @param keySequence a key sequence. Must not be <code>null</code>.
	 * @param equals      whether or not an identical key sequence should be
	 *                    considered as a possible match.
	 * @return <code>true</code>, iff the given key sequence ends with this key
	 *         sequence.
	 */
	public boolean endsWith(KeySequence keySequence, boolean equals) {
		if (keySequence == null) {
			throw new NullPointerException();
		}

		return Util.endsWith(keyStrokes, keySequence.keyStrokes, equals);
	}

	@Override
	public boolean equals(Object object) {
		if (!(object instanceof KeySequence)) {
			return false;
		}

		return keyStrokes.equals(((KeySequence) object).keyStrokes);
	}

	/**
	 * Formats this key sequence into the current default look.
	 *
	 * @return A string representation for this key sequence using the default look;
	 *         never <code>null</code>.
	 */
	public String format() {
		return KeyFormatterFactory.getDefault().format(this);
	}

	/**
	 * Returns the list of key strokes for this key sequence.
	 *
	 * @return the list of key strokes keys. This list may be empty, but is
	 *         guaranteed not to be <code>null</code>. If this list is not empty, it
	 *         is guaranteed to only contain instances of <code>KeyStroke</code>.
	 */
	public List getKeyStrokes() {
		return keyStrokes;
	}

	@Override
	public int hashCode() {
		if (!hashCodeComputed) {
			hashCode = HASH_INITIAL;
			hashCode = hashCode * HASH_FACTOR + keyStrokes.hashCode();
			hashCodeComputed = true;
		}

		return hashCode;
	}

	/**
	 * Returns whether or not this key sequence is complete. Key sequences are
	 * complete iff all of their key strokes are complete.
	 *
	 * @return <code>true</code>, iff the key sequence is complete.
	 */
	public boolean isComplete() {
		return keyStrokes.isEmpty() || keyStrokes.get(keyStrokes.size() - 1).isComplete();
	}

	/**
	 * Returns whether or not this key sequence is empty. Key sequences are complete
	 * iff they have no key strokes.
	 *
	 * @return <code>true</code>, iff the key sequence is empty.
	 */
	public boolean isEmpty() {
		return keyStrokes.isEmpty();
	}

	/**
	 * Returns whether or not this key sequence starts with the given key sequence.
	 *
	 * @param keySequence a key sequence. Must not be <code>null</code>.
	 * @param equals      whether or not an identical key sequence should be
	 *                    considered as a possible match.
	 * @return <code>true</code>, iff the given key sequence starts with this key
	 *         sequence.
	 */
	public boolean startsWith(KeySequence keySequence, boolean equals) {
		if (keySequence == null) {
			throw new NullPointerException();
		}

		return Util.startsWith(keyStrokes, keySequence.keyStrokes, equals);
	}

	/**
	 * Returns the formal string representation for this key sequence.
	 *
	 * @return The formal string representation for this key sequence. Guaranteed
	 *         not to be <code>null</code>.
	 */
	@Override
	public String toString() {
		return KeyFormatterFactory.getFormalKeyFormatter().format(this);
	}
}
