1/*
2 * Copyright (C) 2007 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.dx.util;
18
19/**
20 * Interface for a binary output destination that may be augmented
21 * with textual annotations.
22 */
23public interface AnnotatedOutput
24        extends Output {
25    /**
26     * Get whether this instance will actually keep annotations.
27     *
28     * @return {@code true} iff annotations are being kept
29     */
30    public boolean annotates();
31
32    /**
33     * Get whether this instance is intended to keep verbose annotations.
34     * Annotators may use the result of calling this method to inform their
35     * annotation activity.
36     *
37     * @return {@code true} iff annotations are to be verbose
38     */
39    public boolean isVerbose();
40
41    /**
42     * Add an annotation for the subsequent output. Any previously
43     * open annotation will be closed by this call, and the new
44     * annotation marks all subsequent output until another annotation
45     * call.
46     *
47     * @param msg {@code non-null;} the annotation message
48     */
49    public void annotate(String msg);
50
51    /**
52     * Add an annotation for a specified amount of subsequent
53     * output. Any previously open annotation will be closed by this
54     * call. If there is already pending annotation from one or more
55     * previous calls to this method, the new call "consumes" output
56     * after all the output covered by the previous calls.
57     *
58     * @param amt {@code >= 0;} the amount of output for this annotation to
59     * cover
60     * @param msg {@code non-null;} the annotation message
61     */
62    public void annotate(int amt, String msg);
63
64    /**
65     * End the most recent annotation. Subsequent output will be unannotated,
66     * until the next call to {@link #annotate}.
67     */
68    public void endAnnotation();
69
70    /**
71     * Get the maximum width of the annotated output. This is advisory:
72     * Implementations of this interface are encouraged to deal with too-wide
73     * output, but annotaters are encouraged to attempt to avoid exceeding
74     * the indicated width.
75     *
76     * @return {@code >= 1;} the maximum width
77     */
78    public int getAnnotationWidth();
79}
80