1579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson/* 2579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Copyright (C) 2007 The Android Open Source Project 3579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 4579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Licensed under the Apache License, Version 2.0 (the "License"); 5579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * you may not use this file except in compliance with the License. 6579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * You may obtain a copy of the License at 7579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 8579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 9579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 10579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Unless required by applicable law or agreed to in writing, software 11579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 12579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * See the License for the specific language governing permissions and 14579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * limitations under the License. 15579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 16579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 17579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilsonpackage com.android.dx.util; 18579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 19579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson/** 20579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Interface for a binary output destination that may be augmented 21579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * with textual annotations. 22579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 23579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilsonpublic interface AnnotatedOutput 24579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson extends Output { 25579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson /** 26579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Get whether this instance will actually keep annotations. 27579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 28579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * @return {@code true} iff annotations are being kept 29579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 30579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson public boolean annotates(); 31579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 32579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson /** 33579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Get whether this instance is intended to keep verbose annotations. 34579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Annotators may use the result of calling this method to inform their 35579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * annotation activity. 36579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 37579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * @return {@code true} iff annotations are to be verbose 38579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 39579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson public boolean isVerbose(); 40579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 41579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson /** 42579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Add an annotation for the subsequent output. Any previously 43579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * open annotation will be closed by this call, and the new 44579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * annotation marks all subsequent output until another annotation 45579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * call. 46579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 47579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * @param msg {@code non-null;} the annotation message 48579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 49579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson public void annotate(String msg); 50579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 51579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson /** 52579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Add an annotation for a specified amount of subsequent 53579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * output. Any previously open annotation will be closed by this 54579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * call. If there is already pending annotation from one or more 55579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * previous calls to this method, the new call "consumes" output 56579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * after all the output covered by the previous calls. 57579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 58579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * @param amt {@code >= 0;} the amount of output for this annotation to 59579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * cover 60579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * @param msg {@code non-null;} the annotation message 61579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 62579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson public void annotate(int amt, String msg); 63579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 64579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson /** 65579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * End the most recent annotation. Subsequent output will be unannotated, 66579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * until the next call to {@link #annotate}. 67579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 68579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson public void endAnnotation(); 69579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson 70579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson /** 71579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Get the maximum width of the annotated output. This is advisory: 72579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * Implementations of this interface are encouraged to deal with too-wide 73579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * output, but annotaters are encouraged to attempt to avoid exceeding 74579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * the indicated width. 75579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * 76579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson * @return {@code >= 1;} the maximum width 77579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson */ 78579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson public int getAnnotationWidth(); 79579d7739c53a2707ad711a2d2cae46d7d782f06Jesse Wilson} 80