src/chrome/browser/autocomplete/autocomplete_input.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROME_BROWSER_AUTOCOMPLETE_AUTOCOMPLETE_INPUT_H_
   6 #define CHROME_BROWSER_AUTOCOMPLETE_AUTOCOMPLETE_INPUT_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/gtest_prod_util.h"
  12 #include "base/strings/string16.h"
  13 #include "url/gurl.h"
  14 #include "url/url_parse.h"
  15
  16 // The user input for an autocomplete query.  Allows copying.
  17 class AutocompleteInput {
  18  public:
  19   // Note that the type below may be misleading.  For example, "http:/" alone
  20   // cannot be opened as a URL, so it is marked as a QUERY; yet the user
  21   // probably intends to type more and have it eventually become a URL, so we
  22   // need to make sure we still run it through inline autocomplete.
  23   enum Type {
  24     INVALID,        // Empty input
  25     UNKNOWN,        // Valid input whose type cannot be determined
  26     URL,            // Input autodetected as a URL
  27     QUERY,          // Input autodetected as a query
  28     FORCED_QUERY,   // Input forced to be a query by an initial '?'
  29   };
  30
  31   // The type of page currently displayed.
  32   // Note: when adding an element to this enum, please add it at the end
  33   // and update omnibox_event.proto::PageClassification and
  34   // omnibox_edit_model.cc::ClassifyPage() too.
  35   enum PageClassification {
  36     // An invalid URL; shouldn't happen.
  37     INVALID_SPEC = 0,
  38
  39     // chrome://newtab/.  This can be either the built-in version or a
  40     // replacement new tab page from an extension.  Note that when Instant
  41     // Extended is enabled, the new tab page will be reported as either
  42     // INSTANT_NTP_WITH_OMNIBOX_AS_STARTING_FOCUS or
  43     // INSTANT_NTP_WITH_FAKEBOX_AS_STARTING_FOCUS below,
  44     // unless an extension is replacing the new tab page, in which case
  45     // it will still be reported as NTP.
  46     NTP = 1,
  47
  48     // about:blank.
  49     BLANK = 2,
  50
  51     // The user's home page.  Note that if the home page is set to any
  52     // of the new tab page versions or to about:blank, then we'll
  53     // classify the page into those categories, not HOME_PAGE.
  54     HOME_PAGE = 3,
  55
  56     // The catch-all entry of everything not included somewhere else
  57     // on this list.
  58     OTHER = 4,
  59
  60     // The user is on a search result page that's doing search term
  61     // replacement, meaning the search terms should've appeared in the omnibox
  62     // before the user started editing it, not the URL of the page.
  63     SEARCH_RESULT_PAGE_DOING_SEARCH_TERM_REPLACEMENT = 6,
  64
  65     // The new tab page in which this omnibox interaction first started
  66     // with the user having focus in the omnibox.
  67     INSTANT_NTP_WITH_OMNIBOX_AS_STARTING_FOCUS = 7,
  68
  69     // The new tab page in which this omnibox interaction first started
  70     // with the user having focus in the fakebox.
  71     INSTANT_NTP_WITH_FAKEBOX_AS_STARTING_FOCUS = 8,
  72
  73     // The user is on a search result page that's not doing search term
  74     // replacement, meaning the URL of the page should've appeared in the
  75     // omnibox before the user started editing it, not the search terms.
  76     SEARCH_RESULT_PAGE_NO_SEARCH_TERM_REPLACEMENT = 9
  77   };
  78
  79   AutocompleteInput();
  80   // |text| and |cursor_position| represent the input query and location of
  81   // the cursor with the query respectively.  |cursor_position| may be set to
  82   // base::string16::npos if the input |text| doesn't come directly from the
  83   // user's typing.
  84   //
  85   // |desired_tld| is the user's desired TLD, if one is not already present in
  86   // the text to autocomplete.  When this is non-empty, it also implies that
  87   // "www." should be prepended to the domain where possible. The |desired_tld|
  88   // should not contain a leading '.' (use "com" instead of ".com").
  89   //
  90   // If |current_url| is set to a valid search result page URL, providers can
  91   // use it to perform query refinement. For example, if it is set to an image
  92   // search result page, the search provider may generate an image search URL.
  93   // Query refinement is only used by mobile ports, so only these set
  94   // |current_url| to a non-empty string.
  95   //
  96   // |current_page_classification| represents the type of page the user is
  97   // viewing and manner in which the user is accessing the omnibox; it's
  98   // more than simply the URL.  It includes, for example, whether the page
  99   // is a search result page doing search term replacement or not.
 100   //
 101   // |prevent_inline_autocomplete| is true if the generated result set should
 102   // not require inline autocomplete for the default match.  This is difficult
 103   // to explain in the abstract; the practical use case is that after the user
 104   // deletes text in the edit, the HistoryURLProvider should make sure not to
 105   // promote a match requiring inline autocomplete too highly.
 106   //
 107   // |prefer_keyword| should be true when the keyword UI is onscreen; this will
 108   // bias the autocomplete result set toward the keyword provider when the input
 109   // string is a bare keyword.
 110   //
 111   // |allow_exact_keyword_match| should be false when triggering keyword mode on
 112   // the input string would be surprising or wrong, e.g. when highlighting text
 113   // in a page and telling the browser to search for it or navigate to it. This
 114   // parameter only applies to substituting keywords.
 115   //
 116   // If |matches_requested| is BEST_MATCH or SYNCHRONOUS_MATCHES the controller
 117   // asks the providers to only return matches which are synchronously
 118   // available, which should mean that all providers will be done immediately.
 119   AutocompleteInput(const base::string16& text,
 120                     size_t cursor_position,
 121                     const base::string16& desired_tld,
 122                     const GURL& current_url,
 123                     PageClassification current_page_classification,
 124                     bool prevent_inline_autocomplete,
 125                     bool prefer_keyword,
 126                     bool allow_exact_keyword_match,
 127                     bool want_asynchronous_matches);
 128   ~AutocompleteInput();
 129
 130   // If type is |FORCED_QUERY| and |text| starts with '?', it is removed.
 131   // Returns number of leading characters removed.
 132   static size_t RemoveForcedQueryStringIfNecessary(Type type,
 133                                                    base::string16* text);
 134
 135   // Converts |type| to a string representation.  Used in logging.
 136   static std::string TypeToString(Type type);
 137
 138   // Parses |text| and returns the type of input this will be interpreted as.
 139   // The components of the input are stored in the output parameter |parts|, if
 140   // it is non-NULL. The scheme is stored in |scheme| if it is non-NULL. The
 141   // canonicalized URL is stored in |canonicalized_url|; however, this URL is
 142   // not guaranteed to be valid, especially if the parsed type is, e.g., QUERY.
 143   static Type Parse(const base::string16& text,
 144                     const base::string16& desired_tld,
 145                     url::Parsed* parts,
 146                     base::string16* scheme,
 147                     GURL* canonicalized_url);
 148
 149   // Parses |text| and fill |scheme| and |host| by the positions of them.
 150   // The results are almost as same as the result of Parse(), but if the scheme
 151   // is view-source, this function returns the positions of scheme and host
 152   // in the URL qualified by "view-source:" prefix.
 153   static void ParseForEmphasizeComponents(const base::string16& text,
 154                                           url::Component* scheme,
 155                                           url::Component* host);
 156
 157   // Code that wants to format URLs with a format flag including
 158   // net::kFormatUrlOmitTrailingSlashOnBareHostname risk changing the meaning if
 159   // the result is then parsed as AutocompleteInput.  Such code can call this
 160   // function with the URL and its formatted string, and it will return a
 161   // formatted string with the same meaning as the original URL (i.e. it will
 162   // re-append a slash if necessary).
 163   static base::string16 FormattedStringWithEquivalentMeaning(
 164       const GURL& url,
 165       const base::string16& formatted_url);
 166
 167   // Returns the number of non-empty components in |parts| besides the host.
 168   static int NumNonHostComponents(const url::Parsed& parts);
 169
 170   // Returns whether |text| begins "http:" or "view-source:http:".
 171   static bool HasHTTPScheme(const base::string16& text);
 172
 173   // User-provided text to be completed.
 174   const base::string16& text() const { return text_; }
 175
 176   // Returns 0-based cursor position within |text_| or base::string16::npos if
 177   // not used.
 178   size_t cursor_position() const { return cursor_position_; }
 179
 180   // Use of this setter is risky, since no other internal state is updated
 181   // besides |text_|, |cursor_position_| and |parts_|.  Only callers who know
 182   // that they're not changing the type/scheme/etc. should use this.
 183   void UpdateText(const base::string16& text,
 184                   size_t cursor_position,
 185                   const url::Parsed& parts);
 186
 187   // The current URL, or an invalid GURL if query refinement is not desired.
 188   const GURL& current_url() const { return current_url_; }
 189
 190   // The type of page that is currently behind displayed and how it is
 191   // displayed (e.g., with search term replacement or without).
 192   AutocompleteInput::PageClassification current_page_classification() const {
 193     return current_page_classification_;
 194   }
 195
 196   // The type of input supplied.
 197   Type type() const { return type_; }
 198
 199   // Returns parsed URL components.
 200   const url::Parsed& parts() const { return parts_; }
 201
 202   // The scheme parsed from the provided text; only meaningful when type_ is
 203   // URL.
 204   const base::string16& scheme() const { return scheme_; }
 205
 206   // The input as an URL to navigate to, if possible.
 207   const GURL& canonicalized_url() const { return canonicalized_url_; }
 208
 209   // Returns whether inline autocompletion should be prevented.
 210   bool prevent_inline_autocomplete() const {
 211     return prevent_inline_autocomplete_;
 212   }
 213
 214   // Returns whether, given an input string consisting solely of a substituting
 215   // keyword, we should score it like a non-substituting keyword.
 216   bool prefer_keyword() const { return prefer_keyword_; }
 217
 218   // Returns whether this input is allowed to be treated as an exact
 219   // keyword match.  If not, the default result is guaranteed not to be a
 220   // keyword search, even if the input is "<keyword> <search string>".
 221   bool allow_exact_keyword_match() const { return allow_exact_keyword_match_; }
 222
 223   // Returns whether providers should be allowed to make asynchronous requests
 224   // when processing this input.
 225   bool want_asynchronous_matches() const { return want_asynchronous_matches_; }
 226
 227   // Resets all internal variables to the null-constructed state.
 228   void Clear();
 229
 230  private:
 231   FRIEND_TEST_ALL_PREFIXES(AutocompleteProviderTest, GetDestinationURL);
 232
 233   // NOTE: Whenever adding a new field here, please make sure to update Clear()
 234   // method.
 235   base::string16 text_;
 236   size_t cursor_position_;
 237   GURL current_url_;
 238   AutocompleteInput::PageClassification current_page_classification_;
 239   Type type_;
 240   url::Parsed parts_;
 241   base::string16 scheme_;
 242   GURL canonicalized_url_;
 243   bool prevent_inline_autocomplete_;
 244   bool prefer_keyword_;
 245   bool allow_exact_keyword_match_;
 246   bool want_asynchronous_matches_;
 247 };
 248
 249 #endif  // CHROME_BROWSER_AUTOCOMPLETE_AUTOCOMPLETE_INPUT_H_