rust/src/librustdoc/externalfiles.rs

use crate::html::markdown::{ErrorCodes, IdMap, Markdown, Playground};
use crate::rustc_span::edition::Edition;
use std::fs;
use std::path::Path;
use std::str;

#[derive(Clone, Debug)]
crate struct ExternalHtml {
    /// Content that will be included inline in the <head> section of a
    /// rendered Markdown file or generated documentation
    crate in_header: String,
    /// Content that will be included inline between <body> and the content of
    /// a rendered Markdown file or generated documentation
    crate before_content: String,
    /// Content that will be included inline between the content and </body> of
    /// a rendered Markdown file or generated documentation
    crate after_content: String,
}

impl ExternalHtml {
    crate fn load(
        in_header: &[String],
        before_content: &[String],
        after_content: &[String],
        md_before_content: &[String],
        md_after_content: &[String],
        nightly_build: bool,
        diag: &rustc_errors::Handler,
        id_map: &mut IdMap,
        edition: Edition,
        playground: &Option<Playground>,
    ) -> Option<ExternalHtml> {
        let codes = ErrorCodes::from(nightly_build);
        let ih = load_external_files(in_header, diag)?;
        let bc = load_external_files(before_content, diag)?;
        let m_bc = load_external_files(md_before_content, diag)?;
        let bc = format!(
            "{}{}",
            bc,
            Markdown(&m_bc, &[], id_map, codes, edition, playground).into_string()
        );
        let ac = load_external_files(after_content, diag)?;
        let m_ac = load_external_files(md_after_content, diag)?;
        let ac = format!(
            "{}{}",
            ac,
            Markdown(&m_ac, &[], id_map, codes, edition, playground).into_string()
        );
        Some(ExternalHtml { in_header: ih, before_content: bc, after_content: ac })
    }
}

crate enum LoadStringError {
    ReadFail,
    BadUtf8,
}

crate fn load_string<P: AsRef<Path>>(
    file_path: P,
    diag: &rustc_errors::Handler,
) -> Result<String, LoadStringError> {
    let file_path = file_path.as_ref();
    let contents = match fs::read(file_path) {
        Ok(bytes) => bytes,
        Err(e) => {
            diag.struct_err(&format!("error reading `{}`: {}", file_path.display(), e)).emit();
            return Err(LoadStringError::ReadFail);
        }
    };
    match str::from_utf8(&contents) {
        Ok(s) => Ok(s.to_string()),
        Err(_) => {
            diag.struct_err(&format!("error reading `{}`: not UTF-8", file_path.display())).emit();
            Err(LoadStringError::BadUtf8)
        }
    }
}

fn load_external_files(names: &[String], diag: &rustc_errors::Handler) -> Option<String> {
    let mut out = String::new();
    for name in names {
        let s = match load_string(name, diag) {
            Ok(s) => s,
            Err(_) => return None,
        };
        out.push_str(&s);
        out.push('\n');
    }
    Some(out)
}
Format the world 2019-12-22 23:42:04 +01:00			`use crate::html::markdown::{ErrorCodes, IdMap, Markdown, Playground};`
Normalize `syntax::edition` imports. 2020-01-01 19:40:49 +01:00			`use crate::rustc_span::edition::Edition;`
Use the new fs_read_write functions in rustc internals 2018-01-10 17:58:39 +01:00			`use std::fs;`
Don't construct `PathBuf` ownership if we don't need it. 2016-10-08 22:29:10 +02:00			`use std::path::Path;`
std: Deprecate std::old_io::fs This commit deprecates the majority of std::old_io::fs in favor of std::fs and its new functionality. Some functions remain non-deprecated but are now behind a feature gate called `old_fs`. These functions will be deprecated once suitable replacements have been implemented. The compiler has been migrated to new `std::fs` and `std::path` APIs where appropriate as part of this change. 2015-02-27 06:00:43 +01:00			`use std::str;`
Transition librustdoc to 2018 edition 2019-02-23 08:40:07 +01:00
add Debug impls for the Options structs 2018-11-04 23:39:24 +01:00			`#[derive(Clone, Debug)]`
Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate struct ExternalHtml {`
Add doc comments describing fields on `externalfiles::ExternalHtml`. 2016-10-08 23:34:13 +02:00			`/// Content that will be included inline in the <head> section of a`
			`/// rendered Markdown file or generated documentation`
Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate in_header: String,`
Add doc comments describing fields on `externalfiles::ExternalHtml`. 2016-10-08 23:34:13 +02:00			`/// Content that will be included inline between <body> and the content of`
			`/// a rendered Markdown file or generated documentation`
Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate before_content: String,`
Add doc comments describing fields on `externalfiles::ExternalHtml`. 2016-10-08 23:34:13 +02:00			`/// Content that will be included inline between the content and </body> of`
			`/// a rendered Markdown file or generated documentation`
Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate after_content: String,`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 12:35:25 +02:00			`}`

			`impl ExternalHtml {`
Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate fn load(`
Format the world 2019-12-22 23:42:04 +01:00			`in_header: &[String],`
			`before_content: &[String],`
			`after_content: &[String],`
			`md_before_content: &[String],`
			`md_after_content: &[String],`
Allow making `RUSTC_BOOTSTRAP` conditional on the crate name The main change is that `UnstableOptions::from_environment` now requires an (optional) crate name. If the crate name is unknown (`None`), then the new feature is not available and you still have to use `RUSTC_BOOTSTRAP=1`. In practice this means the feature is only available for `--crate-name`, not for `#![crate_name]`; I'm interested in supporting the second but I'm not sure how. Other major changes: - Added `Session::is_nightly_build()`, which uses the `crate_name` of the session - Added `nightly_options::match_is_nightly_build`, a convenience method for looking up `--crate-name` from CLI arguments. `Session::is_nightly_build()`should be preferred where possible, since it will take into account `#![crate_name]` (I think). - Added `unstable_features` to `rustdoc::RenderOptions` There is a user-facing change here: things like `RUSTC_BOOTSTRAP=0` no longer active nightly features. In practice this shouldn't be a big deal, since `RUSTC_BOOTSTRAP` is the opposite of stable and everyone uses `RUSTC_BOOTSTRAP=1` anyway. - Add tests Check against `Cheat`, not whether nightly features are allowed. Nightly features are always allowed on the nightly channel. - Only call `is_nightly_build()` once within a function - Use booleans consistently for rustc_incremental Sessions can't be passed through threads, so `read_file` couldn't take a session. To be consistent, also take a boolean in `write_file_header`. 2020-10-10 20:27:52 +02:00			`nightly_build: bool,`
nix syntax::errors & prefer rustc_errors over errors 2020-01-09 11:18:47 +01:00			`diag: &rustc_errors::Handler,`
Format the world 2019-12-22 23:42:04 +01:00			`id_map: &mut IdMap,`
			`edition: Edition,`
			`playground: &Option<Playground>,`
			`) -> Option<ExternalHtml> {`
Allow making `RUSTC_BOOTSTRAP` conditional on the crate name The main change is that `UnstableOptions::from_environment` now requires an (optional) crate name. If the crate name is unknown (`None`), then the new feature is not available and you still have to use `RUSTC_BOOTSTRAP=1`. In practice this means the feature is only available for `--crate-name`, not for `#![crate_name]`; I'm interested in supporting the second but I'm not sure how. Other major changes: - Added `Session::is_nightly_build()`, which uses the `crate_name` of the session - Added `nightly_options::match_is_nightly_build`, a convenience method for looking up `--crate-name` from CLI arguments. `Session::is_nightly_build()`should be preferred where possible, since it will take into account `#![crate_name]` (I think). - Added `unstable_features` to `rustdoc::RenderOptions` There is a user-facing change here: things like `RUSTC_BOOTSTRAP=0` no longer active nightly features. In practice this shouldn't be a big deal, since `RUSTC_BOOTSTRAP` is the opposite of stable and everyone uses `RUSTC_BOOTSTRAP=1` anyway. - Add tests Check against `Cheat`, not whether nightly features are allowed. Nightly features are always allowed on the nightly channel. - Only call `is_nightly_build()` once within a function - Use booleans consistently for rustc_incremental Sessions can't be passed through threads, so `read_file` couldn't take a session. To be consistent, also take a boolean in `write_file_header`. 2020-10-10 20:27:52 +02:00			`let codes = ErrorCodes::from(nightly_build);`
Reduce nesting in externalfiles implementation Utilize `?` instead of and_then/map operators 2019-08-11 00:39:50 +02:00			`let ih = load_external_files(in_header, diag)?;`
			`let bc = load_external_files(before_content, diag)?;`
			`let m_bc = load_external_files(md_before_content, diag)?;`
Format the world 2019-12-22 23:42:04 +01:00			`let bc = format!(`
			`"{}{}",`
			`bc,`
rustdoc: Rename internal API fns to `into_string` to avoid surprising listed in API guidelines. 2020-07-15 12:55:40 +02:00			`Markdown(&m_bc, &[], id_map, codes, edition, playground).into_string()`
Format the world 2019-12-22 23:42:04 +01:00			`);`
Reduce nesting in externalfiles implementation Utilize `?` instead of and_then/map operators 2019-08-11 00:39:50 +02:00			`let ac = load_external_files(after_content, diag)?;`
			`let m_ac = load_external_files(md_after_content, diag)?;`
Format the world 2019-12-22 23:42:04 +01:00			`let ac = format!(`
			`"{}{}",`
			`ac,`
rustdoc: Rename internal API fns to `into_string` to avoid surprising listed in API guidelines. 2020-07-15 12:55:40 +02:00			`Markdown(&m_ac, &[], id_map, codes, edition, playground).into_string()`
Format the world 2019-12-22 23:42:04 +01:00			`);`
			`Some(ExternalHtml { in_header: ih, before_content: bc, after_content: ac })`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 12:35:25 +02:00			`}`
			`}`

Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate enum LoadStringError {`
Refactor away `load_or_return` macro. 2016-10-09 04:55:40 +02:00			`ReadFail,`
			`BadUtf8,`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 12:35:25 +02:00			`}`

Make all rustdoc functions and structs crate-private This gives warnings about dead code. 2020-11-14 23:59:58 +01:00			`crate fn load_string<P: AsRef<Path>>(`
Format the world 2019-12-22 23:42:04 +01:00			`file_path: P,`
nix syntax::errors & prefer rustc_errors over errors 2020-01-09 11:18:47 +01:00			`diag: &rustc_errors::Handler,`
Format the world 2019-12-22 23:42:04 +01:00			`) -> Result<String, LoadStringError> {`
Refactor away `load_or_return` macro. 2016-10-09 04:55:40 +02:00			`let file_path = file_path.as_ref();`
Use the new fs_read_write functions in rustc internals 2018-01-10 17:58:39 +01:00			`let contents = match fs::read(file_path) {`
			`Ok(bytes) => bytes,`
			`Err(e) => {`
replace error/warning println with structured diag 2018-05-08 20:42:53 +02:00			diag.struct_err(&format!("error reading `{}`: {}", file_path.display(), e)).emit();
Use the new fs_read_write functions in rustc internals 2018-01-10 17:58:39 +01:00			`return Err(LoadStringError::ReadFail);`
			`}`
			`};`
Refactor away `load_or_return` macro. 2016-10-09 04:55:40 +02:00			`match str::from_utf8(&contents) {`
			`Ok(s) => Ok(s.to_string()),`
			`Err(_) => {`
replace error/warning println with structured diag 2018-05-08 20:42:53 +02:00			diag.struct_err(&format!("error reading `{}`: not UTF-8", file_path.display())).emit();
Refactor away `load_or_return` macro. 2016-10-09 04:55:40 +02:00			`Err(LoadStringError::BadUtf8)`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 12:35:25 +02:00			`}`
			`}`
			`}`

nix syntax::errors & prefer rustc_errors over errors 2020-01-09 11:18:47 +01:00			`fn load_external_files(names: &[String], diag: &rustc_errors::Handler) -> Option<String> {`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 12:35:25 +02:00			`let mut out = String::new();`
`for x in xs.iter()` -> `for x in &xs` 2015-01-31 18:20:46 +01:00			`for name in names {`
replace error/warning println with structured diag 2018-05-08 20:42:53 +02:00			`let s = match load_string(name, diag) {`
Refactor away `load_or_return` macro. 2016-10-09 04:55:40 +02:00			`Ok(s) => s,`
			`Err(_) => return None,`
			`};`
			`out.push_str(&s);`
Deal with the fallout of string stabilization 2014-09-22 17:28:35 +02:00			`out.push('\n');`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 12:35:25 +02:00			`}`
			`Some(out)`
			`}`