+++ /dev/null
-// Copyright 2013 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-// This file implements LinkifyText which introduces
-// links for identifiers pointing to their declarations.
-// The approach does not cover all cases because godoc
-// doesn't have complete type information, but it's
-// reasonably good for browsing.
-
-package godoc
-
-import (
- "fmt"
- "go/ast"
- "go/doc"
- "go/token"
- "io"
- "strconv"
-)
-
-// LinkifyText HTML-escapes source text and writes it to w.
-// Identifiers that are in a "use" position (i.e., that are
-// not being declared), are wrapped with HTML links pointing
-// to the respective declaration, if possible. Comments are
-// formatted the same way as with FormatText.
-//
-func LinkifyText(w io.Writer, text []byte, n ast.Node) {
- links := linksFor(n)
-
- i := 0 // links index
- prev := "" // prev HTML tag
- linkWriter := func(w io.Writer, _ int, start bool) {
- // end tag
- if !start {
- if prev != "" {
- fmt.Fprintf(w, `</%s>`, prev)
- prev = ""
- }
- return
- }
-
- // start tag
- prev = ""
- if i < len(links) {
- switch info := links[i]; {
- case info.path != "" && info.name == "":
- // package path
- fmt.Fprintf(w, `<a href="/pkg/%s/">`, info.path)
- prev = "a"
- case info.path != "" && info.name != "":
- // qualified identifier
- fmt.Fprintf(w, `<a href="/pkg/%s/#%s">`, info.path, info.name)
- prev = "a"
- case info.path == "" && info.name != "":
- // local identifier
- if info.isVal {
- fmt.Fprintf(w, `<span id="%s">`, info.name)
- prev = "span"
- } else if ast.IsExported(info.name) {
- fmt.Fprintf(w, `<a href="#%s">`, info.name)
- prev = "a"
- }
- }
- i++
- }
- }
-
- idents := tokenSelection(text, token.IDENT)
- comments := tokenSelection(text, token.COMMENT)
- FormatSelections(w, text, linkWriter, idents, selectionTag, comments)
-}
-
-// A link describes the (HTML) link information for an identifier.
-// The zero value of a link represents "no link".
-//
-type link struct {
- path, name string // package path, identifier name
- isVal bool // identifier is defined in a const or var declaration
-}
-
-// linksFor returns the list of links for the identifiers used
-// by node in the same order as they appear in the source.
-//
-func linksFor(node ast.Node) (links []link) {
- // linkMap tracks link information for each ast.Ident node. Entries may
- // be created out of source order (for example, when we visit a parent
- // definition node). These links are appended to the returned slice when
- // their ast.Ident nodes are visited.
- linkMap := make(map[*ast.Ident]link)
-
- ast.Inspect(node, func(node ast.Node) bool {
- switch n := node.(type) {
- case *ast.Field:
- for _, n := range n.Names {
- linkMap[n] = link{}
- }
- case *ast.ImportSpec:
- if name := n.Name; name != nil {
- linkMap[name] = link{}
- }
- case *ast.ValueSpec:
- for _, n := range n.Names {
- linkMap[n] = link{name: n.Name, isVal: true}
- }
- case *ast.FuncDecl:
- linkMap[n.Name] = link{}
- case *ast.TypeSpec:
- linkMap[n.Name] = link{}
- case *ast.AssignStmt:
- // Short variable declarations only show up if we apply
- // this code to all source code (as opposed to exported
- // declarations only).
- if n.Tok == token.DEFINE {
- // Some of the lhs variables may be re-declared,
- // so technically they are not defs. We don't
- // care for now.
- for _, x := range n.Lhs {
- // Each lhs expression should be an
- // ident, but we are conservative and check.
- if n, _ := x.(*ast.Ident); n != nil {
- linkMap[n] = link{isVal: true}
- }
- }
- }
- case *ast.SelectorExpr:
- // Detect qualified identifiers of the form pkg.ident.
- // If anything fails we return true and collect individual
- // identifiers instead.
- if x, _ := n.X.(*ast.Ident); x != nil {
- // Create links only if x is a qualified identifier.
- if obj := x.Obj; obj != nil && obj.Kind == ast.Pkg {
- if spec, _ := obj.Decl.(*ast.ImportSpec); spec != nil {
- // spec.Path.Value is the import path
- if path, err := strconv.Unquote(spec.Path.Value); err == nil {
- // Register two links, one for the package
- // and one for the qualified identifier.
- linkMap[x] = link{path: path}
- linkMap[n.Sel] = link{path: path, name: n.Sel.Name}
- }
- }
- }
- }
- case *ast.CompositeLit:
- // Detect field names within composite literals. These links should
- // be prefixed by the type name.
- fieldPath := ""
- prefix := ""
- switch typ := n.Type.(type) {
- case *ast.Ident:
- prefix = typ.Name + "."
- case *ast.SelectorExpr:
- if x, _ := typ.X.(*ast.Ident); x != nil {
- // Create links only if x is a qualified identifier.
- if obj := x.Obj; obj != nil && obj.Kind == ast.Pkg {
- if spec, _ := obj.Decl.(*ast.ImportSpec); spec != nil {
- // spec.Path.Value is the import path
- if path, err := strconv.Unquote(spec.Path.Value); err == nil {
- // Register two links, one for the package
- // and one for the qualified identifier.
- linkMap[x] = link{path: path}
- linkMap[typ.Sel] = link{path: path, name: typ.Sel.Name}
- fieldPath = path
- prefix = typ.Sel.Name + "."
- }
- }
- }
- }
- }
- for _, e := range n.Elts {
- if kv, ok := e.(*ast.KeyValueExpr); ok {
- if k, ok := kv.Key.(*ast.Ident); ok {
- // Note: there is some syntactic ambiguity here. We cannot determine
- // if this is a struct literal or a map literal without type
- // information. We assume struct literal.
- name := prefix + k.Name
- linkMap[k] = link{path: fieldPath, name: name}
- }
- }
- }
- case *ast.Ident:
- if l, ok := linkMap[n]; ok {
- links = append(links, l)
- } else {
- l := link{name: n.Name}
- if n.Obj == nil && doc.IsPredeclared(n.Name) {
- l.path = builtinPkgPath
- }
- links = append(links, l)
- }
- }
- return true
- })
- return
-}
projects / dotfiles / .git / blobdiff