1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! HTML formatting module
13 //! This module contains a large number of `fmt::Show` implementations for
14 //! various types in `rustdoc::clean`. These implementations all currently
15 //! assume that HTML output is desired, although it may be possible to redesign
16 //! them in the future to instead emit any format desired.
19 use std::string::String;
26 use html::item_type::ItemType;
28 use html::render::{cache_key, current_location_key};
30 /// Helper to render an optional visibility with a space after it (if the
31 /// visibility is preset)
32 pub struct VisSpace(pub Option<ast::Visibility>);
33 /// Similarly to VisSpace, this structure is used to render a function style with a
35 pub struct FnStyleSpace(pub ast::FnStyle);
36 /// Wrapper struct for properly emitting a method declaration.
37 pub struct Method<'a>(pub &'a clean::SelfTy, pub &'a clean::FnDecl);
40 pub fn get(&self) -> Option<ast::Visibility> {
41 let VisSpace(v) = *self; v
46 pub fn get(&self) -> ast::FnStyle {
47 let FnStyleSpace(v) = *self; v
51 impl fmt::Show for clean::Generics {
52 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
53 if self.lifetimes.len() == 0 && self.type_params.len() == 0 { return Ok(()) }
54 try!(f.write("<".as_bytes()));
56 for (i, life) in self.lifetimes.iter().enumerate() {
58 try!(f.write(", ".as_bytes()));
60 try!(write!(f, "{}", *life));
63 if self.type_params.len() > 0 {
64 if self.lifetimes.len() > 0 {
65 try!(f.write(", ".as_bytes()));
68 for (i, tp) in self.type_params.iter().enumerate() {
70 try!(f.write(", ".as_bytes()))
72 try!(f.write(tp.name.as_bytes()));
74 if tp.bounds.len() > 0 {
75 try!(f.write(": ".as_bytes()));
76 for (i, bound) in tp.bounds.iter().enumerate() {
78 try!(f.write(" + ".as_bytes()));
80 try!(write!(f, "{}", *bound));
85 try!(f.write(">".as_bytes()));
90 impl fmt::Show for clean::Lifetime {
91 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
92 try!(f.write("'".as_bytes()));
93 try!(f.write(self.get_ref().as_bytes()));
98 impl fmt::Show for clean::TyParamBound {
99 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
101 clean::RegionBound => {
102 f.write("::".as_bytes())
104 clean::TraitBound(ref ty) => {
111 impl fmt::Show for clean::Path {
112 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
114 try!(f.write("::".as_bytes()))
117 for (i, seg) in self.segments.iter().enumerate() {
119 try!(f.write("::".as_bytes()))
121 try!(f.write(seg.name.as_bytes()));
123 if seg.lifetimes.len() > 0 || seg.types.len() > 0 {
124 try!(f.write("<".as_bytes()));
125 let mut comma = false;
126 for lifetime in seg.lifetimes.iter() {
128 try!(f.write(", ".as_bytes()));
131 try!(write!(f, "{}", *lifetime));
133 for ty in seg.types.iter() {
135 try!(f.write(", ".as_bytes()));
138 try!(write!(f, "{}", *ty));
140 try!(f.write(">".as_bytes()));
147 /// Used when rendering a `ResolvedPath` structure. This invokes the `path`
148 /// rendering function with the necessary arguments for linking to a local path.
149 fn resolved_path(w: &mut fmt::Formatter, did: ast::DefId, p: &clean::Path,
150 print_all: bool) -> fmt::Result {
151 path(w, p, print_all,
153 if ast_util::is_local(did) || cache.paths.contains_key(&did) {
154 Some(("../".repeat(loc.len())).to_strbuf())
156 match *cache.extern_locations.get(&did.krate) {
157 render::Remote(ref s) => Some(s.to_strbuf()),
159 Some(("../".repeat(loc.len())).to_strbuf())
161 render::Unknown => None,
166 match cache.paths.find(&did) {
168 Some(&(ref fqp, shortty)) => Some((fqp.clone(), shortty))
173 fn path(w: &mut fmt::Formatter, path: &clean::Path, print_all: bool,
174 root: |&render::Cache, &[String]| -> Option<String>,
175 info: |&render::Cache| -> Option<(Vec<String> , ItemType)>)
178 // The generics will get written to both the title and link
179 let mut generics = String::new();
180 let last = path.segments.last().unwrap();
181 if last.lifetimes.len() > 0 || last.types.len() > 0 {
183 generics.push_str("<");
184 for lifetime in last.lifetimes.iter() {
185 if counter > 0 { generics.push_str(", "); }
187 generics.push_str(format!("{}", *lifetime).as_slice());
189 for ty in last.types.iter() {
190 if counter > 0 { generics.push_str(", "); }
192 generics.push_str(format!("{}", *ty).as_slice());
194 generics.push_str(">");
197 let loc = current_location_key.get().unwrap();
198 let cache = cache_key.get().unwrap();
199 let abs_root = root(&**cache, loc.as_slice());
200 let rel_root = match path.segments.get(0).name.as_slice() {
201 "self" => Some("./".to_owned()),
206 let amt = path.segments.len() - 1;
209 let mut root = String::from_str(root.as_slice());
210 for seg in path.segments.slice_to(amt).iter() {
211 if "super" == seg.name.as_slice() ||
212 "self" == seg.name.as_slice() {
213 try!(write!(w, "{}::", seg.name));
215 root.push_str(seg.name.as_slice());
217 try!(write!(w, "<a class='mod'
218 href='{}index.html'>{}</a>::",
225 for seg in path.segments.slice_to(amt).iter() {
226 try!(write!(w, "{}::", seg.name));
232 match info(&**cache) {
233 // This is a documented path, link to it!
234 Some((ref fqp, shortty)) if abs_root.is_some() => {
235 let mut url = String::from_str(abs_root.unwrap().as_slice());
236 let to_link = fqp.slice_to(fqp.len() - 1);
237 for component in to_link.iter() {
238 url.push_str(component.as_slice());
242 item_type::Module => {
243 url.push_str(fqp.last().unwrap().as_slice());
244 url.push_str("/index.html");
247 url.push_str(shortty.to_static_str());
249 url.push_str(fqp.last().unwrap().as_slice());
250 url.push_str(".html");
254 try!(write!(w, "<a class='{}' href='{}' title='{}'>{}</a>",
255 shortty, url, fqp.connect("::"), last.name));
259 try!(write!(w, "{}", last.name));
262 try!(write!(w, "{}", generics.as_slice()));
266 /// Helper to render type parameters
267 fn tybounds(w: &mut fmt::Formatter,
268 typarams: &Option<Vec<clean::TyParamBound> >) -> fmt::Result {
270 Some(ref params) => {
271 try!(write!(w, ":"));
272 for (i, param) in params.iter().enumerate() {
274 try!(write!(w, " + "));
276 try!(write!(w, "{}", *param));
284 impl fmt::Show for clean::Type {
285 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
287 clean::TyParamBinder(id) => {
288 let m = cache_key.get().unwrap();
289 f.write(m.typarams.get(&ast_util::local_def(id)).as_bytes())
291 clean::Generic(did) => {
292 let m = cache_key.get().unwrap();
293 f.write(m.typarams.get(&did).as_bytes())
295 clean::ResolvedPath{ did, ref typarams, ref path } => {
296 try!(resolved_path(f, did, path, false));
297 tybounds(f, typarams)
299 clean::Self(..) => f.write("Self".as_bytes()),
300 clean::Primitive(prim) => {
302 ast::TyInt(ast::TyI) => "int",
303 ast::TyInt(ast::TyI8) => "i8",
304 ast::TyInt(ast::TyI16) => "i16",
305 ast::TyInt(ast::TyI32) => "i32",
306 ast::TyInt(ast::TyI64) => "i64",
307 ast::TyUint(ast::TyU) => "uint",
308 ast::TyUint(ast::TyU8) => "u8",
309 ast::TyUint(ast::TyU16) => "u16",
310 ast::TyUint(ast::TyU32) => "u32",
311 ast::TyUint(ast::TyU64) => "u64",
312 ast::TyFloat(ast::TyF32) => "f32",
313 ast::TyFloat(ast::TyF64) => "f64",
314 ast::TyFloat(ast::TyF128) => "f128",
316 ast::TyBool => "bool",
317 ast::TyChar => "char",
319 f.write(s.as_bytes())
321 clean::Closure(ref decl, ref region) => {
322 write!(f, "{style}{lifetimes}|{args}|{bounds}\
323 {arrow, select, yes{ -> {ret}} other{}}",
324 style = FnStyleSpace(decl.fn_style),
325 lifetimes = if decl.lifetimes.len() == 0 {
328 format!("<{:#}>", decl.lifetimes)
330 args = decl.decl.inputs,
331 arrow = match decl.decl.output {
335 ret = decl.decl.output,
337 let mut ret = String::new();
340 ret.push_str(format!(": {}",
345 for bound in decl.bounds.iter() {
347 clean::RegionBound => {}
348 clean::TraitBound(ref t) => {
354 ret.push_str(format!("{}",
362 clean::Proc(ref decl) => {
363 write!(f, "{style}{lifetimes}proc({args}){bounds}\
364 {arrow, select, yes{ -> {ret}} other{}}",
365 style = FnStyleSpace(decl.fn_style),
366 lifetimes = if decl.lifetimes.len() == 0 {
369 format_strbuf!("<{:#}>", decl.lifetimes)
371 args = decl.decl.inputs,
372 bounds = if decl.bounds.len() == 0 {
375 let mut m = decl.bounds
377 .map(|s| s.to_str().to_strbuf());
380 m.collect::<Vec<String>>().connect(" + "))
382 arrow = match decl.decl.output { clean::Unit => "no", _ => "yes" },
383 ret = decl.decl.output)
385 clean::BareFunction(ref decl) => {
386 write!(f, "{}{}fn{}{}",
387 FnStyleSpace(decl.fn_style),
388 match decl.abi.as_slice() {
389 "" => " extern ".to_strbuf(),
390 "\"Rust\"" => "".to_strbuf(),
391 s => format_strbuf!(" extern {} ", s)
396 clean::Tuple(ref typs) => {
397 try!(f.write("(".as_bytes()));
398 for (i, typ) in typs.iter().enumerate() {
400 try!(f.write(", ".as_bytes()))
402 try!(write!(f, "{}", *typ));
404 f.write(")".as_bytes())
406 clean::Vector(ref t) => write!(f, "[{}]", **t),
407 clean::FixedVector(ref t, ref s) => {
408 write!(f, "[{}, ..{}]", **t, *s)
410 clean::String => f.write("str".as_bytes()),
411 clean::Bool => f.write("bool".as_bytes()),
412 clean::Unit => f.write("()".as_bytes()),
413 clean::Bottom => f.write("!".as_bytes()),
414 clean::Unique(ref t) => write!(f, "~{}", **t),
415 clean::Managed(ref t) => write!(f, "@{}", **t),
416 clean::RawPointer(m, ref t) => {
419 clean::Mutable => "mut ",
420 clean::Immutable => "",
423 clean::BorrowedRef{ lifetime: ref l, mutability, type_: ref ty} => {
425 Some(ref l) => format!("{} ", *l),
428 write!(f, "&{}{}{}",
431 clean::Mutable => "mut ",
432 clean::Immutable => "",
440 impl fmt::Show for clean::Arguments {
441 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
442 for (i, input) in self.values.iter().enumerate() {
443 if i > 0 { try!(write!(f, ", ")); }
444 if input.name.len() > 0 {
445 try!(write!(f, "{}: ", input.name));
447 try!(write!(f, "{}", input.type_));
453 impl fmt::Show for clean::FnDecl {
454 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
455 write!(f, "({args}){arrow, select, yes{ -> {ret}} other{}}",
457 arrow = match self.output { clean::Unit => "no", _ => "yes" },
462 impl<'a> fmt::Show for Method<'a> {
463 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
464 let Method(selfty, d) = *self;
465 let mut args = String::new();
467 clean::SelfStatic => {},
468 clean::SelfValue => args.push_str("self"),
469 clean::SelfOwned => args.push_str("~self"),
470 clean::SelfBorrowed(Some(ref lt), clean::Immutable) => {
471 args.push_str(format!("&{} self", *lt).as_slice());
473 clean::SelfBorrowed(Some(ref lt), clean::Mutable) => {
474 args.push_str(format!("&{} mut self", *lt).as_slice());
476 clean::SelfBorrowed(None, clean::Mutable) => {
477 args.push_str("&mut self");
479 clean::SelfBorrowed(None, clean::Immutable) => {
480 args.push_str("&self");
483 for (i, input) in d.inputs.values.iter().enumerate() {
484 if i > 0 || args.len() > 0 { args.push_str(", "); }
485 if input.name.len() > 0 {
486 args.push_str(format!("{}: ", input.name).as_slice());
488 args.push_str(format!("{}", input.type_).as_slice());
491 "({args}){arrow, select, yes{ -> {ret}} other{}}",
493 arrow = match d.output { clean::Unit => "no", _ => "yes" },
498 impl fmt::Show for VisSpace {
499 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
501 Some(ast::Public) => write!(f, "pub "),
502 Some(ast::Inherited) | None => Ok(())
507 impl fmt::Show for FnStyleSpace {
508 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
510 ast::UnsafeFn => write!(f, "unsafe "),
511 ast::NormalFn => Ok(())
516 impl fmt::Show for clean::ViewPath {
517 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
519 clean::SimpleImport(ref name, ref src) => {
520 if *name == src.path.segments.last().unwrap().name {
521 write!(f, "use {};", *src)
523 write!(f, "use {} = {};", *name, *src)
526 clean::GlobImport(ref src) => {
527 write!(f, "use {}::*;", *src)
529 clean::ImportList(ref src, ref names) => {
530 try!(write!(f, "use {}::\\{", *src));
531 for (i, n) in names.iter().enumerate() {
533 try!(write!(f, ", "));
535 try!(write!(f, "{}", *n));
543 impl fmt::Show for clean::ImportSource {
544 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
546 Some(did) => resolved_path(f, did, &self.path, true),
548 for (i, seg) in self.path.segments.iter().enumerate() {
550 try!(write!(f, "::"))
552 try!(write!(f, "{}", seg.name));
560 impl fmt::Show for clean::ViewListIdent {
561 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
564 let path = clean::Path {
566 segments: vec!(clean::PathSegment {
567 name: self.name.clone(),
568 lifetimes: Vec::new(),
572 resolved_path(f, did, &path, false)
574 _ => write!(f, "{}", self.name),