First example should be expanded to a complete program

[mhavrlent]

Example:

// Send a GET request and wait for the response headers.
let mut response = isahc::get("https://example.org")?;
// Read the response body into a string and print it to standard output.
println!("{}", response.text()?);

Error:

error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `std::ops::Try`)
 --> src\http.rs:3:20
  |
1 | / pub fn run() {
2 | | // Send a GET request and wait for the response headers.
3 | | let mut response = isahc::get("https://example.org")?;
  | |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ cannot use the `?` operator in a function that returns `()`
4 | | // Read the response body into a string and print it to standard output.
5 | | println!("{}", response.text()?);
6 | | }
  | |_- this function should return `Result` or `Option` to accept `?`
  |
  = help: the trait `std::ops::Try` is not implemented for `()`
  = note: required by `std::ops::Try::from_error`

error[E0599]: no method named `text` found for struct `http::response::Response<isahc::body::Body>` in the current scope
 --> src\http.rs:5:25
  |
5 | println!("{}", response.text()?);
  |                         ^^^^ method not found in `http::response::Response<isahc::body::Body>`
  |
  = help: items from traits can only be used if the trait is in scope
  = note: the following trait is implemented but not in scope; perhaps add a `use` for it:
          `use isahc::response::ResponseExt;`

error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `std::ops::Try`)        
 --> src\http.rs:5:16
  |
1 | / pub fn run() {
2 | | // Send a GET request and wait for the response headers.
3 | | let mut response = isahc::get("https://example.org")?;
4 | | // Read the response body into a string and print it to standard output.
5 | | println!("{}", response.text()?);
  | |                ^^^^^^^^^^^^^^^^ cannot use the `?` operator in a function that returns `()`
6 | | }
  | |_- this function should return `Result` or `Option` to accept `?`
  |
  = help: the trait `std::ops::Try` is not implemented for `()`
  = note: required by `std::ops::Try::from_error`

error: aborting due to 3 previous errors

Some errors have detailed explanations: E0277, E0599.
For more information about an error, try `rustc --explain E0277`.
error: could not compile `rust_test1`.

Rust version:

rustc 1.43.1 (8d69840ab 2020-05-04)

[sagebind]

Hi, thanks for trying out Isahc! The examples use the try (?) operator, which is a best practice when doing error handling in Rust. Your example fails to compile because your function run does not return a Result, but sending an HTTP request has the potential to fail (bad domain, network unreachable, etc) and the ? syntax is used to bubble up errors to the parent caller. You can read more about Result and error handling here: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html.

The key error is this part of the error message:

error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `std::ops::Try`) 

If you want the program to simply panic and exit if an error occurs, you can replace ? with .unwrap(), though this is not recommended for real-world programs (but it can be convenient when you're just learning or experimenting).

[mhavrlent]

@sagebind
Thank you. Could you please update the documentation and wrap example with a method with Result? It would help newbies like me, since newbies want to copy&paste some example first to see if it works. If simple examples don't work straight away, newbies tend to search for a different library. If several libraries don't work straight away, newbies tend to search for a different language.
Thanks.

[sagebind]

There are several complete examples of Rust programs in the examples directory that you can look to in order to test things out, which is linked to in the library documentation home page at https://docs.rs/isahc.

Could you please update the documentation and wrap example with a method with Result?

This is not a common practice in Rust library documentation, mainly because (1) it clutters up the example snippets with extra ceremony that can make things busier and take longer to read, and (2) Result is a fundamental concept of the language that is already taught elsewhere, and knowledge of it is usually assumed when using most libraries since its so integral. And the Isahc docs have a lot of example snippets, so wrapping everything in a function would probably grow tedious.

It may be worth considering though for the very first example, but for a full program the best place maybe for absolute beginners to start would be the simple program in the examples directory.

since newbies want to copy&paste some example first to see if it works.

Rust code typically can't usually be copied and pasted into arbitrary programs, since Rust has strong lifetime and type checking requirements that affect surrounding code.

I apologize if you had a poor first experience, but I'm not sure what else I could do to help as a library maintainer.

[sagebind]

Thinking about this further, the code snippet in the README file for sure could stand to be updated and expanded. That's something that definitely makes sense. I'll do that shortly.

[mhavrlent]

@sagebind
Yes, if you could replace the first example with the simple program, or put a link to that example above the first example, that would be really helpful.
Btw. I like Rust so far and I really appreciate your library, I know it's a lot of hard work. Let's make it a little bit more user friendly to avoid these "rust is too hard to learn" comments all over the internet. :)