Serializing urls with serde 1.0 is kinda weird, so maybe worth an example.

Using env_logger. This is different from #95 in that it should show making a function call that returns a Result, matching on it, and logging in the error case with the error value included in the message.

https://docs.rs/crossbeam

We used to have one but it didn't work: https://github.com/brson/rust-cookbook/issues/32.

We could use an approach more like https://serde.rs where it links to a playground rather than running the code inline. See this page for example. This is nice because you get to modify the code if you want.

#80 added an example that shows posting a JSON body. Let's add a separate one to post the contents of a file.

The bare minimum env_logger example.

As the #38 is closed, the stubs for "Serialize a Url" should be removed from net.md and intro.md

Perl Cookbook has a good reputation, but I have never read it. Give it a skim at least, then figure out which of their examples make sense in the Rust world, and produce a list of example use case statements to feed into the cookbook.

e.g. the "read lines from file" creates "lines.txt" and dirties the directory. Could solve this in skeptic.

Badges obtained from shields.io are always for the latest version available on crates.io
https://img.shields.io/crates/v/clap.svg?label=clap currently shows 2.24.1 while in committed Cargo.lock clap has version 2.23.3.

This is somewhat low priority ATM but I am sure that it will become a problem once breaking changes of cookbook dependencies are published. Users will likely get build errors from posted examples misguided by the badge version incompatible with cookbook Cargo.lock.

Imho It would be best to:

• Have travis check versions - possibly with https://crates.io/crates/cargo-outdated (and eagerly update if there are no conflicts/failed tests?)
• Have badges reflect the actual version in Cargo.lock - currently i have no idea how to manage that

Does anyone have non-contrived examples? Some ideas:

• nm to list symbols in the current executable
• git rev-parse --verify HEAD
• some ImageMagick command

I suspect this is a common operation.

The Perl cookbook or Python cookbook could be a good source of inspiration.

• Declare lazily evaluated constant (lazy_static)
• Maintain global mutable state (lazy_static)
• Unzip a tarball to a temporary directory (temdir + tar + flate2)
• Dispatch work to a thread pool (threadpool)
• Fork a short-lived thread that cheaply references data from the original thread (crossbeam)
• Access a file randomly using a memory map (memmap)
• TODO evaluate this issue and generate more recipes

Using lazy_static!. This is different from #99 in that it should also show interior mutability to change the static value after it has been initialized.

Add an example to demonstrate url::percent_encoding.

Hi, I did not see issue for the missing Rand crates examples in Basics section so I went ahead and opened it here (I hope it's ok)

• Generate random floating point numbers
• Generate random values of a custom type

I would like to create a PR for both of these snippets.
Also I would suggest to create another example Generate random numbers within a range as this seams to be a relatively common usecase.

cc @brson

Add an example to demonstrate url::form_urlencoded.

Removing this trailing URL junk seems like the kind of thing people do.

Maybe load a config file that tells the application what path to write its logs to.

The "Create and delete Gist with GitHub API" currently shows basic auth. We don't necessarily need code for an OAuth example but just a link to how you might handle more advanced auth situations.

the code formatting for many of the snippets 'breaks' when it sees quote-pairs inside raw strings r#"like "this" eg"#, it would unhighlight the word 'this'. probably because it's not highlighting the raw stirng just the "" pairs between the ## 's

I know this is probably not a bug with /this/ repository but I wouldn't know where to look to actually fix it

All major websites and many services provide restful apis. Using those has become a very important topic, be it for retrieving information from websites, interacting with common third-party service or communicating in an internal network.

Ideally, a whole chapter should be dedicated to this topic. It should explaining the following subjects, which are ordered in descending priority:

• Get from an endpoint url to the needed data; this should include the GET request, parsing json and extracting data (added in #80)
• POST a JSON body (added in #80)
• POST the contents of a file
• Set custom header and url parameters
• Iterate through paginated requests
• Tools for using advanced authentication techniques (e.g. oauth); this does not need an explicit example but rather a link to the relevant crates
• Handling errors such as rate limits

The crates.io API would be a good way to demonstrate this. A lot of their endpoints are limited to 100 elements per query, with a page=2 parameter to see more elements.

curl -sS \
  -H 'Content-Type: application/json' \
  'https://crates.io/api/v1/crates/serde/reverse_dependencies?per_page=100&page=2'

The tables in concurency.md, encoding.md and app.md are not consistent with main TOC in intro.md (categories are missing). I am assuming that these should be mirrored.
Moreover most of examples except in basics.md are missing at least one badge.

I can solve it later today.

Hitting a rate limit may either return an error for the request or return a JSON body that is different from the usual. Let's show how to deal with one or both of these cases.

https://docs.rs/memmap/*/memmap/struct.Mmap.html

Most of this page is not written!

This is pretty important for appearances, so I'll try to get to it soon, but patches still welcome. Speak up on thread if you plan to write any sections.

Right now the error handling pattern suggested by the cookbook's 'about' page, and used in at least some of the examples, looks similar to quick_main!. Seems like we should just use that.

Switch the existing examples to replace 'main' with 'quick_main!', and update the about page.

cc @dtolnay @Yamakaky

https://docs.rs/memmap/*/memmap/struct.Mmap.html

Relevant crates: temdir, tar, flate2

Come up with ideas for nice introductory examples of using reqwest, possibly in combination with other crates, that would be good to show in the Rust Cookbook. Please leave a comment here with your ideas! You don't necessarily have to write the example code yourself but PRs are always welcome!

• Make an HTTP GET request (reqwest)
• Download a file to a temporary directory (reqwest + tempdir)
• Make a partial download with HTTP range headers (reqwest)
• Query the GitHub API (reqwest + serde)
• Create and delete Gist with GitHub API (reqwest + serde)
• Use HEAD request to test whether endpoint exists (reqwest)
• Extract all links from a webpage (reqwest + select)
• Check webpage for broken links (reqwest + select)
• TODO evaluate the remaining comments on this page and decide if recipes are in scope.

Crate evaluation thread on internals.rust-lang.org

Write examples for these use cases following the existing precedent and guidelines in CONTRIBUTING.md

• Log a debug message to the console
• Log an error message to the console
• Log messages with a custom logger (added in #74)
• Enable log levels per module (added in #78)
• Log to the Unix syslog (added in #70)
• Log messages to a custom location
• Include a timestamp on log messages

Crate evaluation for log: See https://internals.rust-lang.org/t/crate-evaluation-for-2017-05-16-log/5185

Suggest ideas for other examples here if you have them!

These examples are desired to represent the url crate.

• Parse a URL from a string to a Url type
• Create a base URL by removing path segments
• Create new URLs from a base URL
• Extract the URL origin (scheme / host / port)
• Remove fragment identifiers and query pairs from a URL
• Encode binary data as application/x-www-form-urlencoded
• Percent-encode binary data

Other ideas very much welcome. Suggest here or just submit a PR.

It's quite unattractive that the index tables all have different widths. There's surely some way to style them.

https://docs.rs/threadpool

Hi some of the crate badges have wrong version on them (the link is prepared for different crate for instance clap for log)

Also in intro.md the category is "command line" instead of debugging for the log related examples.

Some of these problems are fixed in https://github.com/brson/rust-cookbook/pull/70
I will fix it later today once pulls are settled.

Basically replace all version requirements in Cargo.toml under [dependencies] with "*", then cargo test. This will notify us when a crate releases a new major version that is incompatible with our example code, meaning the example needs to be updated.

Using lazy_static! to do the initialization.

For whatever reason, this doesn't seem to be the default behavior. We definitely need to show a way to do this.

@dtolnay Hi after switching all examples with fn run() to error_chain some of the examples became quite noisy eg http://localhost:3000/net.html#parse-a-url-from-a-string-to-a-url-type
has 8 lines of code to 9 lines of error_chain maiking it hard to read

I think that we could have best of both worlds (completely copy-pastable examples and minimal noise) if we have used the expand collapse button (currently hidden along with play button) and hide the error_chain and main boiler plate by default (and be able to show it on click).

I will prepare a minimal PR for your consideration

On https://serde.rs there is an "Edit" button in the top left that takes you to GitHub's web editor for the current page. We have gotten a decent amount of use out of that. It lowers the barrier for contributing minor fixes.

Let's take what we have and make it look real nice.

Some ideas:

• Create an "Introduction" prose chapter, and sink the error handling discussion into that.
• Write a brief, motivating introduction
• Turn the TOC into a flat list of domains, like "File I/O", "Concurrency", "Math", "Processes", etc. each
  with its own page, each page is a flat list of use cases with accompanying examples
• Fill out the contributing page
• Make the alignment of badges more aesthetic

cc @branderson @dhharris @trentspi

For example, check whether a particular GitHub user exists: https://api.github.com/users/ferris-the-crab

Some but not all of these examples would work if run with play.integer32.com instead.

According to CONTRIBUTING.md:

This project is intended to be simple to contribute to, and to always have obvious next work items available.

That means it's probably important to let you know that the links and some of the formatting are broken in the contributing file. This is probably a really easy fix for someone looking to contribute. 😄

Issues I found while reading through CONTRIBUTING.md:

• [libz blitz] does not link to anything (this link is used several times throughout the file)
• [crate-tasks] does not link to anything
• ["how to read this book"] does not link to anything
• The Adding an example link at the top of the file in the navigation links does not work
• The "a note about crate representation" link in Finding what to contribute is broken and the section on the page it links to is empty
  • The section being empty is a bigger bug than the link being broken because it's not easy to know how to contribute if you were relying on that section to know which crates are being represented in the cookbook. I'm bringing this up because the file explicitly says:

    If at any time there is not something obvious to contribute, that is a bug.

• The "A note about error handling" link in Example Guidelines is broken

Hard part here will be figuring out what to do about running the examples in the test suite without actually hitting the network.