ascii doc generation

src/librustdoc/ascii/highlight.rs

@@ -0,0 +1,197 @@
+// 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.
+
+//! Basic html highlighting functionality
+//!
+//! This module uses libsyntax's lexer to provide token-based highlighting for
+//! the HTML documentation generated by rustdoc.
+
+use std::io;
+use std::io::prelude::*;
+use syntax::parse::lexer;
+use syntax::parse::token;
+use syntax::parse;
+
+const RED : &'static str = "\x1b[31m";
+const GREEN : &'static str = "\x1b[32m";
+const BROWN : &'static str = "\x1b[33m";
+const BLUE : &'static str = "\x1b[34m";
+const MAGENTA : &'static str = "\x1b[35m";
+const CYAN : &'static str = "\x1b[36m";
+const WHITE : &'static str = "\x1b[37m";
+const NORMAL : &'static str = "\x1b[0m";
+
+/// Highlights some source code, returning the HTML output.
+pub fn highlight(src: &str, class: Option<&str>, id: Option<&str>) -> String {
+    debug!("highlighting: ================\n{}\n==============", src);
+    let sess = parse::ParseSess::new();
+    let fm = sess.codemap().new_filemap("<stdin>".to_string(), src.to_string());
+
+    let mut out = Vec::new();
+    doit(&sess,
+         lexer::StringReader::new(&sess.span_diagnostic, fm),
+         class,
+         id,
+         &mut out).unwrap();
+    String::from_utf8_lossy(&out[..]).into_owned()
+}
+
+/// Exhausts the `lexer` writing the output into `out`.
+///
+/// The general structure for this method is to iterate over each token,
+/// possibly giving it an HTML span with a class specifying what flavor of token
+/// it's used. All source code emission is done as slices from the source map,
+/// not from the tokens themselves, in order to stay true to the original
+/// source.
+fn doit(sess: &parse::ParseSess, mut lexer: lexer::StringReader,
+        class: Option<&str>, id: Option<&str>,
+        out: &mut Write) -> io::Result<()> {
+    use syntax::parse::lexer::Reader;
+
+    //try!(write!(out, "<pre "));
+    /*match id {
+        Some(id) => try!(write!(out, "id='{}' ", id)),
+        None => {}
+    }*/
+    //try!(write!(out, "class='rust {}'>\n", class.unwrap_or("")));
+    let mut is_attribute = false;
+    let mut is_macro = false;
+    let mut is_macro_nonterminal = false;
+    loop {
+        let next = lexer.next_token();
+
+        let snip = |sp| sess.codemap().span_to_snippet(sp).unwrap();
+
+        if next.tok == token::Eof { break }
+
+        let klass = match next.tok {
+            token::Whitespace => {
+                try!(write!(out, "{}", &snip(next.sp)));
+                continue
+            },
+            token::Comment => {
+                try!(write!(out, "{}{}{}",
+                            GREEN, &snip(next.sp), NORMAL));
+                continue
+            },
+            token::Shebang(s) => {
+                try!(write!(out, "{}", s.as_str()));
+                continue
+            },
+            // If this '&' token is directly adjacent to another token, assume
+            // that it's the address-of operator instead of the and-operator.
+            // This allows us to give all pointers their own class (`Box` and
+            // `@` are below).
+            token::BinOp(token::And) if lexer.peek().sp.lo == next.sp.hi => RED,//"kw-2",
+            token::At | token::Tilde => RED,//"kw-2",
+
+            // consider this as part of a macro invocation if there was a
+            // leading identifier
+            token::Not if is_macro => { is_macro = false; BLUE/*"macro"*/ }
+
+            // operators
+            token::Eq | token::Lt | token::Le | token::EqEq | token::Ne | token::Ge | token::Gt |
+                token::AndAnd | token::OrOr | token::Not | token::BinOp(..) | token::RArrow |
+                token::BinOpEq(..) | token::FatArrow => BLUE,//"op",
+
+            // miscellaneous, no highlighting
+            token::Dot | token::DotDot | token::DotDotDot | token::Comma | token::Semi |
+                token::Colon | token::ModSep | token::LArrow | token::OpenDelim(_) |
+                token::CloseDelim(token::Brace) | token::CloseDelim(token::Paren) |
+                token::Question => "",
+            token::Dollar => {
+                if lexer.peek().tok.is_ident() {
+                    is_macro_nonterminal = true;
+                    "macro-nonterminal"
+                } else {
+                    ""
+                }
+            }
+
+            // This is the start of an attribute. We're going to want to
+            // continue highlighting it as an attribute until the ending ']' is
+            // seen, so skip out early. Down below we terminate the attribute
+            // span when we see the ']'.
+            token::Pound => {
+                is_attribute = true;
+                try!(write!(out, "\x1b[32m#"/*r"<span class='attribute'>#"*/));
+                continue
+            }
+            token::CloseDelim(token::Bracket) => {
+                if is_attribute {
+                    is_attribute = false;
+                    try!(write!(out, "]\x1b[0m"/*"[</span>"*/));
+                    continue
+                } else {
+                    ""
+                }
+            }
+
+            token::Literal(lit, _suf) => {
+                match lit {
+                    // text literals
+                    token::Byte(..) | token::Char(..) |
+                        token::Binary(..) | token::BinaryRaw(..) |
+                        token::Str_(..) | token::StrRaw(..) => GREEN,//"string",
+
+                    // number literals
+                    token::Integer(..) | token::Float(..) => RED,//"number",
+                }
+            }
+
+            // keywords are also included in the identifier set
+            token::Ident(ident, _is_mod_sep) => {
+                match &token::get_ident(ident)[..] {
+                    "ref" | "mut" => RED,//"kw-2",
+
+                    "self" => "self",
+                    "false" | "true" => GREEN,//"boolval",
+
+                    "Option" | "Result" => "prelude-ty",
+                    "Some" | "None" | "Ok" | "Err" => BROWN,//"prelude-val",
+
+                    _ if next.tok.is_any_keyword() => CYAN,//"kw",
+                    _ => {
+                        if is_macro_nonterminal {
+                            is_macro_nonterminal = false;
+                            MAGENTA//"macro-nonterminal"
+                        } else if lexer.peek().tok == token::Not {
+                            is_macro = true;
+                            MAGENTA//"macro"
+                        } else {
+                            MAGENTA//"ident"
+                        }
+                    }
+                }
+            }
+
+            // Special macro vars are like keywords
+            token::SpecialVarNt(_) => RED,//"kw-2",
+
+            token::Lifetime(..) => BLUE,//"lifetime",
+            token::DocComment(..) => BLUE,//"doccomment",
+            token::Underscore | token::Eof | token::Interpolated(..) |
+                token::MatchNt(..) | token::SubstNt(..) => "",
+        };
+
+        // as mentioned above, use the original source code instead of
+        // stringifying this token
+        let snip = sess.codemap().span_to_snippet(next.sp).unwrap();
+        if klass == "" {
+            try!(write!(out, "{}", &snip));
+        } else {
+            try!(write!(out, "{}{}{}", klass,
+                          &snip, NORMAL));
+        }
+    }
+
+    //write!(out, "</pre>\n")
+    write!(out, "\n")
+}

src/librustdoc/ascii/item_type.rs

@@ -0,0 +1,116 @@
+// 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.
+
+//! Item types.
+
+use std::fmt;
+use clean;
+
+/// Item type. Corresponds to `clean::ItemEnum` variants.
+///
+/// The search index uses item types encoded as smaller numbers which equal to
+/// discriminants. JavaScript then is used to decode them into the original value.
+/// Consequently, every change to this type should be synchronized to
+/// the `itemTypes` mapping table in `static/main.js`.
+#[derive(Copy, PartialEq, Clone, Debug)]
+pub enum ItemType {
+    Module          = 0,
+    ExternCrate     = 1,
+    Import          = 2,
+    Struct          = 3,
+    Enum            = 4,
+    Function        = 5,
+    Typedef         = 6,
+    Static          = 7,
+    Trait           = 8,
+    Impl            = 9,
+    TyMethod        = 10,
+    Method          = 11,
+    StructField     = 12,
+    Variant         = 13,
+    Macro           = 14,
+    Primitive       = 15,
+    AssociatedType  = 16,
+    Constant        = 17,
+    AssociatedConst = 18,
+}
+
+impl ItemType {
+    pub fn from_item(item: &clean::Item) -> ItemType {
+        match item.inner {
+            clean::ModuleItem(..)          => ItemType::Module,
+            clean::ExternCrateItem(..)     => ItemType::ExternCrate,
+            clean::ImportItem(..)          => ItemType::Import,
+            clean::StructItem(..)          => ItemType::Struct,
+            clean::EnumItem(..)            => ItemType::Enum,
+            clean::FunctionItem(..)        => ItemType::Function,
+            clean::TypedefItem(..)         => ItemType::Typedef,
+            clean::StaticItem(..)          => ItemType::Static,
+            clean::ConstantItem(..)        => ItemType::Constant,
+            clean::TraitItem(..)           => ItemType::Trait,
+            clean::ImplItem(..)            => ItemType::Impl,
+            clean::TyMethodItem(..)        => ItemType::TyMethod,
+            clean::MethodItem(..)          => ItemType::Method,
+            clean::StructFieldItem(..)     => ItemType::StructField,
+            clean::VariantItem(..)         => ItemType::Variant,
+            clean::ForeignFunctionItem(..) => ItemType::Function, // no ForeignFunction
+            clean::ForeignStaticItem(..)   => ItemType::Static, // no ForeignStatic
+            clean::MacroItem(..)           => ItemType::Macro,
+            clean::PrimitiveItem(..)       => ItemType::Primitive,
+            clean::AssociatedConstItem(..) => ItemType::AssociatedConst,
+            clean::AssociatedTypeItem(..)  => ItemType::AssociatedType,
+            clean::DefaultImplItem(..)     => ItemType::Impl,
+        }
+    }
+
+    pub fn from_type_kind(kind: clean::TypeKind) -> ItemType {
+        match kind {
+            clean::TypeStruct   => ItemType::Struct,
+            clean::TypeEnum     => ItemType::Enum,
+            clean::TypeFunction => ItemType::Function,
+            clean::TypeTrait    => ItemType::Trait,
+            clean::TypeModule   => ItemType::Module,
+            clean::TypeStatic   => ItemType::Static,
+            clean::TypeConst    => ItemType::Constant,
+            clean::TypeVariant  => ItemType::Variant,
+            clean::TypeTypedef  => ItemType::Typedef,
+        }
+    }
+
+    pub fn to_static_str(&self) -> &'static str {
+        match *self {
+            ItemType::Module          => "mod",
+            ItemType::ExternCrate     => "externcrate",
+            ItemType::Import          => "import",
+            ItemType::Struct          => "struct",
+            ItemType::Enum            => "enum",
+            ItemType::Function        => "fn",
+            ItemType::Typedef         => "type",
+            ItemType::Static          => "static",
+            ItemType::Trait           => "trait",
+            ItemType::Impl            => "impl",
+            ItemType::TyMethod        => "tymethod",
+            ItemType::Method          => "method",
+            ItemType::StructField     => "structfield",
+            ItemType::Variant         => "variant",
+            ItemType::Macro           => "macro",
+            ItemType::Primitive       => "primitive",
+            ItemType::AssociatedType  => "associatedtype",
+            ItemType::Constant        => "constant",
+            ItemType::AssociatedConst => "associatedconstant",
+        }
+    }
+}
+
+impl fmt::Display for ItemType {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        self.to_static_str().fmt(f)
+    }
+}

src/librustdoc/ascii/layout.rs

@@ -0,0 +1,57 @@
+// Copyright 2013 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::fmt;
+use std::io::prelude::*;
+use std::io;
+
+use externalfiles::ExternalHtml;
+
+#[derive(Clone)]
+pub struct Layout {
+    pub logo: String,
+    pub favicon: String,
+    pub external_html: ExternalHtml,
+    pub krate: String,
+    pub playground_url: String,
+}
+
+pub struct Page<'a> {
+    pub title: &'a str,
+    pub ty: &'a str,
+    pub root_path: &'a str,
+    pub description: &'a str,
+    pub keywords: &'a str
+}
+
+pub fn render<T: fmt::Display, S: fmt::Display>(
+    dst: &mut io::Write, layout: &Layout, page: &Page, sidebar: &S, t: &T)
+    -> io::Result<()>
+{
+    write!(dst, "{}", *t)
+}
+
+pub fn redirect(dst: &mut io::Write, url: &str) -> io::Result<()> {
+    // <script> triggers a redirect before refresh, so this is fine.
+    /*write!(dst,
+r##"<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta http-equiv="refresh" content="0;URL={url}">
+</head>
+<body>
+    <p>Redirecting to <a href="{url}">{url}</a>...</p>
+    <script>location.replace("{url}" + location.search + location.hash);</script>
+</body>
+</html>"##,
+    url = url,
+    )*/
+    Ok(())
+}

src/librustdoc/ascii/mod.rs

@@ -0,0 +1,16 @@
+// Copyright 2012-2015 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.
+
+pub mod highlight;
+pub mod item_type;
+pub mod format;
+pub mod layout;
+pub mod render;
+pub mod toc;