lint/libs/lint-api/src/main/java/com/android/tools/lint/detector/api/Location.java - platform/tools/base - Git at Google

 /*
  * Copyright (C) 2011 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package com.android.tools.lint.detector.api;

 import com.android.annotations.NonNull;
 import com.android.annotations.Nullable;
 import com.android.ide.common.blame.SourcePosition;
 import com.android.ide.common.res2.ResourceFile;
 import com.android.ide.common.res2.ResourceItem;
 import com.google.common.annotations.Beta;

 import java.io.File;

 /**
  * Location information for a warning
  * <p/>
  * <b>NOTE: This is not a public or final API; if you rely on this be prepared
  * to adjust your code for the next tools release.</b>
  */
 @Beta
 public class Location {
     private static final String SUPER_KEYWORD = "super"; //$NON-NLS-1$

     private final File mFile;
     private final Position mStart;
     private final Position mEnd;
     private String mMessage;
     private Location mSecondary;
     private Object mClientData;

     /**
      * (Private constructor, use one of the factory methods
      * {@link Location#create(File)},
      * {@link Location#create(File, Position, Position)}, or
      * {@link Location#create(File, String, int, int)}.
      * <p>
      * Constructs a new location range for the given file, from start to end. If
      * the length of the range is not known, end may be null.
      *
      * @param file the associated file (but see the documentation for
      *            {@link #getFile()} for more information on what the file
      *            represents)
      * @param start the starting position, or null
      * @param end the ending position, or null
      */
     protected Location(@NonNull File file, @Nullable Position start, @Nullable Position end) {
         super();
         mFile = file;
         mStart = start;
         mEnd = end;
     }

     /**
      * Returns the file containing the warning. Note that the file *itself* may
      * not yet contain the error. When editing a file in the IDE for example,
      * the tool could generate warnings in the background even before the
      * document is saved. However, the file is used as a identifying token for
      * the document being edited, and the IDE integration can map this back to
      * error locations in the editor source code.
      *
      * @return the file handle for the location
      */
     @NonNull
     public File getFile() {
         return mFile;
     }

     /**
      * The start position of the range
      *
      * @return the start position of the range, or null
      */
     @Nullable
     public Position getStart() {
         return mStart;
     }

     /**
      * The end position of the range
      *
      * @return the start position of the range, may be null for an empty range
      */
     @Nullable
     public Position getEnd() {
         return mEnd;
     }

     /**
      * Returns a secondary location associated with this location (if
      * applicable), or null.
      *
      * @return a secondary location or null
      */
     @Nullable
     public Location getSecondary() {
         return mSecondary;
     }

     /**
      * Sets a secondary location for this location.
      *
      * @param secondary a secondary location associated with this location
      */
     public void setSecondary(@Nullable Location secondary) {
         mSecondary = secondary;
     }

     /**
      * Sets a custom message for this location. This is typically used for
      * secondary locations, to describe the significance of this alternate
      * location. For example, for a duplicate id warning, the primary location
      * might say "This is a duplicate id", pointing to the second occurrence of
      * id declaration, and then the secondary location could point to the
      * original declaration with the custom message "Originally defined here".
      *
      * @param message the message to apply to this location
      */
     public void setMessage(@NonNull String message) {
         mMessage = message;
     }

     /**
      * Returns the custom message for this location, if any. This is typically
      * used for secondary locations, to describe the significance of this
      * alternate location. For example, for a duplicate id warning, the primary
      * location might say "This is a duplicate id", pointing to the second
      * occurrence of id declaration, and then the secondary location could point
      * to the original declaration with the custom message
      * "Originally defined here".
      *
      * @return the custom message for this location, or null
      */
     @Nullable
     public String getMessage() {
         return mMessage;
     }

     /**
      * Sets the client data associated with this location. This is an optional
      * field which can be used by the creator of the {@link Location} to store
      * temporary state associated with the location.
      *
      * @param clientData the data to store with this location
      */
     public void setClientData(@Nullable Object clientData) {
         mClientData = clientData;
     }

     /**
      * Returns the client data associated with this location - an optional field
      * which can be used by the creator of the {@link Location} to store
      * temporary state associated with the location.
      *
      * @return the data associated with this location
      */
     @Nullable
     public Object getClientData() {
         return mClientData;
     }

     @Override
     public String toString() {
         return "Location [file=" + mFile + ", start=" + mStart + ", end=" + mEnd + ", message="
                 + mMessage + ']';
     }

     /**
      * Creates a new location for the given file
      *
      * @param file the file to create a location for
      * @return a new location
      */
     @NonNull
     public static Location create(@NonNull File file) {
         return new Location(file, null /*start*/, null /*end*/);
     }

     /**
      * Creates a new location for the given file and SourcePosition.
      *
      * @param file the file containing the positions
      * @param position the source position
      * @return a new location
      */
     @NonNull
     public static Location create(
             @NonNull File file,
             @NonNull SourcePosition position) {
         if (position.equals(SourcePosition.UNKNOWN)) {
             return new Location(file, null /*start*/, null /*end*/);
         }
         return new Location(file,
                 new DefaultPosition(
                         position.getStartLine(),
                         position.getStartColumn(),
                         position.getStartOffset()),
                 new DefaultPosition(
                         position.getEndLine(),
                         position.getEndColumn(),
                         position.getEndOffset()));
     }

     /**
      * Creates a new location for the given file and starting and ending
      * positions.
      *
      * @param file the file containing the positions
      * @param start the starting position
      * @param end the ending position
      * @return a new location
      */
     @NonNull
     public static Location create(
             @NonNull File file,
             @NonNull Position start,
             @Nullable Position end) {
         return new Location(file, start, end);
     }

     /**
      * Creates a new location for the given file, with the given contents, for
      * the given offset range.
      *
      * @param file the file containing the location
      * @param contents the current contents of the file
      * @param startOffset the starting offset
      * @param endOffset the ending offset
      * @return a new location
      */
     @NonNull
     public static Location create(
             @NonNull File file,
             @Nullable String contents,
             int startOffset,
             int endOffset) {
         if (startOffset < 0 || endOffset < startOffset) {
             throw new IllegalArgumentException("Invalid offsets");
         }

         if (contents == null) {
             return new Location(file,
                     new DefaultPosition(-1, -1, startOffset),
                     new DefaultPosition(-1, -1, endOffset));
         }

         int size = contents.length();
         endOffset = Math.min(endOffset, size);
         startOffset = Math.min(startOffset, endOffset);
         Position start = null;
         int line = 0;
         int lineOffset = 0;
         char prev = 0;
         for (int offset = 0; offset <= size; offset++) {
             if (offset == startOffset) {
                 start = new DefaultPosition(line, offset - lineOffset, offset);
             }
             if (offset == endOffset) {
                 Position end = new DefaultPosition(line, offset - lineOffset, offset);
                 return new Location(file, start, end);
             }
             char c = contents.charAt(offset);
             if (c == '\n') {
                 lineOffset = offset + 1;
                 if (prev != '\r') {
                     line++;
                 }
             } else if (c == '\r') {
                 line++;
                 lineOffset = offset + 1;
             }
             prev = c;
         }
         return create(file);
     }

     /**
      * Creates a new location for the given file, with the given contents, for
      * the given line number.
      *
      * @param file the file containing the location
      * @param contents the current contents of the file
      * @param line the line number (0-based) for the position
      * @return a new location
      */
     @NonNull
     public static Location create(@NonNull File file, @NonNull String contents, int line) {
         return create(file, contents, line, null, null, null);
     }

     /**
      * Creates a new location for the given file, with the given contents, for
      * the given line number.
      *
      * @param file the file containing the location
      * @param contents the current contents of the file
      * @param line the line number (0-based) for the position
      * @param patternStart an optional pattern to search for from the line
      *            match; if found, adjust the column and offsets to begin at the
      *            pattern start
      * @param patternEnd an optional pattern to search for behind the start
      *            pattern; if found, adjust the end offset to match the end of
      *            the pattern
      * @param hints optional additional information regarding the pattern search
      * @return a new location
      */
     @NonNull
     public static Location create(@NonNull File file, @NonNull String contents, int line,
             @Nullable String patternStart, @Nullable String patternEnd,
             @Nullable SearchHints hints) {
         int currentLine = 0;
         int offset = 0;
         while (currentLine < line) {
             offset = contents.indexOf('\n', offset);
             if (offset == -1) {
                 return create(file);
             }
             currentLine++;
             offset++;
         }

         if (line == currentLine) {
             if (patternStart != null) {
                 SearchDirection direction = SearchDirection.NEAREST;
                 if (hints != null) {
                     direction = hints.mDirection;
                 }

                 int index;
                 if (direction == SearchDirection.BACKWARD) {
                     index = findPreviousMatch(contents, offset, patternStart, hints);
                     line = adjustLine(contents, line, offset, index);
                 } else if (direction == SearchDirection.EOL_BACKWARD) {
                     int lineEnd = contents.indexOf('\n', offset);
                     if (lineEnd == -1) {
                         lineEnd = contents.length();
                     }

                     index = findPreviousMatch(contents, lineEnd, patternStart, hints);
                     line = adjustLine(contents, line, offset, index);
                 } else if (direction == SearchDirection.FORWARD) {
                     index = findNextMatch(contents, offset, patternStart, hints);
                     line = adjustLine(contents, line, offset, index);
                 } else {
                     assert direction == SearchDirection.NEAREST;

                     int before = findPreviousMatch(contents, offset, patternStart, hints);
                     int after = findNextMatch(contents, offset, patternStart, hints);

                     if (before == -1) {
                         index = after;
                         line = adjustLine(contents, line, offset, index);
                     } else if (after == -1) {
                         index = before;
                         line = adjustLine(contents, line, offset, index);
                     } else if (offset - before < after - offset) {
                         index = before;
                         line = adjustLine(contents, line, offset, index);
                     } else {
                         index = after;
                         line = adjustLine(contents, line, offset, index);
                     }
                 }

                 if (index != -1) {
                     int lineStart = contents.lastIndexOf('\n', index);
                     if (lineStart == -1) {
                         lineStart = 0;
                     } else {
                         lineStart++; // was pointing to the previous line's CR, not line start
                     }
                     int column = index - lineStart;
                     if (patternEnd != null) {
                         int end = contents.indexOf(patternEnd, offset + patternStart.length());
                         if (end != -1) {
                             return new Location(file, new DefaultPosition(line, column, index),
                                     new DefaultPosition(line, -1, end + patternEnd.length()));
                         }
                     } else if (hints != null && (hints.isJavaSymbol() || hints.isWholeWord())) {
                         if (hints.isConstructor() && contents.startsWith(SUPER_KEYWORD, index)) {
                             patternStart = SUPER_KEYWORD;
                         }
                         return new Location(file, new DefaultPosition(line, column, index),
                                 new DefaultPosition(line, column + patternStart.length(),
                                         index + patternStart.length()));
                     }
                     return new Location(file, new DefaultPosition(line, column, index),
                             new DefaultPosition(line, column, index + patternStart.length()));
                 }
             }

             Position position = new DefaultPosition(line, -1, offset);
             return new Location(file, position, position);
         }

         return create(file);
     }

     private static int findPreviousMatch(@NonNull String contents, int offset, String pattern,
             @Nullable SearchHints hints) {
         while (true) {
             int index = contents.lastIndexOf(pattern, offset);
             if (index == -1) {
                 return -1;
             } else {
                 if (isMatch(contents, index, pattern, hints)) {
                     return index;
                 } else {
                     offset = index - pattern.length();
                 }
             }
         }
     }

     private static int findNextMatch(@NonNull String contents, int offset, String pattern,
             @Nullable SearchHints hints) {
         int constructorIndex = -1;
         if (hints != null && hints.isConstructor()) {
             // Special condition: See if the call is referenced as "super" instead.
             assert hints.isWholeWord();
             int index = contents.indexOf(SUPER_KEYWORD, offset);
             if (index != -1 && isMatch(contents, index, SUPER_KEYWORD, hints)) {
                 constructorIndex = index;
             }
         }

         while (true) {
             int index = contents.indexOf(pattern, offset);
             if (index == -1) {
                 return constructorIndex;
             } else {
                 if (isMatch(contents, index, pattern, hints)) {
                     if (constructorIndex != -1) {
                         return Math.min(constructorIndex, index);
                     }
                     return index;
                 } else {
                     offset = index + pattern.length();
                 }
             }
         }
     }

     private static boolean isMatch(@NonNull String contents, int offset, String pattern,
             @Nullable SearchHints hints) {
         if (!contents.startsWith(pattern, offset)) {
             return false;
         }

         if (hints != null) {
             char prevChar = offset > 0 ? contents.charAt(offset - 1) : 0;
             int lastIndex = offset + pattern.length() - 1;
             char nextChar = lastIndex < contents.length() - 1 ? contents.charAt(lastIndex + 1) : 0;

             if (hints.isWholeWord() && (Character.isLetter(prevChar)
                     || Character.isLetter(nextChar))) {
                 return false;

             }

             if (hints.isJavaSymbol()) {
                 if (Character.isJavaIdentifierPart(prevChar)
                         || Character.isJavaIdentifierPart(nextChar)) {
                     return false;
                 }

                 if (prevChar == '"') {
                     return false;
                 }

                 // TODO: Additional validation to see if we're in a comment, string, etc.
                 // This will require lexing from the beginning of the buffer.
             }

             if (hints.isConstructor() && SUPER_KEYWORD.equals(pattern)) {
                 // Only looking for super(), not super.x, so assert that the next
                 // non-space character is (
                 int index = lastIndex + 1;
                 while (index < contents.length() - 1) {
                     char c = contents.charAt(index);
                     if (c == '(') {
                         break;
                     } else if (!Character.isWhitespace(c)) {
                         return false;
                     }
                     index++;
                 }
             }
         }

         return true;
     }

     private static int adjustLine(String doc, int line, int offset, int newOffset) {
         if (newOffset == -1) {
             return line;
         }

         if (newOffset < offset) {
             return line - countLines(doc, newOffset, offset);
         } else {
             return line + countLines(doc, offset, newOffset);
         }
     }

     private static int countLines(String doc, int start, int end) {
         int lines = 0;
         for (int offset = start; offset < end; offset++) {
             char c = doc.charAt(offset);
             if (c == '\n') {
                 lines++;
             }
         }

         return lines;
     }

     /**
      * Reverses the secondary location list initiated by the given location
      *
      * @param location the first location in the list
      * @return the first location in the reversed list
      */
     public static Location reverse(@NonNull Location location) {
         Location next = location.getSecondary();
         location.setSecondary(null);
         while (next != null) {
             Location nextNext = next.getSecondary();
             next.setSecondary(location);
             location = next;
             next = nextNext;
         }

         return location;
     }

     /**
      * A {@link Handle} is a reference to a location. The point of a location
      * handle is to be able to create them cheaply, and then resolve them into
      * actual locations later (if needed). This makes it possible to for example
      * delay looking up line numbers, for locations that are offset based.
      */
     public interface Handle {
         /**
          * Compute a full location for the given handle
          *
          * @return create a location for this handle
          */
         @NonNull
         Location resolve();

         /**
          * Sets the client data associated with this location. This is an optional
          * field which can be used by the creator of the {@link Location} to store
          * temporary state associated with the location.
          *
          * @param clientData the data to store with this location
          */
         void setClientData(@Nullable Object clientData);

         /**
          * Returns the client data associated with this location - an optional field
          * which can be used by the creator of the {@link Location} to store
          * temporary state associated with the location.
          *
          * @return the data associated with this location
          */
         @Nullable
         Object getClientData();
     }

     /** A default {@link Handle} implementation for simple file offsets */
     public static class DefaultLocationHandle implements Handle {
         private final File mFile;
         private final String mContents;
         private final int mStartOffset;
         private final int mEndOffset;
         private Object mClientData;

         /**
          * Constructs a new {@link DefaultLocationHandle}
          *
          * @param context the context pointing to the file and its contents
          * @param startOffset the start offset within the file
          * @param endOffset the end offset within the file
          */
         public DefaultLocationHandle(@NonNull Context context, int startOffset, int endOffset) {
             mFile = context.file;
             mContents = context.getContents();
             mStartOffset = startOffset;
             mEndOffset = endOffset;
         }

         @Override
         @NonNull
         public Location resolve() {
             return create(mFile, mContents, mStartOffset, mEndOffset);
         }

         @Override
         public void setClientData(@Nullable Object clientData) {
             mClientData = clientData;
         }

         @Override
         @Nullable
         public Object getClientData() {
             return mClientData;
         }
     }

     public static class ResourceItemHandle implements Handle {
         private final ResourceItem mItem;

         public ResourceItemHandle(@NonNull ResourceItem item) {
             mItem = item;
         }
         @NonNull
         @Override
         public Location resolve() {
             // TODO: Look up the exact item location more
             // closely
             ResourceFile source = mItem.getSource();
             assert source != null : mItem;
             return create(source.getFile());
         }

         @Override
         public void setClientData(@Nullable Object clientData) {
         }

         @Nullable
         @Override
         public Object getClientData() {
             return null;
         }
     }

     /**
      * Whether to look forwards, or backwards, or in both directions, when
      * searching for a pattern in the source code to determine the right
      * position range for a given symbol.
      * <p>
      * When dealing with bytecode for example, there are only line number entries
      * within method bodies, so when searching for the method declaration, we should only
      * search backwards from the first line entry in the method.
      */
     public enum SearchDirection {
         /** Only search forwards */
         FORWARD,

         /** Only search backwards */
         BACKWARD,

         /** Search backwards from the current end of line (normally it's the beginning of
          * the current line) */
         EOL_BACKWARD,

         /**
          * Search both forwards and backwards from the given line, and prefer
          * the match that is closest
          */
         NEAREST,
     }

     /**
      * Extra information pertaining to finding a symbol in a source buffer,
      * used by {@link Location#create(File, String, int, String, String, SearchHints)}
      */
     public static class SearchHints {
         /**
          * the direction to search for the nearest match in (provided
          * {@code patternStart} is non null)
          */
         @NonNull
         private final SearchDirection mDirection;

         /** Whether the matched pattern should be a whole word */
         private boolean mWholeWord;

         /**
          * Whether the matched pattern should be a Java symbol (so for example,
          * a match inside a comment or string literal should not be used)
          */
         private boolean mJavaSymbol;

         /**
          * Whether the matched pattern corresponds to a constructor; if so, look for
          * some other possible source aliases too, such as "super".
          */
         private boolean mConstructor;

         private SearchHints(@NonNull SearchDirection direction) {
             super();
             mDirection = direction;
         }

         /**
          * Constructs a new {@link SearchHints} object
          *
          * @param direction the direction to search in for the pattern
          * @return a new @link SearchHints} object
          */
         @NonNull
         public static SearchHints create(@NonNull SearchDirection direction) {
             return new SearchHints(direction);
         }

         /**
          * Indicates that pattern matches should apply to whole words only

          * @return this, for constructor chaining
          */
         @NonNull
         public SearchHints matchWholeWord() {
             mWholeWord = true;

             return this;
         }

         /** @return true if the pattern match should be for whole words only */
         public boolean isWholeWord() {
             return mWholeWord;
         }

         /**
          * Indicates that pattern matches should apply to Java symbols only
          *
          * @return this, for constructor chaining
          */
         @NonNull
         public SearchHints matchJavaSymbol() {
             mJavaSymbol = true;
             mWholeWord = true;

             return this;
         }

         /** @return true if the pattern match should be for Java symbols only */
         public boolean isJavaSymbol() {
             return mJavaSymbol;
         }

         /**
          * Indicates that pattern matches should apply to constructors. If so, look for
          * some other possible source aliases too, such as "super".
          *
          * @return this, for constructor chaining
          */
         @NonNull
         public SearchHints matchConstructor() {
             mConstructor = true;
             mWholeWord = true;
             mJavaSymbol = true;

             return this;
         }

         /** @return true if the pattern match should be for a constructor */
         public boolean isConstructor() {
             return mConstructor;
         }
     }
 }
	/*
	* Copyright (C) 2011 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package com.android.tools.lint.detector.api;

	import com.android.annotations.NonNull;
	import com.android.annotations.Nullable;
	import com.android.ide.common.blame.SourcePosition;
	import com.android.ide.common.res2.ResourceFile;
	import com.android.ide.common.res2.ResourceItem;
	import com.google.common.annotations.Beta;

	import java.io.File;

	/**
	* Location information for a warning
	* <p/>
	* <b>NOTE: This is not a public or final API; if you rely on this be prepared
	* to adjust your code for the next tools release.</b>
	*/
	@Beta
	public class Location {
	private static final String SUPER_KEYWORD = "super"; //$NON-NLS-1$

	private final File mFile;
	private final Position mStart;
	private final Position mEnd;
	private String mMessage;
	private Location mSecondary;
	private Object mClientData;

	/**
	* (Private constructor, use one of the factory methods
	* {@link Location#create(File)},
	* {@link Location#create(File, Position, Position)}, or
	* {@link Location#create(File, String, int, int)}.
	* <p>
	* Constructs a new location range for the given file, from start to end. If
	* the length of the range is not known, end may be null.
	*
	* @param file the associated file (but see the documentation for
	* {@link #getFile()} for more information on what the file
	* represents)
	* @param start the starting position, or null
	* @param end the ending position, or null
	*/
	protected Location(@NonNull File file, @Nullable Position start, @Nullable Position end) {
	super();
	mFile = file;
	mStart = start;
	mEnd = end;
	}

	/**
	* Returns the file containing the warning. Note that the file itself may
	* not yet contain the error. When editing a file in the IDE for example,
	* the tool could generate warnings in the background even before the
	* document is saved. However, the file is used as a identifying token for
	* the document being edited, and the IDE integration can map this back to
	* error locations in the editor source code.
	*
	* @return the file handle for the location
	*/
	@NonNull
	public File getFile() {
	return mFile;
	}

	/**
	* The start position of the range
	*
	* @return the start position of the range, or null
	*/
	@Nullable
	public Position getStart() {
	return mStart;
	}

	/**
	* The end position of the range
	*
	* @return the start position of the range, may be null for an empty range
	*/
	@Nullable
	public Position getEnd() {
	return mEnd;
	}

	/**
	* Returns a secondary location associated with this location (if
	* applicable), or null.
	*
	* @return a secondary location or null
	*/
	@Nullable
	public Location getSecondary() {
	return mSecondary;
	}

	/**
	* Sets a secondary location for this location.
	*
	* @param secondary a secondary location associated with this location
	*/
	public void setSecondary(@Nullable Location secondary) {
	mSecondary = secondary;
	}

	/**
	* Sets a custom message for this location. This is typically used for
	* secondary locations, to describe the significance of this alternate
	* location. For example, for a duplicate id warning, the primary location
	* might say "This is a duplicate id", pointing to the second occurrence of
	* id declaration, and then the secondary location could point to the
	* original declaration with the custom message "Originally defined here".
	*
	* @param message the message to apply to this location
	*/
	public void setMessage(@NonNull String message) {
	mMessage = message;
	}

	/**
	* Returns the custom message for this location, if any. This is typically
	* used for secondary locations, to describe the significance of this
	* alternate location. For example, for a duplicate id warning, the primary
	* location might say "This is a duplicate id", pointing to the second
	* occurrence of id declaration, and then the secondary location could point
	* to the original declaration with the custom message
	* "Originally defined here".
	*
	* @return the custom message for this location, or null
	*/
	@Nullable
	public String getMessage() {
	return mMessage;
	}

	/**
	* Sets the client data associated with this location. This is an optional
	* field which can be used by the creator of the {@link Location} to store
	* temporary state associated with the location.
	*
	* @param clientData the data to store with this location
	*/
	public void setClientData(@Nullable Object clientData) {
	mClientData = clientData;
	}

	/**
	* Returns the client data associated with this location - an optional field
	* which can be used by the creator of the {@link Location} to store
	* temporary state associated with the location.
	*
	* @return the data associated with this location
	*/
	@Nullable
	public Object getClientData() {
	return mClientData;
	}

	@Override
	public String toString() {
	return "Location [file=" + mFile + ", start=" + mStart + ", end=" + mEnd + ", message="
	+ mMessage + ']';
	}

	/**
	* Creates a new location for the given file
	*
	* @param file the file to create a location for
	* @return a new location
	*/
	@NonNull
	public static Location create(@NonNull File file) {
	return new Location(file, null /start/, null /end/);
	}

	/**
	* Creates a new location for the given file and SourcePosition.
	*
	* @param file the file containing the positions
	* @param position the source position
	* @return a new location
	*/
	@NonNull
	public static Location create(
	@NonNull File file,
	@NonNull SourcePosition position) {
	if (position.equals(SourcePosition.UNKNOWN)) {
	return new Location(file, null /start/, null /end/);
	}
	return new Location(file,
	new DefaultPosition(
	position.getStartLine(),
	position.getStartColumn(),
	position.getStartOffset()),
	new DefaultPosition(
	position.getEndLine(),
	position.getEndColumn(),
	position.getEndOffset()));
	}

	/**
	* Creates a new location for the given file and starting and ending
	* positions.
	*
	* @param file the file containing the positions
	* @param start the starting position
	* @param end the ending position
	* @return a new location
	*/
	@NonNull
	public static Location create(
	@NonNull File file,
	@NonNull Position start,
	@Nullable Position end) {
	return new Location(file, start, end);
	}

	/**
	* Creates a new location for the given file, with the given contents, for
	* the given offset range.
	*
	* @param file the file containing the location
	* @param contents the current contents of the file
	* @param startOffset the starting offset
	* @param endOffset the ending offset
	* @return a new location
	*/
	@NonNull
	public static Location create(
	@NonNull File file,
	@Nullable String contents,
	int startOffset,
	int endOffset) {
	if (startOffset < 0 \|\| endOffset < startOffset) {
	throw new IllegalArgumentException("Invalid offsets");
	}

	if (contents == null) {
	return new Location(file,
	new DefaultPosition(-1, -1, startOffset),
	new DefaultPosition(-1, -1, endOffset));
	}

	int size = contents.length();
	endOffset = Math.min(endOffset, size);
	startOffset = Math.min(startOffset, endOffset);
	Position start = null;
	int line = 0;
	int lineOffset = 0;
	char prev = 0;
	for (int offset = 0; offset <= size; offset++) {
	if (offset == startOffset) {
	start = new DefaultPosition(line, offset - lineOffset, offset);
	}
	if (offset == endOffset) {
	Position end = new DefaultPosition(line, offset - lineOffset, offset);
	return new Location(file, start, end);
	}
	char c = contents.charAt(offset);
	if (c == '\n') {
	lineOffset = offset + 1;
	if (prev != '\r') {
	line++;
	}
	} else if (c == '\r') {
	line++;
	lineOffset = offset + 1;
	}
	prev = c;
	}
	return create(file);
	}

	/**
	* Creates a new location for the given file, with the given contents, for
	* the given line number.
	*
	* @param file the file containing the location
	* @param contents the current contents of the file
	* @param line the line number (0-based) for the position
	* @return a new location
	*/
	@NonNull
	public static Location create(@NonNull File file, @NonNull String contents, int line) {
	return create(file, contents, line, null, null, null);
	}

	/**
	* Creates a new location for the given file, with the given contents, for
	* the given line number.
	*
	* @param file the file containing the location
	* @param contents the current contents of the file
	* @param line the line number (0-based) for the position
	* @param patternStart an optional pattern to search for from the line
	* match; if found, adjust the column and offsets to begin at the
	* pattern start
	* @param patternEnd an optional pattern to search for behind the start
	* pattern; if found, adjust the end offset to match the end of
	* the pattern
	* @param hints optional additional information regarding the pattern search
	* @return a new location
	*/
	@NonNull
	public static Location create(@NonNull File file, @NonNull String contents, int line,
	@Nullable String patternStart, @Nullable String patternEnd,
	@Nullable SearchHints hints) {
	int currentLine = 0;
	int offset = 0;
	while (currentLine < line) {
	offset = contents.indexOf('\n', offset);
	if (offset == -1) {
	return create(file);
	}
	currentLine++;
	offset++;
	}

	if (line == currentLine) {
	if (patternStart != null) {
	SearchDirection direction = SearchDirection.NEAREST;
	if (hints != null) {
	direction = hints.mDirection;
	}

	int index;
	if (direction == SearchDirection.BACKWARD) {
	index = findPreviousMatch(contents, offset, patternStart, hints);
	line = adjustLine(contents, line, offset, index);
	} else if (direction == SearchDirection.EOL_BACKWARD) {
	int lineEnd = contents.indexOf('\n', offset);
	if (lineEnd == -1) {
	lineEnd = contents.length();
	}

	index = findPreviousMatch(contents, lineEnd, patternStart, hints);
	line = adjustLine(contents, line, offset, index);
	} else if (direction == SearchDirection.FORWARD) {
	index = findNextMatch(contents, offset, patternStart, hints);
	line = adjustLine(contents, line, offset, index);
	} else {
	assert direction == SearchDirection.NEAREST;

	int before = findPreviousMatch(contents, offset, patternStart, hints);
	int after = findNextMatch(contents, offset, patternStart, hints);

	if (before == -1) {
	index = after;
	line = adjustLine(contents, line, offset, index);
	} else if (after == -1) {
	index = before;
	line = adjustLine(contents, line, offset, index);
	} else if (offset - before < after - offset) {
	index = before;
	line = adjustLine(contents, line, offset, index);
	} else {
	index = after;
	line = adjustLine(contents, line, offset, index);
	}
	}

	if (index != -1) {
	int lineStart = contents.lastIndexOf('\n', index);
	if (lineStart == -1) {
	lineStart = 0;
	} else {
	lineStart++; // was pointing to the previous line's CR, not line start
	}
	int column = index - lineStart;
	if (patternEnd != null) {
	int end = contents.indexOf(patternEnd, offset + patternStart.length());
	if (end != -1) {
	return new Location(file, new DefaultPosition(line, column, index),
	new DefaultPosition(line, -1, end + patternEnd.length()));
	}
	} else if (hints != null && (hints.isJavaSymbol() \|\| hints.isWholeWord())) {
	if (hints.isConstructor() && contents.startsWith(SUPER_KEYWORD, index)) {
	patternStart = SUPER_KEYWORD;
	}
	return new Location(file, new DefaultPosition(line, column, index),
	new DefaultPosition(line, column + patternStart.length(),
	index + patternStart.length()));
	}
	return new Location(file, new DefaultPosition(line, column, index),
	new DefaultPosition(line, column, index + patternStart.length()));
	}
	}

	Position position = new DefaultPosition(line, -1, offset);
	return new Location(file, position, position);
	}

	return create(file);
	}

	private static int findPreviousMatch(@NonNull String contents, int offset, String pattern,
	@Nullable SearchHints hints) {
	while (true) {
	int index = contents.lastIndexOf(pattern, offset);
	if (index == -1) {
	return -1;
	} else {
	if (isMatch(contents, index, pattern, hints)) {
	return index;
	} else {
	offset = index - pattern.length();
	}
	}
	}
	}

	private static int findNextMatch(@NonNull String contents, int offset, String pattern,
	@Nullable SearchHints hints) {
	int constructorIndex = -1;
	if (hints != null && hints.isConstructor()) {
	// Special condition: See if the call is referenced as "super" instead.
	assert hints.isWholeWord();
	int index = contents.indexOf(SUPER_KEYWORD, offset);
	if (index != -1 && isMatch(contents, index, SUPER_KEYWORD, hints)) {
	constructorIndex = index;
	}
	}

	while (true) {
	int index = contents.indexOf(pattern, offset);
	if (index == -1) {
	return constructorIndex;
	} else {
	if (isMatch(contents, index, pattern, hints)) {
	if (constructorIndex != -1) {
	return Math.min(constructorIndex, index);
	}
	return index;
	} else {
	offset = index + pattern.length();
	}
	}
	}
	}

	private static boolean isMatch(@NonNull String contents, int offset, String pattern,
	@Nullable SearchHints hints) {
	if (!contents.startsWith(pattern, offset)) {
	return false;
	}

	if (hints != null) {
	char prevChar = offset > 0 ? contents.charAt(offset - 1) : 0;
	int lastIndex = offset + pattern.length() - 1;
	char nextChar = lastIndex < contents.length() - 1 ? contents.charAt(lastIndex + 1) : 0;

	if (hints.isWholeWord() && (Character.isLetter(prevChar)
	\|\| Character.isLetter(nextChar))) {
	return false;

	}

	if (hints.isJavaSymbol()) {
	if (Character.isJavaIdentifierPart(prevChar)
	\|\| Character.isJavaIdentifierPart(nextChar)) {
	return false;
	}

	if (prevChar == '"') {
	return false;
	}

	// TODO: Additional validation to see if we're in a comment, string, etc.
	// This will require lexing from the beginning of the buffer.
	}

	if (hints.isConstructor() && SUPER_KEYWORD.equals(pattern)) {
	// Only looking for super(), not super.x, so assert that the next
	// non-space character is (
	int index = lastIndex + 1;
	while (index < contents.length() - 1) {
	char c = contents.charAt(index);
	if (c == '(') {
	break;
	} else if (!Character.isWhitespace(c)) {
	return false;
	}
	index++;
	}
	}
	}

	return true;
	}

	private static int adjustLine(String doc, int line, int offset, int newOffset) {
	if (newOffset == -1) {
	return line;
	}

	if (newOffset < offset) {
	return line - countLines(doc, newOffset, offset);
	} else {
	return line + countLines(doc, offset, newOffset);
	}
	}

	private static int countLines(String doc, int start, int end) {
	int lines = 0;
	for (int offset = start; offset < end; offset++) {
	char c = doc.charAt(offset);
	if (c == '\n') {
	lines++;
	}
	}

	return lines;
	}

	/**
	* Reverses the secondary location list initiated by the given location
	*
	* @param location the first location in the list
	* @return the first location in the reversed list
	*/
	public static Location reverse(@NonNull Location location) {
	Location next = location.getSecondary();
	location.setSecondary(null);
	while (next != null) {
	Location nextNext = next.getSecondary();
	next.setSecondary(location);
	location = next;
	next = nextNext;
	}

	return location;
	}

	/**
	* A {@link Handle} is a reference to a location. The point of a location
	* handle is to be able to create them cheaply, and then resolve them into
	* actual locations later (if needed). This makes it possible to for example
	* delay looking up line numbers, for locations that are offset based.
	*/
	public interface Handle {
	/**
	* Compute a full location for the given handle
	*
	* @return create a location for this handle
	*/
	@NonNull
	Location resolve();

	/**
	* Sets the client data associated with this location. This is an optional
	* field which can be used by the creator of the {@link Location} to store
	* temporary state associated with the location.
	*
	* @param clientData the data to store with this location
	*/
	void setClientData(@Nullable Object clientData);

	/**
	* Returns the client data associated with this location - an optional field
	* which can be used by the creator of the {@link Location} to store
	* temporary state associated with the location.
	*
	* @return the data associated with this location
	*/
	@Nullable
	Object getClientData();
	}

	/** A default {@link Handle} implementation for simple file offsets */
	public static class DefaultLocationHandle implements Handle {
	private final File mFile;
	private final String mContents;
	private final int mStartOffset;
	private final int mEndOffset;
	private Object mClientData;

	/**
	* Constructs a new {@link DefaultLocationHandle}
	*
	* @param context the context pointing to the file and its contents
	* @param startOffset the start offset within the file
	* @param endOffset the end offset within the file
	*/
	public DefaultLocationHandle(@NonNull Context context, int startOffset, int endOffset) {
	mFile = context.file;
	mContents = context.getContents();
	mStartOffset = startOffset;
	mEndOffset = endOffset;
	}

	@Override
	@NonNull
	public Location resolve() {
	return create(mFile, mContents, mStartOffset, mEndOffset);
	}

	@Override
	public void setClientData(@Nullable Object clientData) {
	mClientData = clientData;
	}

	@Override
	@Nullable
	public Object getClientData() {
	return mClientData;
	}
	}

	public static class ResourceItemHandle implements Handle {
	private final ResourceItem mItem;

	public ResourceItemHandle(@NonNull ResourceItem item) {
	mItem = item;
	}
	@NonNull
	@Override
	public Location resolve() {
	// TODO: Look up the exact item location more
	// closely
	ResourceFile source = mItem.getSource();
	assert source != null : mItem;
	return create(source.getFile());
	}

	@Override
	public void setClientData(@Nullable Object clientData) {
	}

	@Nullable
	@Override
	public Object getClientData() {
	return null;
	}
	}

	/**
	* Whether to look forwards, or backwards, or in both directions, when
	* searching for a pattern in the source code to determine the right
	* position range for a given symbol.
	* <p>
	* When dealing with bytecode for example, there are only line number entries
	* within method bodies, so when searching for the method declaration, we should only
	* search backwards from the first line entry in the method.
	*/
	public enum SearchDirection {
	/** Only search forwards */
	FORWARD,

	/** Only search backwards */
	BACKWARD,

	/** Search backwards from the current end of line (normally it's the beginning of
	* the current line) */
	EOL_BACKWARD,

	/**
	* Search both forwards and backwards from the given line, and prefer
	* the match that is closest
	*/
	NEAREST,
	}

	/**
	* Extra information pertaining to finding a symbol in a source buffer,
	* used by {@link Location#create(File, String, int, String, String, SearchHints)}
	*/
	public static class SearchHints {
	/**
	* the direction to search for the nearest match in (provided
	* {@code patternStart} is non null)
	*/
	@NonNull
	private final SearchDirection mDirection;

	/** Whether the matched pattern should be a whole word */
	private boolean mWholeWord;

	/**
	* Whether the matched pattern should be a Java symbol (so for example,
	* a match inside a comment or string literal should not be used)
	*/
	private boolean mJavaSymbol;

	/**
	* Whether the matched pattern corresponds to a constructor; if so, look for
	* some other possible source aliases too, such as "super".
	*/
	private boolean mConstructor;

	private SearchHints(@NonNull SearchDirection direction) {
	super();
	mDirection = direction;
	}

	/**
	* Constructs a new {@link SearchHints} object
	*
	* @param direction the direction to search in for the pattern
	* @return a new @link SearchHints} object
	*/
	@NonNull
	public static SearchHints create(@NonNull SearchDirection direction) {
	return new SearchHints(direction);
	}

	/**
	* Indicates that pattern matches should apply to whole words only

	* @return this, for constructor chaining
	*/
	@NonNull
	public SearchHints matchWholeWord() {
	mWholeWord = true;

	return this;
	}

	/** @return true if the pattern match should be for whole words only */
	public boolean isWholeWord() {
	return mWholeWord;
	}

	/**
	* Indicates that pattern matches should apply to Java symbols only
	*
	* @return this, for constructor chaining
	*/
	@NonNull
	public SearchHints matchJavaSymbol() {
	mJavaSymbol = true;
	mWholeWord = true;

	return this;
	}

	/** @return true if the pattern match should be for Java symbols only */
	public boolean isJavaSymbol() {
	return mJavaSymbol;
	}

	/**
	* Indicates that pattern matches should apply to constructors. If so, look for
	* some other possible source aliases too, such as "super".
	*
	* @return this, for constructor chaining
	*/
	@NonNull
	public SearchHints matchConstructor() {
	mConstructor = true;
	mWholeWord = true;
	mJavaSymbol = true;

	return this;
	}

	/** @return true if the pattern match should be for a constructor */
	public boolean isConstructor() {
	return mConstructor;
	}
	}
	}