Add examples Url methods #309 #340

ghost · 2017-05-14T07:50:13Z

This change is

ghost · 2017-05-14T07:56:24Z

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

@@ -861,6 +886,20 @@ impl Url {
    }

    /// Return this URL’s query string, if any, as a percent-encoded ASCII string.


Let's show a third example where percent-encoding is necessary.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    ///
+    /// let url = Url::parse("https://example.com/api/versions?page=2").unwrap();
+    ///
+    /// assert_eq!(url.path(), "/api/versions");


I think this would be more readable at a glance if the asserts were grouped with the previous line:

use url::Url; let url = Url::parse("https://example.com/api/versions?page=2").unwrap(); assert_eq!(url.path(), "/api/versions"); let url = Url::parse("https://example.com").unwrap(); assert_eq!(url.path(), "/");

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    /// use url::Url;
+    ///
+    /// let parse_options = Url::options();
+    /// let base = parse_options.parse("https://example.net/api/").unwrap();


Please come up with an example that requires ParseOptions. This one would just use Url::parse.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    /// {
+    ///     url.set_fragment(Some("cell=4,1-6,2"));
+    /// }
+    /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));


Please add an assert on url.as_str() after each of these to show what the full url looks like.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    /// {
+    ///     url.set_query(Some("page=2"));
+    /// }
+    /// assert_eq!(url.query(), Some("page=2"));


Please add an assert on url.as_str() after this.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    /// use url::Url;
+    ///
+    /// let mut url = Url::parse("http://example.com").unwrap();
+    /// {


This nesting is not needed.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    /// {
+    ///     url.set_ip_host("127.0.0.1".parse().unwrap());
+    /// }
+    /// assert_eq!(url.host_str(), Some("127.0.0.1"));


Please add an assert on url.as_str() after this.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    ///
+    /// let mut url = Url::parse("mailto:rms@example.com").unwrap();
+    /// let result = url.set_ip_host("127.0.0.1".parse().unwrap());
+    /// assert!(result.is_err());


Since the error type isn't meaningful, please add a brief comment here reminding why this is an error.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    ///
+    /// let mut url = Url::parse("mailto:rmz@example.com").unwrap();
+    /// let result = url.set_username("user1");
+    /// assert!(result.is_err());


Please add a comment saying why this is an error.

dtolnay · 2017-05-14T09:58:20Z

src/lib.rs

+    /// let mut url = Url::parse("ftp://:secre1@example.com").unwrap();
+    /// let result = url.set_username("user1");
+    /// assert!(result.is_ok());
+    /// assert_eq!(url.username(), "user1");


Please add an assert on url.as_str().

dtolnay · 2017-05-14T10:00:31Z

Nice work. One more comment that applies to all of these: the examples should show realistic error handling. In real code you probably would not want any of these unwrap() calls to crash your application. Use ? instead - see #323 for some examples.

brson · 2017-06-03T03:06:47Z

Ping @hngnaig

ghost · 2017-06-05T10:54:14Z

I just fix code, but i missed test for method path, i will update soon, let me know if any wrong. Thanks @dtolnay.

ghost · 2017-06-05T14:29:32Z

I need help about function path, as doc, method will return &str, that percent-encoded ASCII string. But i assert function shown as bellow, that no percent-encoded.

use url::Url;
let url = Url::parse("https://example.com/foo/bar/baz").unwrap();
assert_eq!(url.path(), "/foo/bar/baz");

I didn't really understand what it is. I think i should assert as bellow.

use url::Url;
use url::percent_encoding;
let url = Url::parse("https://example.com/foo%21bar%21baz").unwrap();
let encoding_path = percent_encoding::percent_encode(b"/foo/bar/baz", PATH_SEGMENT_ENCODE_SET);
let path_str = encoding_path.collect::<String>();
assert_eq!(url.path(), path_str);

Thanks for help me.

SimonSapin · 2017-06-13T16:55:31Z

src/lib.rs

+    ///
+    /// # Examples
+    ///
+    /// Get default `ParseOption`, then change base url


ParseOptions is plural. (s missing.)

SimonSapin · 2017-06-13T16:55:31Z

src/lib.rs

+    ///
+    /// let options = Url::options();
+    /// let api = Url::parse("https://api.example.com").ok();
+    /// let base_url = options.base_url(api.as_ref());


Please replace .ok() with .unwrap() and api.as_ref() with Some(&api), to show more typical usage.

Actually, according to the other examples (and as highlighted by @dtolnay), we should not be using unwrap() either. Let's use ? instead, thus forcing users to handle the errors properly.

SimonSapin · 2017-06-13T17:00:02Z

@hngnaig Your examples for path happen not to use percent-encoding. If you’d like to add an example that does, try something like:

let url = Url::parse("https://example.com/Été hiver/").unwrap();
assert_eq!(url.path(), "/%C3%89t%C3%A9%20hiver");

No need to use percent_encode explicitly in that example.

SimonSapin · 2017-06-19T07:37:59Z

Your Url::path example looks good, thanks!

However, I’m not sure how it happened, but this PR is now adding 115 new commits. Please squash them into one commit. (Unless you think it’s valuable to split your changes into multiple commits, but they should not duplicate unrelated changes.)

As an aside, I recommend this git alias to visualize the commit graph, I use it a lot. In ~/.gitconfig, add:

[alias]
graph = log --oneline --graph --all --decorate

Now the git graph command shows branch in your repository.

Now, the usual way to squash is git rebase -i <some-base-commit> (-i is also --interactive) and using the fixup instruction in the editor that comes up. But this might be tricky with so many commits and conflicts, so try this instead:

Check out your branch if it isn’t already.
Use git graph above or some other way to find which commit of the master branch your branch is up-to-date with. As far as I can tell this should be d19d5d0, but double-check.
Run git reset --soft <that-commit>, for example git reset --soft d19d5d0. This changes your branch to be "at" that commit, but keeps all of the checked out files intact.
Run git commit. Unfortunately with this method you will need to rewrite the commit message.
Run git push -f. -f is also --force, it will overwrite the remote branch (in your GitHub fork) regardless of what was there before, even if this effectively removes commits. This should be use very carefully, but it is needed in this case.

ghost · 2017-06-21T05:50:46Z

Thanks @SimonSapin for helping me. I squashed all commit, and reset them at the last commit d19d5d. However, there are still errors, I'm trying to check the code and fix the errors.

SimonSapin · 2017-06-21T06:58:35Z

I can take over the git wrangling if you’d like. Let me know.

ghost · 2017-06-21T09:33:11Z

💯 After trying to fix the error, pull request has been completely done, cc @SimonSapin 💯

KiChjang · 2017-06-21T09:49:18Z

@hngnaig Unfortunately your PR still contains merge commits and isn't properly squashed.

SimonSapin · 2017-06-21T11:16:03Z

It also has unrelated whitespace changes in fuzz/fuzzers/parse.rs and percent_encoding/lib.rs


        Squash commit

ghost · 2017-06-21T15:36:58Z

cc @KiChjang, @SimonSapin i squashed all commit, and remove all whitespace in fuzz/fuzzers/parse.rs and percent_encoding/lib.rs

Enet4 · 2017-06-21T16:10:23Z

src/lib.rs

+    ///
+    /// # fn run() -> Result<(), ParseError> {
+    /// let mut url = Url::parse("http://example.com")?;
+    /// url.set_ip_host("127.0.0.1".parse().unwrap());


Is this unwrap acceptable here (I'm asking because 127.0.0.1 is guaranteed to work)? If not, we could change the return type to Result<(), Box<Error>> and map errors into a &'static str.

I think it's acceptable because 127.0.0.1 is valid static ip address. But it will be much better if change return type to Result<(), Box<Error>>.

fn run() -> Result<(), Box<Error>> { url.set_ip_host("127.0.0.1".parse()?); }

SimonSapin · 2017-06-21T16:37:36Z

Thanks you!

@bors-servo r+

Reviewed 1 of 1 files at r3.
Review status: all files reviewed at latest revision, 17 unresolved discussions.

src/lib.rs, line 1605 at r3 (raw file):

Previously, Enet4 (Eduardo Pinho) wrote…

Is this unwrap acceptable here (I'm asking because 127.0.0.1 is guaranteed to work)? If not, we could change the return type to Result<(), Box<Error>> and map errors into a &'static str.

In normal code I think it’s fine to use .unwrap() when we know that it won’t panic (unless some code is buggy), for example when the input is fixed like here. In the spirit of #312 however we should probably avoid it in examples. Let’s do this later in a follow-up.

Comments from Reviewable

bors-servo · 2017-06-21T16:37:36Z

📌 Commit dd1f232 has been approved by SimonSapin

bors-servo · 2017-06-21T16:37:39Z

⌛ Testing commit dd1f232 with merge 1807848...


        Auto merge of #340 - hngnaig:master, r=SimonSapin

Add examples Url methods #309 Fix #309  --- This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/rust-url/340)

bors-servo · 2017-06-21T16:50:58Z

☀️ Test successful - status-travis
Approved by: SimonSapin
Pushing 1807848 to master...

dtolnay reviewed May 14, 2017

View changes

SimonSapin reviewed Jun 13, 2017

View changes

Squash commit

Loading status checks…

dd1f232

Enet4 reviewed Jun 21, 2017

View changes

servo / rust-url

Add examples Url methods #309 #340

Add examples Url methods #309 #340

ghost commented May 14, 2017 •

edited by SimonSapin

ghost commented May 14, 2017

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

dtolnay commented May 14, 2017

brson commented Jun 3, 2017

ghost commented Jun 5, 2017 •

edited by ghost

ghost commented Jun 5, 2017

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

SimonSapin commented Jun 13, 2017

SimonSapin commented Jun 19, 2017

ghost commented Jun 21, 2017

SimonSapin commented Jun 21, 2017

ghost commented Jun 21, 2017 •

edited by ghost

KiChjang commented Jun 21, 2017

SimonSapin commented Jun 21, 2017

ghost commented Jun 21, 2017

This comment has been minimized.

This comment has been minimized.

SimonSapin commented Jun 21, 2017

bors-servo commented Jun 21, 2017

bors-servo commented Jun 21, 2017

bors-servo commented Jun 21, 2017

		@@ -861,6 +886,20 @@ impl Url {
		}

		/// Return this URL’s query string, if any, as a percent-encoded ASCII string.

servo / rust-url

Join GitHub today

Add examples Url methods #309 #340

Add examples Url methods #309 #340

Conversation

ghost commented May 14, 2017 • edited by SimonSapin

ghost commented May 14, 2017

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

dtolnay commented May 14, 2017

brson commented Jun 3, 2017

ghost commented Jun 5, 2017 • edited by ghost

ghost commented Jun 5, 2017

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

SimonSapin commented Jun 13, 2017

SimonSapin commented Jun 19, 2017

ghost commented Jun 21, 2017

SimonSapin commented Jun 21, 2017

ghost commented Jun 21, 2017 • edited by ghost

KiChjang commented Jun 21, 2017

SimonSapin commented Jun 21, 2017

ghost commented Jun 21, 2017

This comment has been minimized.

Enet4 Jun 21, 2017 • edited

This comment has been minimized.

SimonSapin commented Jun 21, 2017

bors-servo commented Jun 21, 2017

bors-servo commented Jun 21, 2017

bors-servo commented Jun 21, 2017

ghost commented May 14, 2017 •

edited by SimonSapin

ghost commented Jun 5, 2017 •

edited by ghost

ghost commented Jun 21, 2017 •

edited by ghost

Enet4 Jun 21, 2017 •

edited