rust-lang-nursery / rust-cookbook Goto Github PK
View Code? Open in Web Editor NEWhttps://rust-lang-nursery.github.io/rust-cookbook
License: Creative Commons Zero v1.0 Universal
https://rust-lang-nursery.github.io/rust-cookbook
License: Creative Commons Zero v1.0 Universal
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.
#80 added an example that shows posting a JSON body. Let's add a separate one to post the contents of a file.
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.
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.
These examples are desired to represent the url crate.
Url
typeOther ideas very much welcome. Suggest here or just submit a PR.
For whatever reason, this doesn't seem to be the default behavior. We definitely need to show a way to do this.
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.
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.
Maybe load a config file that tells the application what path to write its logs to.
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:
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.
Removing this trailing URL junk seems like the kind of thing people do.
Add an example to demonstrate url::form_urlencoded
.
The Perl cookbook or Python cookbook could be a good source of inspiration.
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.
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.
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.
I suspect this is a common operation.
As the #38 is closed, the stubs for "Serialize a Url
" should be removed from net.md and intro.md
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!
Does anyone have non-contrived examples? Some ideas:
nm
to list symbols in the current executablegit rev-parse --verify HEAD
The bare minimum env_logger example.
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 anythingAdding an example
link at the top of the file in the navigation links does not work"a note about crate representation"
link in Finding what to contribute is broken and the section on the page it links to is empty
If at any time there is not something obvious to contribute, that is a bug.
"A note about error handling"
link in Example Guidelines is brokenUsing lazy_static!
to do the initialization.
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
Add an example to demonstrate url::percent_encoding
.
@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
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)
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
Write examples for these use cases following the existing precedent and guidelines in CONTRIBUTING.md
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!
e.g. the "read lines from file" creates "lines.txt" and dirties the directory. Could solve this in skeptic.
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'
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.
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.
Relevant crates: temdir, tar, flate2
Let's take what we have and make it look real nice.
Some ideas:
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:
For example, check whether a particular GitHub user exists: https://api.github.com/users/ferris-the-crab
Hard part here will be figuring out what to do about running the examples in the test suite without actually hitting the network.
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.
It's quite unattractive that the index tables all have different widths. There's surely some way to style them.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.