zypp/url/UrlBase.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /**
  10  * \file zypp/url/UrlBase.h
  11  */
  12 #ifndef   ZYPP_URL_URLBASE_H
  13 #define   ZYPP_URL_URLBASE_H
  14
  15 #include <zypp/url/UrlUtils.h>
  16 #include <zypp/base/PtrTypes.h>
  17
  18
  19 //////////////////////////////////////////////////////////////////////
  20 namespace zypp
  21 { ////////////////////////////////////////////////////////////////////
  22
  23   ////////////////////////////////////////////////////////////////////
  24   namespace url
  25   { //////////////////////////////////////////////////////////////////
  26
  27
  28     // ---------------------------------------------------------------
  29     /**
  30      * UrlBase behaviour configuration variables container.
  31      */
  32     typedef std::map< std::string, std::string > UrlConfig;
  33
  34
  35     // ---------------------------------------------------------------
  36     /**
  37      * Vector of URL scheme names.
  38      */
  39     typedef std::vector<std::string>             UrlSchemes;
  40
  41
  42     // ---------------------------------------------------------------
  43     /**
  44      * Url::toString() view options.
  45      *
  46      * A instance of this class represents a bit-wise combination
  47      * of view option constants.
  48      *
  49      * It provides ViewOption::operator+() and ViewOption::operator-()
  50      * to modify a view option combination and a ViewOption::has()
  51      * method, to check if a specified option is enabled or not.
  52      */
  53     struct ViewOption
  54     {
  55       /** @{ */
  56       /**
  57        * Option to include scheme name in the URL string.
  58        *
  59        * Disabling this option causes, that the URL string
  60        * contains the path, query and fragment components
  61        * only, for example just "/foo/bar.txt".
  62        *
  63        * This option is \b enabled by default.
  64        */
  65       static const ViewOption WITH_SCHEME;
  66       /**
  67        * Option to include username in the URL string.
  68        *
  69        * This option depends on a enabled WITH_SCHEME and
  70        * WITH_HOST options and is \b enabled by default.
  71        */
  72       static const ViewOption WITH_USERNAME;
  73       /**
  74        * Option to include password in the URL string.
  75        *
  76        * This option depends on a enabled WITH_SCHEME,
  77        * WITH_HOST and WITH_USERNAME options and is
  78        * \b disabled by default, causing to hide the
  79        * password in the URL authority.
  80        */
  81       static const ViewOption WITH_PASSWORD;
  82       /**
  83        * Option to include hostname in the URL string.
  84        *
  85        * This option depends on a enabled WITH_SCHEME
  86        * option and is \b enabled by default.
  87        */
  88       static const ViewOption WITH_HOST;
  89       /**
  90        * Option to include port number in the URL string.
  91        *
  92        * This option depends on a enabled WITH_SCHEME and
  93        * WITH_HOST options and is \b enabled by default.
  94        */
  95       static const ViewOption WITH_PORT;
  96       /**
  97        * Option to include path name in the URL string.
  98        *
  99        * This option is \b enabled by default.
 100        */
 101       static const ViewOption WITH_PATH_NAME;
 102       /**
 103        * Option to include path parameters in the URL string.
 104        *
 105        * This option depends on a enabled WITH_PATH_NAME
 106        * option and is \b disabled by default, causing to
 107        * hide the path parameters.
 108        */
 109       static const ViewOption WITH_PATH_PARAMS;
 110       /**
 111        * Option to include query string in the URL string.
 112        *
 113        * This option is \b enabled by default.
 114        */
 115       static const ViewOption WITH_QUERY_STR;
 116       /**
 117        * Option to include fragment string in the URL string.
 118        *
 119        * This option is \b enabled by default.
 120        */
 121       static const ViewOption WITH_FRAGMENT;
 122       /** @} */
 123
 124       /** @{ */
 125       /**
 126        * Explicitely include the URL authority separator "//".
 127        *
 128        * It causes, that the URL string includes an empty URL
 129        * authority, for example:
 130        * "file:///foo.txt" instead of just "file:/foo.txt".
 131        *
 132        * This option depends on a enabled WITH_SCHEME view
 133        * option and is enabled by default.
 134        */
 135       static const ViewOption EMPTY_AUTHORITY;
 136       /**
 137        * Explicitely include the "/" path character.
 138        *
 139        * It causes, that a "/" is added to the Url if the path
 140        * name is empty, for example:
 141        *
 142        * "http://localhost/" instead of just "http://localhost".
 143        *
 144        * This option depends on a enabled WITH_PATH_NAME view
 145        * option and is enabled by default.
 146        */
 147       static const ViewOption EMPTY_PATH_NAME;
 148       /**
 149        * Explicitely include the path parameters separator ";".
 150        *
 151        * It causes, that the URL allways contains the ";" path
 152        * parameters separator.
 153        *
 154        * This option depends on a enabled EMPTY_PATH_NAME view
 155        * option and is disabled by default.
 156        */
 157       static const ViewOption EMPTY_PATH_PARAMS;
 158       /**
 159        * Explicitely include the query string separator "?".
 160        *
 161        * It causes, that if the query string is requested using
 162        * the WITH_QUERY_STR option, the URL allways contains the
 163        * "?" query string separator, even if the query string is
 164        * empty.
 165        * This option depends on a enabled WITH_QUERY_STR view
 166        * option and is disabled by default.
 167        */
 168       static const ViewOption EMPTY_QUERY_STR;
 169       /**
 170        * Explicitely include the fragment string separator "#".
 171        *
 172        * It causes, that if the fragment string is requested using
 173        * the WITH_FRAGMENT option, the URL allways contains the "#"
 174        * fragment string separator, even if the fragment string is
 175        * empty.
 176        * This option depends on a enabled WITH_FRAGMENT view
 177        * option and is disabled by default.
 178        */
 179       static const ViewOption EMPTY_FRAGMENT;
 180       /** @} */
 181
 182       /** @{ */
 183       /**
 184        * Default combination of view options.
 185        *
 186        * By default, following view options are enabled:
 187        *   WITH_SCHEME,    WITH_USERNAME,    WITH_HOST,
 188        *   WITH_PORT,      WITH_PATH_NAME,   WITH_QUERY_STR,
 189        *   WITH_FRAGMENT,  EMPTY_AUTHORITY,  EMPTY_PATH_NAME.
 190        */
 191       static const ViewOption DEFAULTS;
 192       /** @} */
 193
 194       /**
 195        * Create instance with default combination of view options.
 196        */
 197       ViewOption(): opt(DEFAULTS.opt)
 198       {}
 199
 200       /**
 201        * Adds \p l and \p r to a new option combination.
 202        *
 203        * @return The new option combination.
 204        */
 205       friend inline ViewOption
 206       operator + (const ViewOption &l, const ViewOption &r)
 207       { return ViewOption(l.opt |  r.opt); }
 208
 209       /**
 210        * Substract \p r from \p l to a new option combination.
 211        *
 212        * @return The new option combination.
 213        */
 214       friend inline ViewOption
 215       operator - (const ViewOption &l, const ViewOption &r)
 216       { return ViewOption(l.opt & ~r.opt); }
 217
 218       /**
 219        * Assign specified option combination \p o to the current object.
 220        *
 221        * \param o   The option or option combination to make a copy of.
 222        * \return A reference to this option combination.
 223        */
 224       inline ViewOption &
 225       operator = (const ViewOption &o)
 226       { opt = o.opt; return *this; }
 227
 228       /**
 229        * Check if specified option \p o is set in the current object.
 230        * \param o    A view option constant.
 231        * \return True, if specified option \p o is
 232        *               set/enabled in the instance.
 233        */
 234       inline bool
 235       has(const ViewOption &o) const
 236       { return o.opt & opt; }
 237
 238     private:
 239       ViewOption(int o): opt(o) {}
 240       int opt;
 241     };
 242
 243
 244     // ---------------------------------------------------------------
 245     /**
 246      * ViewOptions is just an alias for ViewOption.
 247      */
 248     typedef ViewOption ViewOptions;
 249
 250
 251     // ---------------------------------------------------------------
 252     /**
 253      * Internal data as used by UrlBase.
 254      */
 255     class UrlData
 256     {
 257     public:
 258       UrlData()
 259       {}
 260
 261       UrlData(const UrlConfig &conf)
 262         : config(conf)
 263       {}
 264
 265       UrlConfig       config;
 266       ViewOptions     vopts;
 267
 268       std::string     scheme;
 269       std::string     user;
 270       std::string     pass;
 271       std::string     host;
 272       std::string     port;
 273       std::string     pathname;
 274       std::string     pathparams;
 275       std::string     querystr;
 276       std::string     fragment;
 277     };
 278
 279
 280     // ---------------------------------------------------------------
 281     /**
 282      * \brief Generic Url base class.
 283      *
 284      * The UrlBase class implements default behaviour for URL
 285      * manipulations and a base for implementation of scheme-
 286      * specialized URL's for the Url class.
 287      *
 288      */
 289     class UrlBase
 290     {
 291     public:
 292
 293       virtual ~UrlBase();
 294       UrlBase();
 295
 296       /**
 297        * Create a new Url object as copy of the given one.
 298        * \param url The Url object to make a copy of.
 299        */
 300       UrlBase(const UrlBase &url);
 301
 302       /**
 303        * \brief Construct new object and initializes it with
 304        *        specified URL components.
 305        *
 306        * \param scheme    A scheme name.
 307        * \param authority A authority component data (encoded).
 308        * \param pathdata  A path component data (encoded).
 309        * \param querystr  A query string (encoded).
 310        * \param fragment  A fragment component (encoded),
 311        */
 312       UrlBase(const std::string &scheme,
 313               const std::string &authority,
 314               const std::string &pathdata,
 315               const std::string &querystr,
 316               const std::string &fragment);
 317
 318
 319       // -----------------
 320       /**
 321        * \brief Clears all data in the object.
 322        */
 323       virtual void
 324       clear();
 325
 326       /**
 327        * Returns pointer to a copy of the current object.
 328        *
 329        * Should be reimplemented by all derived object using
 330        * the copy constructor of the derived class, e.g.:
 331        * \code
 332        *   return new MyUrlDerivedFromUrlBase(*this);
 333        * \endcode
 334        *
 335        * \return A pointer to a copy of the current object.
 336        */
 337       virtual UrlBase *
 338       clone() const;
 339
 340       /**
 341        * \brief Initializes current object with new URL components.
 342        *
 343        * \param scheme    A scheme name.
 344        * \param authority A authority component data (encoded).
 345        * \param pathdata  A path component data (encoded).
 346        * \param querystr  A query string (encoded).
 347        * \param fragment  A fragment component (encoded),
 348        */
 349       virtual void
 350       init(const std::string &scheme,
 351            const std::string &authority,
 352            const std::string &pathdata,
 353            const std::string &querystr,
 354            const std::string &fragment);
 355
 356
 357       // -----------------
 358       /**
 359        * \brief Returns scheme names known by this object.
 360        *
 361        * This method is used in the isValidScheme() method and
 362        * is intended to be reimplemented by derived classes to
 363        * return the scheme names it implements (is restricted
 364        * or compatible to).
 365        *
 366        * For example, if your derived class implements special
 367        * features of LDAP URL's, this method may return "ldap"
 368        * and "ldaps" scheme names.
 369        *
 370        * The UrlBase class returns an empty vector, that signals
 371        * that it is useable with all URL's.
 372        *
 373        * \return A vector with scheme names known by this object.
 374        */
 375       virtual UrlSchemes
 376       getKnownSchemes() const;
 377
 378       /**
 379        * \brief Returns if scheme name is known to this object.
 380        * \return True, if scheme name is known to this object.
 381        */
 382       virtual bool
 383       isKnownScheme(const std::string &scheme) const;
 384
 385
 386       /**
 387        * \brief Verifies specified scheme name.
 388        *
 389        * Verifies the generic syntax of the specified \p scheme name
 390        * and if it is contained in the current object's list of known
 391        * schemes (see getKnownSchemes()) if the list is not empty (as
 392        * in the UrlBase class).
 393        *
 394        * \return True, if generic scheme name syntax is valid and
 395        *         the scheme name is known to the current object.
 396        */
 397       virtual bool
 398       isValidScheme(const std::string &scheme) const;
 399
 400
 401       /**
 402        * \brief Verifies the Url.
 403        *
 404        * Verifies if the current object contains a non-empty scheme
 405        * name. Additional semantical URL checks may be performed by
 406        * derived UrlBase-objects.
 407        *
 408        * \return True, if the Url seems to be valid.
 409        */
 410       virtual bool
 411       isValid() const;
 412
 413
 414       // -----------------
 415       /**
 416        * Returns a default string representation of the Url object.
 417        *
 418        * By default, a password in the URL will be hidden.
 419        *
 420        * \return A default string representation of the Url object.
 421        */
 422       virtual std::string
 423       toString() const;
 424
 425       /**
 426        * Returns a string representation of the Url object.
 427        *
 428        * To include a password in the resulting Url string, use:
 429        * \code
 430        *    url.toString(url::ViewOptions() +
 431        *                 url::ViewOptions::WITH_PASSWORD);
 432        * \endcode
 433        *
 434        * or its equivalent:
 435        *
 436        * \code
 437        *    url.toString(url::ViewOptions::DEFAULTS +
 438        *                 url::ViewOptions::WITH_PASSWORD);
 439        * \endcode
 440        *
 441        * \param opts  A combination of view options.
 442        * \return A string representation of the Url object.
 443        */
 444       virtual std::string
 445       toString(const zypp::url::ViewOptions &opts) const;
 446
 447
 448       // -----------------
 449       /**
 450        * Returns the scheme name of the URL.
 451        * \return Scheme name of the current Url object.
 452        */
 453       virtual std::string
 454       getScheme() const;
 455
 456
 457       // -----------------
 458       /**
 459        * Returns the encoded authority component of the URL.
 460        *
 461        * The returned authority string does not contain the leading
 462        * "//" separator characters, but just its "user:pass@host:port"
 463        * content only.
 464        *
 465        * \return The encoded authority component string.
 466        */
 467       virtual std::string
 468       getAuthority() const;
 469
 470       /**
 471        * Returns the username from the URL authority.
 472        * \param eflag Flag if the usename should be percent-decoded or not.
 473        * \return The username sub-component from the URL authority.
 474        */
 475       virtual std::string
 476       getUsername(EEncoding eflag) const;
 477
 478       /**
 479        * Returns the password from the URL authority.
 480        * \param eflag Flag if the password should be percent-decoded or not.
 481        * \return The password sub-component from the URL authority.
 482        */
 483       virtual std::string
 484       getPassword(EEncoding eflag) const;
 485
 486       /**
 487        * Returns the hostname or IP from the URL authority.
 488        *
 489        * In case the Url contains an IP number, it may be surrounded
 490        * by "[" and "]" characters, for example "[::1]" for an IPv6
 491        * localhost address.
 492        *
 493        * \param eflag Flag if the host should be percent-decoded or not.
 494        * \return The host sub-component from the URL authority.
 495        */
 496       virtual std::string
 497       getHost(EEncoding eflag) const;
 498
 499       /**
 500        * Returns the port from the URL authority.
 501        * \return The port sub-component from the URL authority.
 502        */
 503       virtual std::string
 504       getPort() const;
 505
 506
 507       // -----------------
 508       /**
 509        * Returns the encoded path component of the URL.
 510        *
 511        * The path data contains the path name, optionally
 512        * followed by path parameters separated with a ";"
 513        * character, for example "/foo/bar;version=1.1".
 514        *
 515        * \return The encoded path component of the URL.
 516        */
 517       virtual std::string
 518       getPathData() const;
 519
 520       /**
 521        * Returns the path name from the URL.
 522        * \param eflag Flag if the path should be decoded or not.
 523        * \return The path name sub-component without path parameters
 524        *         from Path-Data component of the URL.
 525        */
 526       virtual std::string
 527       getPathName(EEncoding eflag) const;
 528
 529       /**
 530        * Returns the path parameters from the URL.
 531        * \return The encoded path parameters from the URL.
 532        */
 533       virtual std::string
 534       getPathParams() const;
 535
 536       /**
 537        * Returns a vector with path parameter substrings.
 538        *
 539        * The default path parameter separator is the \c ',' character.
 540        * A schema specific object may overide the default separators.
 541        *
 542        * For example, the path parameters string "foo=1,bar=2" is splited
 543        * by default into a vector containing the substrings "foo=1" and
 544        * "bar=2".
 545        *
 546        * \return The path parameters splited into a vector of substrings.
 547        */
 548       virtual zypp::url::ParamVec
 549       getPathParamsVec() const;
 550
 551       /**
 552        * Returns a string map with path parameter keys and values.
 553        *
 554        * The default path parameter separator is the \c ',' character,
 555        * the default key/value separator for the path parameters is
 556        * the \c '=' character.
 557        * A schema specific object may overide the default separators.
 558        *
 559        * For example, the path parameters string "foo=1,bar=2" is splited
 560        * into a map containing "foo" = "1" and "bar" = "2" by default.
 561        *
 562        * \param eflag Flag if the path parameter keys and values should
 563        *               be decoded or not.
 564        * \return The path parameters key and values as a string map.
 565        */
 566       virtual zypp::url::ParamMap
 567       getPathParamsMap(EEncoding eflag) const;
 568
 569       /**
 570        * Return the value for the specified path parameter.
 571        *
 572        * For example, if the path parameters string is "foo=1,bar=2"
 573        * the method will return the substring "1" for the param key
 574        * "foo" and "2" for the param key "bar".
 575        *
 576        * \param param The path parameter key.
 577        * \param eflag Flag if the path parameter keys and values should
 578        *              be decoded or not.
 579        * \return The value for the path parameter key or empty string.
 580        */
 581       virtual std::string
 582       getPathParam(const std::string &param, EEncoding eflag) const;
 583
 584
 585       // -----------------
 586       /**
 587        * Returns the encoded query string component of the URL.
 588        *
 589        * The query string is returned without first "?" (separator)
 590        * character. Further "?" characters as in e.g. LDAP URL's
 591        * remains in the returned string.
 592        *
 593        * \return The encoded query string component of the URL.
 594        */
 595       virtual std::string
 596       getQueryString() const;
 597
 598       /**
 599        * Returns a vector with query string parameter substrings.
 600        *
 601        * The default query string parameter separator is the \c '&'
 602        * character.
 603        * A schema specific object may overide the default separators.
 604        *
 605        * For example, the query string "foo=1&bar=2" is splited by
 606        * default into a vector containing the substrings "foo=1" and
 607        * "bar=2".
 608        *
 609        * \return The query string splited into a vector of substrings.
 610        */
 611       virtual zypp::url::ParamVec
 612       getQueryStringVec() const;
 613
 614       /**
 615        * Returns a string map with query parameter and their values.
 616        *
 617        * The default query string parameter separator is the \c ','
 618        * character, the default key/value separator the \c '=' character.
 619        * A schema specific object may overide the default separators.
 620        *
 621        * For example, the query string "foo=1&bar=2" is splited by
 622        * default into a map containing "foo" = "1" and "bar" = "2".
 623        *
 624        * \param eflag Flag if the query string keys and values should
 625        *               be decoded or not.
 626        * \return The query string as a key/value string map.
 627        */
 628       virtual zypp::url::ParamMap
 629       getQueryStringMap(EEncoding eflag) const;
 630
 631       /**
 632        * Return the value for the specified query parameter.
 633        *
 634        * For example, if the query string is "foo=1,bar=2" the method
 635        * will return the substring "1" for the param key "foo" and
 636        * "2" for the param key "bar".
 637        *
 638        * \param param The query parameter key.
 639        * \param eflag Flag if the query parameter keys and values should
 640        *              be decoded or not.
 641        * \return The value for the query parameter key or empty string.
 642        */
 643       virtual std::string
 644       getQueryParam(const std::string &param, EEncoding eflag) const;
 645
 646
 647       // -----------------
 648       /**
 649        * Returns the encoded fragment component of the URL.
 650        * \param eflag Flag if the fragment should be percent-decoded or not.
 651        * \return The encoded fragment component of the URL.
 652        */
 653       virtual std::string
 654       getFragment(EEncoding eflag) const;
 655
 656
 657       // -----------------
 658       /**
 659        * \brief Set the scheme name in the URL.
 660        * \param scheme The new scheme name.
 661        */
 662       virtual void
 663       setScheme(const std::string &scheme);
 664
 665
 666       // -----------------
 667       /**
 668        * \brief Set the authority component in the URL.
 669        *
 670        * The \p authority string shoud not contain any leading
 671        * "//" separator characters (just "user:pass@host:port").
 672        *
 673        * \param authority The authority component string.
 674        */
 675       virtual void
 676       setAuthority(const std::string &authority);
 677
 678       /**
 679        * \brief Set the username in the URL authority.
 680        * \param user The new username.
 681        */
 682       virtual void
 683       setUsername(const std::string &user);
 684
 685       /**
 686        * \brief Set the password in the URL authority.
 687        * \param pass The new password.
 688        */
 689       virtual void
 690       setPassword(const std::string &pass);
 691
 692       /**
 693        * \brief Set the hostname or IP in the URL authority.
 694        * \param host The new hostname or IP.
 695        */
 696       virtual void
 697       setHost(const std::string &host);
 698
 699       /**
 700        * \brief Set the port number in the URL authority.
 701        * \param port The new port number.
 702        */
 703       virtual void
 704       setPort(const std::string &port);
 705
 706
 707       // -----------------
 708       /**
 709        * \brief Set the path data component in the URL.
 710        *
 711        * The \p pathdata string may include path parameters
 712        * separated using the ";" separator character.
 713        *
 714        * \param pathdata The encoded path data component string.
 715        */
 716       virtual void
 717       setPathData(const std::string &pathdata);
 718
 719       /**
 720        * \brief Set the path name.
 721        * \param path The new path name.
 722        */
 723       virtual void
 724       setPathName(const std::string &path);
 725
 726       /**
 727        * \brief Set the path parameters.
 728        * \param params The new path parameter string.
 729        */
 730       virtual void
 731       setPathParams(const std::string &params);
 732
 733       /**
 734        * \brief Set the path parameters.
 735        * \param pvec The vector with path parameters.
 736        */
 737       virtual void
 738       setPathParamsVec(const zypp::url::ParamVec &pvec);
 739
 740       /**
 741        * \brief Set the path parameters.
 742        * \param pmap The map with path parameters.
 743        */
 744       virtual void
 745       setPathParamsMap(const zypp::url::ParamMap &pmap);
 746
 747       /**
 748        * \brief Set or add value for the specified path parameter.
 749        * \param param The path parameter name.
 750        * \param value The path parameter value.
 751        */
 752       virtual void
 753       setPathParam(const std::string &param, const std::string &value);
 754
 755
 756       // -----------------
 757       /**
 758        * \brief Set the query string in the URL.
 759        *
 760        * The \p querystr string will be supposed to not to
 761        * contain the "?" separator character.
 762        *
 763        * \param querystr The new encoded query string.
 764        */
 765       virtual void
 766       setQueryString(const std::string &querystr);
 767
 768       /**
 769        * \brief Set the query parameters.
 770        * \param qvec The vector with query parameters.
 771        */
 772       virtual void
 773       setQueryStringVec(const zypp::url::ParamVec &qvec);
 774
 775       /**
 776        * \brief Set the query parameters.
 777        * \param qmap The map with query parameters.
 778        */
 779       virtual void
 780       setQueryStringMap(const zypp::url::ParamMap &qmap);
 781
 782       /**
 783        * \brief Set or add value for the specified query parameter.
 784        * \param param The query parameter name.
 785        * \param value The query parameter value.
 786        */
 787       virtual void
 788       setQueryParam(const std::string &param, const std::string &value);
 789
 790
 791       // -----------------
 792       /**
 793        * \brief Set the fragment string in the URL.
 794        * \param fragment The new encoded fragment string.
 795        */
 796       virtual void
 797       setFragment(const std::string &fragment);
 798
 799
 800       // -----------------
 801       /**
 802        * Configures behaviour of the instance.
 803        *
 804        * This method is called in UrlBase constructors before
 805        * any URL components are applied.
 806        * Derived classes may reimplement this method to change
 807        * the behaviour of the object.
 808        * Use the config() methods to query and change them.
 809        *
 810        * The UrlBase class uses following config variables:
 811        *
 812        * - Path parameter separators:
 813        *   - \a \c sep_pathparams   \c ";"
 814        *     Separator used to split path parameters from path name.
 815        *   - \a \c psep_pathparam   \c ","
 816        *     Separator between path parameters.
 817        *   - \a \c vsep_pathparam   \c "="
 818        *     Separator between key and value of a path parameter.
 819        *   .
 820        * .
 821        *
 822        * - Query string separators:
 823        *   - \a \c psep_querystr    \c "&"
 824        *     Separator between query string parameters.
 825        *   - \a \c vsep_querystr    \c "="
 826        *     Separator between key and value of a query parameter.
 827        *   .
 828        * .
 829        *
 830        * - Characters in URL components, that are safe without
 831        *   URL percent-encoding (see zypp::url::encode()).
 832        *   - \a safe_username    ""
 833        *   - \a safe_password    ""
 834        *   - \a safe_hostname    "[:]"
 835        *   - \a safe_pathname    "/"
 836        *   - \a safe_pathparams  ""
 837        *   - \a safe_querystr    ""
 838        *   - \a safe_fragment    ""
 839        *   .
 840        * .
 841        *
 842        * - Regular expressions used to verify URL components
 843        *   and their sub-components:
 844        *   - \a rx_scheme        "^[a-zA-Z][a-zA-Z0-9\\._-]*$"
 845        *   - \a rx_username      ".*"
 846        *   - \a rx_password      ".*"
 847        *   - \a rx_hostname      ".*" FIXME!
 848        *   - \a rx_port          "^[0-9]{1,5}$"
 849        *   - \a rx_pathname      ".*"
 850        *   - \a rx_pathparams    ".*"
 851        *   - \a rx_querystr      ".*"
 852        *   - \a rx_fragment      ".*"
 853        *   .
 854        * .
 855        */
 856       virtual void
 857       configure();
 858
 859
 860       /**
 861        * Get the value of a UrlBase configuration variable.
 862        *
 863        * See configure() method for names an purpose of the
 864        * configuration variables used in UrlBase class.
 865        *
 866        * \param opt The name of the configuration variable.
 867        * \return The value of the specified variable
 868        *         or empty string.
 869        */
 870       std::string
 871       config(const std::string &opt) const;
 872
 873     //protected:
 874       // friend class Url;
 875       /**
 876        * Set the value of a UrlBase configuration variable.
 877        *
 878        * See configure() method for names an purpose of the
 879        * configuration variables used in UrlBase class.
 880        *
 881        * \param opt The name of the configuration variable.
 882        * \param val The new value for the configuration variable.
 883        */
 884       void
 885       config(const std::string &opt, const std::string &val);
 886
 887
 888       /**
 889        * Return the view options of the current object.
 890        *
 891        * This method is used to query the view options
 892        * used by the Url::toString() method.
 893        *
 894        * \return The current view option combination.
 895        */
 896       ViewOptions
 897       getViewOptions() const;
 898
 899       /**
 900        * Change the view options of the current object.
 901        *
 902        * This method is used to change the view options
 903        * used by the Url::toString() method.
 904        *
 905        * \param vopts New view options combination.
 906        */
 907       void
 908       setViewOptions(const ViewOptions &vopts);
 909
 910
 911     protected:
 912       /**
 913        * Utility method to cleanup a path name.
 914        *
 915        * By default, this method replaces multiple occurences
 916        * of the "/" characeter from the begining of the path,
 917        * so the cleaned path begins with at most one "/".
 918        *
 919        * This operation is required in some cases to not to
 920        * missinterpret multiple "/" occurences as an empty
 921        * URL authority.
 922        *
 923        * \param path A path name.
 924        * \return A path begining with at most one "/" character.
 925        */
 926       virtual std::string
 927       cleanupPathName(const std::string &path);
 928
 929
 930     private:
 931       UrlData        *m_data;
 932     };
 933
 934
 935     // ---------------------------------------------------------------
 936     /**
 937      * \brief Copy-On-Write Url reference.
 938      */
 939     typedef RWCOW_pointer<UrlBase>          UrlRef;
 940
 941
 942     //////////////////////////////////////////////////////////////////
 943   } // namespace url
 944   ////////////////////////////////////////////////////////////////////
 945
 946   ////////////////////////////////////////////////////////////////////
 947 } // namespace zypp
 948 //////////////////////////////////////////////////////////////////////
 949
 950 #endif /* ZYPP_URL_URLBASE_H */
 951 /*
 952 ** vim: set ts=2 sts=2 sw=2 ai et:
 953 */