rust/src/librustdoc/externalfiles.rs

// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

use std::fs;
use std::path::Path;
use std::str;
use errors;
use syntax::feature_gate::UnstableFeatures;
use html::markdown::{IdMap, ErrorCodes, Markdown};
use std::cell::RefCell;

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

impl ExternalHtml {
    pub fn load(in_header: &[String], before_content: &[String], after_content: &[String],
                md_before_content: &[String], md_after_content: &[String], diag: &errors::Handler,
                id_map: &mut IdMap)
            -> Option<ExternalHtml> {
        let codes = ErrorCodes::from(UnstableFeatures::from_environment().is_nightly_build());
        load_external_files(in_header, diag)
            .and_then(|ih|
                load_external_files(before_content, diag)
                    .map(|bc| (ih, bc))
            )
            .and_then(|(ih, bc)|
                load_external_files(md_before_content, diag)
                    .map(|m_bc| (ih,
                            format!("{}{}", bc, Markdown(&m_bc, &[], RefCell::new(id_map), codes))))
            )
            .and_then(|(ih, bc)|
                load_external_files(after_content, diag)
                    .map(|ac| (ih, bc, ac))
            )
            .and_then(|(ih, bc, ac)|
                load_external_files(md_after_content, diag)
                    .map(|m_ac| (ih, bc,
                            format!("{}{}", ac, Markdown(&m_ac, &[], RefCell::new(id_map), codes))))
            )
            .map(|(ih, bc, ac)|
                ExternalHtml {
                    in_header: ih,
                    before_content: bc,
                    after_content: ac,
                }
            )
    }
}

pub enum LoadStringError {
    ReadFail,
    BadUtf8,
}

pub fn load_string<P: AsRef<Path>>(file_path: P, diag: &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: &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)
}
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`// Copyright 2014 The Rust Project Developers. See the COPYRIGHT`
			`// file at the top-level directory of this distribution and at`
			`// http://rust-lang.org/COPYRIGHT.`
			`//`
			`// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or`
			`// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license`
			`// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your`
			`// option. This file may not be copied, modified, or distributed`
			`// except according to those terms.`

Use the new fs_read_write functions in rustc internals 2018-01-10 08:58:39 -08:00			`use std::fs;`
Don't construct `PathBuf` ownership if we don't need it. 2016-10-08 16:29:10 -04: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-26 21:00:43 -08:00			`use std::str;`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`use errors;`
Further extract error code switch Removes dependency on UnstableFeatures from markdown rendering 2018-07-22 11:10:19 -06:00			`use syntax::feature_gate::UnstableFeatures;`
Remove global derive_id and reset_ids functions Previously these functions relied on TLS but we can instead thread the relevant state through explicitly. 2018-07-22 07:25:00 -06:00			`use html::markdown::{IdMap, ErrorCodes, Markdown};`
			`use std::cell::RefCell;`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00
sed -i -s 's/#\[deriving(/#\[derive(/g' */.rs 2015-01-03 22:54:18 -05:00			`#[derive(Clone)]`
Add themes option 2018-01-20 22:16:46 +01:00			`pub struct ExternalHtml {`
Add doc comments describing fields on `externalfiles::ExternalHtml`. 2016-10-08 17:34:13 -04:00			`/// Content that will be included inline in the <head> section of a`
			`/// rendered Markdown file or generated documentation`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`pub in_header: String,`
Add doc comments describing fields on `externalfiles::ExternalHtml`. 2016-10-08 17:34:13 -04:00			`/// Content that will be included inline between <body> and the content of`
			`/// a rendered Markdown file or generated documentation`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`pub before_content: String,`
Add doc comments describing fields on `externalfiles::ExternalHtml`. 2016-10-08 17:34:13 -04:00			`/// Content that will be included inline between the content and </body> of`
			`/// a rendered Markdown file or generated documentation`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`pub after_content: String`
			`}`

			`impl ExternalHtml {`
Add markdown-[before\|after]-content options 2017-05-08 14:25:01 +02:00			`pub fn load(in_header: &[String], before_content: &[String], after_content: &[String],`
Remove global derive_id and reset_ids functions Previously these functions relied on TLS but we can instead thread the relevant state through explicitly. 2018-07-22 07:25:00 -06:00			`md_before_content: &[String], md_after_content: &[String], diag: &errors::Handler,`
			`id_map: &mut IdMap)`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`-> Option<ExternalHtml> {`
Further extract error code switch Removes dependency on UnstableFeatures from markdown rendering 2018-07-22 11:10:19 -06:00			`let codes = ErrorCodes::from(UnstableFeatures::from_environment().is_nightly_build());`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`load_external_files(in_header, diag)`
Make `ExternalHtml::load` short-circuited. 2016-10-08 23:53:57 -04:00			`.and_then(\|ih\|`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`load_external_files(before_content, diag)`
Make `ExternalHtml::load` short-circuited. 2016-10-08 23:53:57 -04:00			`.map(\|bc\| (ih, bc))`
			`)`
Add markdown-[before\|after]-content options 2017-05-08 14:25:01 +02:00			`.and_then(\|(ih, bc)\|`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`load_external_files(md_before_content, diag)`
Remove global derive_id and reset_ids functions Previously these functions relied on TLS but we can instead thread the relevant state through explicitly. 2018-07-22 07:25:00 -06:00			`.map(\|m_bc\| (ih,`
			`format!("{}{}", bc, Markdown(&m_bc, &[], RefCell::new(id_map), codes))))`
Add markdown-[before\|after]-content options 2017-05-08 14:25:01 +02:00			`)`
Make `ExternalHtml::load` short-circuited. 2016-10-08 23:53:57 -04:00			`.and_then(\|(ih, bc)\|`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`load_external_files(after_content, diag)`
Make `ExternalHtml::load` short-circuited. 2016-10-08 23:53:57 -04:00			`.map(\|ac\| (ih, bc, ac))`
			`)`
Add markdown-[before\|after]-content options 2017-05-08 14:25:01 +02:00			`.and_then(\|(ih, bc, ac)\|`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`load_external_files(md_after_content, diag)`
Remove global derive_id and reset_ids functions Previously these functions relied on TLS but we can instead thread the relevant state through explicitly. 2018-07-22 07:25:00 -06:00			`.map(\|m_ac\| (ih, bc,`
			`format!("{}{}", ac, Markdown(&m_ac, &[], RefCell::new(id_map), codes))))`
Add markdown-[before\|after]-content options 2017-05-08 14:25:01 +02:00			`)`
Make `ExternalHtml::load` short-circuited. 2016-10-08 23:53:57 -04:00			`.map(\|(ih, bc, ac)\|`
			`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 03:35:25 -07:00			`}`
			`}`

Refactor away `load_or_return` macro. 2016-10-08 22:55:40 -04:00			`pub enum LoadStringError {`
			`ReadFail,`
			`BadUtf8,`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`}`

replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			`pub fn load_string<P: AsRef<Path>>(file_path: P, diag: &errors::Handler)`
			`-> Result<String, LoadStringError>`
			`{`
Refactor away `load_or_return` macro. 2016-10-08 22:55:40 -04:00			`let file_path = file_path.as_ref();`
Use the new fs_read_write functions in rustc internals 2018-01-10 08:58:39 -08:00			`let contents = match fs::read(file_path) {`
			`Ok(bytes) => bytes,`
			`Err(e) => {`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05: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 08:58:39 -08:00			`return Err(LoadStringError::ReadFail);`
			`}`
			`};`
Refactor away `load_or_return` macro. 2016-10-08 22:55:40 -04:00			`match str::from_utf8(&contents) {`
			`Ok(s) => Ok(s.to_string()),`
			`Err(_) => {`
replace error/warning println with structured diag 2018-05-08 13:42:53 -05:00			diag.struct_err(&format!("error reading `{}`: not UTF-8", file_path.display())).emit();
Refactor away `load_or_return` macro. 2016-10-08 22:55:40 -04:00			`Err(LoadStringError::BadUtf8)`
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. 2014-06-28 03:35:25 -07:00			`}`
			`}`
			`}`

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