001/*
002  Licensed to the Apache Software Foundation (ASF) under one or more
003  contributor license agreements.  See the NOTICE file distributed with
004  this work for additional information regarding copyright ownership.
005  The ASF licenses this file to You under the Apache License, Version 2.0
006  (the "License"); you may not use this file except in compliance with
007  the License.  You may obtain a copy of the License at
008
009      https://www.apache.org/licenses/LICENSE-2.0
010
011  Unless required by applicable law or agreed to in writing, software
012  distributed under the License is distributed on an "AS IS" BASIS,
013  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014  See the License for the specific language governing permissions and
015  limitations under the License.
016 */
017package org.apache.commons.cli.help;
018
019import java.io.IOException;
020
021/**
022 * An abstract implementation of {@link HelpAppendable} that writes output to an {@link Appendable} instance.
023 * <p>
024 * This class is the superclass of all classes that filter help appendables. These appendable sit on top of an existing appendable (the <em>underlying</em>
025 * appendable) which it uses as its basic sink of data, but possibly transforming the data along the way or providing additional functionality.
026 * </p>
027 * <p>
028 * The class {@code FilterHelpAppendable} itself simply overrides all methods of {@code HelpAppendable} with versions that pass all requests to the underlying
029 * appendable. Subclasses of {@code FilterHelpAppendable} may further override some of these methods as well as provide additional methods and fields.
030 * </p>
031 * <p>
032 * <em>Implementation Note</em>: This class is similar to FilterOutputStream in relation to OutputStream. We could further split FilterHelpAppendable into a
033 * FilterAppendable but that seems like YAGNI.
034 * </p>
035 *
036 * @since 1.10.0
037 */
038public abstract class FilterHelpAppendable implements HelpAppendable {
039
040    /**
041     * The underlying appendable to be filtered.
042     */
043    protected final Appendable output;
044
045    /**
046     * Constructs an appendable filter built on top of the specified underlying appendable.
047     *
048     * @param output the underlying appendable to be assigned to the field {@code this.output} for later use, or {@code null} if this instance is to be created
049     *               without an underlying stream.
050     */
051    protected FilterHelpAppendable(final Appendable output) {
052        this.output = output;
053    }
054
055    @Override
056    public FilterHelpAppendable append(final char ch) throws IOException {
057        output.append(ch);
058        return this;
059    }
060
061    @Override
062    public FilterHelpAppendable append(final CharSequence text) throws IOException {
063        output.append(text);
064        return this;
065    }
066
067    @Override
068    public FilterHelpAppendable append(final CharSequence csq, final int start, final int end) throws IOException {
069        output.append(csq, start, end);
070        return this;
071    }
072}