Deprecate Node.Text

Node.Text was intended to get a text value from some inline nodes.
A 'text value' of a Text node is clear.

But

- BaseNode had a default implementation of Node.Text
- Lacks of GoDoc description that Node.Text is valid only for
  some inline nodes

So, some users are using Node.Text for BlockNodes.

A 'text value' for a BlockNode is not clear.

e.g. : Text value of a ListNode

- It should be contains list markers?
- What do characters concatinate List items with? newlines? spaces?
- If it contains codeblocks, codeblocks should be fenced or indented?

Now we would like to avoid such ambiguous method.

ast/ast.go

@@ -127,6 +127,8 @@ type Node interface {
  // If this node is a block node, Text returns a text value as reasonable as possible.
  // Notice that there are no 'correct' text values for the block nodes.
  // Result for the block nodes may be different from your expectation.
+ //
+ // Deprecated: Use other properties of the node to get the text value(i.e. Pragraph.Lines, Text.Value).
  Text(source []byte) []byte
 
  // HasBlankPreviousLines returns true if the row before this node is blank,
@@ -378,7 +380,9 @@ func (n *BaseNode) OwnerDocument() *Document {
  return nil
 }
 
-// Text implements Node.Text .
+// Text implements Node.Text .
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. Pragraph.Lines, Text.Value).
 func (n *BaseNode) Text(source []byte) []byte {
  var buf bytes.Buffer
  for c := n.firstChild; c != nil; c = c.NextSibling() {

ast/block.go

@@ -131,6 +131,8 @@ func (n *TextBlock) Kind() NodeKind {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. TextBlock.Lines).
 func (n *TextBlock) Text(source []byte) []byte {
  return n.Lines().Value(source)
 }
@@ -161,6 +163,8 @@ func (n *Paragraph) Kind() NodeKind {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. Paragraph.Lines).
 func (n *Paragraph) Text(source []byte) []byte {
  return n.Lines().Value(source)
 }
@@ -260,6 +264,8 @@ func (n *CodeBlock) Kind() NodeKind {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. CodeBlock.Lines).
 func (n *CodeBlock) Text(source []byte) []byte {
  return n.Lines().Value(source)
 }
@@ -320,6 +326,8 @@ func (n *FencedCodeBlock) Kind() NodeKind {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. FencedCodeBlock.Lines).
 func (n *FencedCodeBlock) Text(source []byte) []byte {
  return n.Lines().Value(source)
 }
@@ -519,6 +527,8 @@ func (n *HTMLBlock) Kind() NodeKind {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. HTMLBlock.Lines).
 func (n *HTMLBlock) Text(source []byte) []byte {
  ret := n.Lines().Value(source)
  if n.HasClosure() {

ast/inline.go

@@ -143,17 +143,25 @@ func (n *Text) Merge(node Node, source []byte) bool {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. Text.Value).
 func (n *Text) Text(source []byte) []byte {
  return n.Segment.Value(source)
 }
 
+// Value returns a value of this node.
+// SoftLineBreaks are not included in the returned value.
+func (n *Text) Value(source []byte) []byte {
+ return n.Segment.Value(source)
+}
+
 // Dump implements Node.Dump.
 func (n *Text) Dump(source []byte, level int) {
  fs := textFlagsString(n.flags)
  if len(fs) != 0 {
  fs = "(" + fs + ")"
  }
- fmt.Printf("%sText%s: \"%s\"\n", strings.Repeat(" ", level), fs, strings.TrimRight(string(n.Text(source)), "\n"))
+ fmt.Printf("%sText%s: \"%s\"\n", strings.Repeat(" ", level), fs, strings.TrimRight(string(n.Value(source)), "\n"))
 }
 
 // KindText is a NodeKind of the Text node.
@@ -258,6 +266,8 @@ func (n *String) SetCode(v bool) {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. String.Value).
 func (n *String) Text(source []byte) []byte {
  return n.Value
 }
@@ -492,20 +502,22 @@ func (n *AutoLink) URL(source []byte) []byte {
  ret := make([]byte, 0, len(n.Protocol)+s.Len()+3)
  ret = append(ret, n.Protocol...)
  ret = append(ret, ':', '/', '/')
- ret = append(ret, n.value.Text(source)...)
+ ret = append(ret, n.value.Value(source)...)
  return ret
  }
- return n.value.Text(source)
+ return n.value.Value(source)
 }
 
 // Label returns a label of this node.
 func (n *AutoLink) Label(source []byte) []byte {
- return n.value.Text(source)
+ return n.value.Value(source)
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. AutoLink.Label).
 func (n *AutoLink) Text(source []byte) []byte {
- return n.value.Text(source)
+ return n.value.Value(source)
 }
 
 // NewAutoLink returns a new AutoLink node.
@@ -547,6 +559,8 @@ func (n *RawHTML) Kind() NodeKind {
 }
 
 // Text implements Node.Text.
+//
+// Deprecated: Use other properties of the node to get the text value(i.e. RawHTML.Segments).
 func (n *RawHTML) Text(source []byte) []byte {
  return n.Segments.Value(source)
 }

ast_test.go

@@ -141,11 +141,15 @@ l4`,
  c1 = c1.FirstChild()
  c2 = c2.FirstChild()
  }
- if !bytes.Equal(c1.Text(s), []byte(cs.T1)) {
- t.Errorf("%s unmatch: %s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1)))
+ if !bytes.Equal(c1.Text(s), []byte(cs.T1)) { // nolint: staticcheck
+
+ t.Errorf("%s unmatch: %s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1))) // nolint: staticcheck
+
  }
- if !bytes.Equal(c2.Text(s), []byte(cs.T2)) {
- t.Errorf("%s(EOF) unmatch: %s", cs.Name, testutil.DiffPretty(c2.Text(s), []byte(cs.T2)))
+ if !bytes.Equal(c2.Text(s), []byte(cs.T2)) { // nolint: staticcheck
+
+ t.Errorf("%s(EOF) unmatch: %s", cs.Name, testutil.DiffPretty(c2.Text(s), []byte(cs.T2))) // nolint: staticcheck
+
  }
  })
  }
@@ -191,8 +195,8 @@ func TestASTInlineNodeText(t *testing.T) {
  md := New()
  n := md.Parser().Parse(text.NewReader(s))
  c1 := n.FirstChild().FirstChild()
- if !bytes.Equal(c1.Text(s), []byte(cs.T1)) {
- t.Errorf("%s unmatch:\n%s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1)))
+ if !bytes.Equal(c1.Text(s), []byte(cs.T1)) { // nolint: staticcheck
+ t.Errorf("%s unmatch:\n%s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1))) // nolint: staticcheck
  }
  })
  }

extension/ast_test.go

@@ -71,11 +71,15 @@ a
  c1 = c1.FirstChild()
  c2 = c2.FirstChild()
  }
- if !bytes.Equal(c1.Text(s), []byte(cs.T1)) {
- t.Errorf("%s unmatch:\n%s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1)))
+ if !bytes.Equal(c1.Text(s), []byte(cs.T1)) { // nolint: staticcheck
+
+ t.Errorf("%s unmatch:\n%s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1))) // nolint: staticcheck
+
  }
- if !bytes.Equal(c2.Text(s), []byte(cs.T2)) {
- t.Errorf("%s(EOF) unmatch: %s", cs.Name, testutil.DiffPretty(c2.Text(s), []byte(cs.T2)))
+ if !bytes.Equal(c2.Text(s), []byte(cs.T2)) { // nolint: staticcheck
+
+ t.Errorf("%s(EOF) unmatch: %s", cs.Name, testutil.DiffPretty(c2.Text(s), []byte(cs.T2))) // nolint: staticcheck
+
  }
  })
  }
@@ -108,8 +112,10 @@ func TestASTInlineNodeText(t *testing.T) {
  )
  n := md.Parser().Parse(text.NewReader(s))
  c1 := n.FirstChild().FirstChild()
- if !bytes.Equal(c1.Text(s), []byte(cs.T1)) {
- t.Errorf("%s unmatch:\n%s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1)))
+ if !bytes.Equal(c1.Text(s), []byte(cs.T1)) { // nolint: staticcheck
+
+ t.Errorf("%s unmatch:\n%s", cs.Name, testutil.DiffPretty(c1.Text(s), []byte(cs.T1))) // nolint: staticcheck
+
  }
  })
  }

renderer/html/html.go

@@ -680,7 +680,7 @@ func (r *Renderer) renderImage(w util.BufWriter, source []byte, node ast.Node, e
  _, _ = w.Write(util.EscapeHTML(util.URLEscape(n.Destination, true)))
  }
  _, _ = w.WriteString(`" alt="`)
- r.renderAttribute(w, source, n)
+ r.renderTexts(w, source, n)
  _ = w.WriteByte('"')
  if n.Title != nil {
  _, _ = w.WriteString(` title="`)
@@ -737,7 +737,7 @@ func (r *Renderer) renderText(w util.BufWriter, source []byte, node ast.Node, en
  if r.EastAsianLineBreaks != EastAsianLineBreaksNone && len(value) != 0 {
  sibling := node.NextSibling()
  if sibling != nil && sibling.Kind() == ast.KindText {
- if siblingText := sibling.(*ast.Text).Text(source); len(siblingText) != 0 {
+ if siblingText := sibling.(*ast.Text).Value(source); len(siblingText) != 0 {
  thisLastRune := util.ToRune(value, len(value)-1)
  siblingFirstRune, _ := utf8.DecodeRune(siblingText)
  if r.EastAsianLineBreaks.softLineBreak(thisLastRune, siblingFirstRune) {
@@ -770,19 +770,14 @@ func (r *Renderer) renderString(w util.BufWriter, source []byte, node ast.Node,
  return ast.WalkContinue, nil
 }
 
-func (r *Renderer) renderAttribute(w util.BufWriter, source []byte, n ast.Node) {
+func (r *Renderer) renderTexts(w util.BufWriter, source []byte, n ast.Node) {
  for c := n.FirstChild(); c != nil; c = c.NextSibling() {
  if s, ok := c.(*ast.String); ok {
  _, _ = r.renderString(w, source, s, true)
- } else if t, ok := c.(*ast.String); ok {
+ } else if t, ok := c.(*ast.Text); ok {
  _, _ = r.renderText(w, source, t, true)
- } else if !c.HasChildren() {
- r.Writer.Write(w, c.Text(source))
- if t, ok := c.(*ast.Text); ok && t.SoftLineBreak() {
- _ = w.WriteByte('\n')
- }
  } else {
- r.renderAttribute(w, source, c)
+ r.renderTexts(w, source, c)
  }
  }
 }