- Reformat everything now that the bug in dprint for wrapping lines with
inline code is fixed.
- Additionally, apply the formatting rules I *should have* applied the
first time, so the repo has the same style it has historically used.
Preprocessors using `pulldown-cmark-to-cmark` do not yet perform round
trips 100% correctly, and insert leading spaces and an extra initial `>`
for block quotes, so strip those. Once that is fixed upstream, this will
become a no-op, and can be removed then.
- Create an `mdbook_trpl` library package which hosts shared concerns
for the packages, e.g. error and config handling.
- Move `mdbook-trpl-note` and `mdbook-trpl-listing` into the new shared
package, with binaries at `src/bin/(note|listing)/main.rs` and the
existing libraries at `src/note/mod.rs` and `src/listing/mod.rs` with
their associated tests.
- Extract their actual shared pieces into the crate root.
- Update `tools/nostarch.sh` to build all the bins in `mdbook_trpl` at
one time.
At the moment, this doesn't do a lot except trim down the number of
packages in the repository, but it sets things up nicely to support more
preprocessors (which I am going to add shortly).
Rust recently began printing error messages which include the full path
to the source of the file with an error in it; when that path is in the
standard library, that includes the user's home directory (or similar).
A previous change (b9241f6) added support for those paths in the output
files; this one adds support to the local file paths linter.
Specifically allow exactly and only paths in the home directory which
include `.rustup` or `.cargo`.
Set `reqwest.default-features = false`, since it includes `native-tls`
by default, and explicitly opt into `rustls-tls` instead. This also
implicitly drops http2 support, but we do not use that in the examples,
so that is actually just a small win.
Contributes to rust-lang/rust#131859, which is failing because using
`native-tis` requires the environment to have an OpenSSL installation,
and the `rust-lang/rust` CI environment does not.
The `trpl`, `mdbook-trpl-note`, and `mdbook-trpl-listing` crates should
*never* be part of a host workspace: neither in `rust-lang/book` nor in
`rust-lang/rust`. They are always built as independent packages, so they
do not end up depending implicitly on the host’s workspace dependencies.
Accordingly, opt out by setting an empty `[workspace]` key in each of
the packages' `Cargo.toml` files so that they do not have to be
configured in both places they might be used.
- Produce an error on unsupported `Listing` attributes. This will
primarily prevent us from ending up with typos.
- Improve the error handling for missing attributes, and add tests to
guarantee we do what we expect.
Add `reqwest` and `scraper` dependencies to the `trpl` crate. Wrap them
in `trpl` re-exports which keep the API surface low.
Rewrite the whole first section to use `race` along with those `trpl`
re-exports to show a more “real” example of async code right form the
start, including actual concurrency, unlike the previous introduction.
Update 17.03 to account for having introduced `race` already, and update
listing numbers for rewritten 17.01.
The *inclues* for them were fixed already, but not these!
The `block_on` name is what both Tokio and smol use, but it is a bit
obscure from the point of view of introducing this material. `run` says
much more clearly what it does *for the level we care about here*, I
think.
In addition to the baseline changes, skip over non-directory code where
directories are needed to deal with things like `.DS_Store` files. Also
add a bunch of context on error causes from `std::io::Error` because it
was *impossible* to figure out exactly what the source of those were.
XML does not allow more XML to appear in the body of an attribute, but
this is not XML! It is *HTML*, since Markdown allows embedding HTML, and
HTML *does* allow embedding further `<` and `>` characters within the
attributes on the element. Accordingly, switch to `html_parser`, add a
test covering this behavior, and update `ListingBuilder` to take the
number, caption, and file name types as owned rather than as references,
since that is what `html_parser` supplies.
Additionally, refactor the guts a bit so it is easy to see the overall
logic of `rewrite_listing`, with the gnarly bits around opening and
closing the rewritten listings pushed into a method on the `State`
struct, itself renamed to `ListingState` and its `current_listing` field
renamed to `current`. This also clarifies the semantics of each part of
the rewrite operation, e.g. `ListingState::open_listing` is fallible;
`ListingState::close_listing` is not.
When I originally built this, I thought *all* “listings” had numbers and
captions, but it turns out that there are a number of places in the book
where having the overall `figure`-driven output, i.e. with a file name,
is desirable even though there is no number or caption.
A potential enhancement later would be to require a caption if a number
is present, since that seems to be what the book actually does.
Eliminate `trpl::timeout` entirely. Instead, just build the `timeout`
directly (as the rest of the section already did). Restructure the
listings as well, eliminating duplication and extraneous bits.
Use `IntervalStream` and `ReceiverStream` to show the composition of
multiple streams, along with throttling and timeouts. This will also
provide a useful foundation for discussing the relationships between
futures, tasks, and threads in the final sections of the book, since
you can accomplish the same basic API by simply substituting threads
for tasks—but with different tradeoffs!
- Rexport `tokio::fs::read_to_string` as `trpl::read_to_string`.
- Add a no-listing example for the mutable borrow example. This will
keep us honest that the code there itself compiles just fine!
This makes compiled output in listings much more reasonable. It may be
worth seeing if we can trim it down even further. (Switching to `smol`
would do that, I think, but would have other effects.)
- Update the implementation for `race` to use `futures::future::Either`
instead of duplicating the type, and update the test not to try to use
equality.
- Add a `pub use` for `tokio::task::yield_now`.
Create a `trpl::race` function which simplifies the `select` API by
ignoring the future which resolves second. Use the `race` function to
show how you can implement an even simpler `timeout` function on top of
it, i.e. showing how futures can compose nicely. With that in place,
there is enough to be able to “work up to it” in the body of the text.
Up to this point, the chapter has stuck to `join` and `join3`, as simple
function-based APIs. The `join_all` API is obviously more convenient
than those *if you can use it*, but being able to use it requires having
something which `impl Iterator` of a given type, and therefore demands a
homogeneous type, which motivates introducing `Box::pin`.
That in turn is quite annoying to work with and requires `Output =
<same>` for all the futures in the collection, because of how `join_all`
is typed (Rust does not have the ability to do do variadic types, which
is what would be necessary for `join_all` to work the way we might
want). Thus, we get a motivation for `futures::join!`, which unlike
`join_all` *can* work with heterogeneous types.
This fills out a fair bit of the text here and adds a lot of the listing
support, and outlines what remains to do text-wise.
- Incorporate a good discusion of the need to make sure that the `tx`
in this example gets dropped.
- Add more listings which show borrowing vs. moving a `tx`, covering
the full territory in that example.
- Add and test more re-exports in `trpl`.
I made a conscious choice here *not* to use `future::join_all()` because
that ends up getting into a discussion of `Pin`. I left a TODO item here
for now because I think it is probably worth getting into, and that
could be a good thing to transition to *after* this section.
