#
#
#            Nim's Runtime Library
#        (c) Copyright 2012 Andreas Rumpf
#
#    See the file "copying.txt", included in this
#    distribution, for details about the copyright.
#

## A simple XML tree generator.
##
runnableExamples:
  var g = newElement("myTag")
  g.add newText("some text")
  g.add newComment("this is comment")

  var h = newElement("secondTag")
  h.add newEntity("some entity")

  let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
  let k = newXmlTree("treeTag", [g, h], att)

  doAssert $k == """<treeTag key1="first value" key2="second value">
  <myTag>some text<!-- this is comment --></myTag>
  <secondTag>&some entity;</secondTag>
</treeTag>"""

## **See also:**
## * `xmlparser module <xmlparser.html>`_ for high-level XML parsing
## * `parsexml module <parsexml.html>`_ for low-level XML parsing
## * `htmlgen module <htmlgen.html>`_ for html code generator

import std/private/since
import macros, strtabs, strutils, sequtils

when defined(nimPreviewSlimSystem):
  import std/assertions


type
  XmlNode* = ref XmlNodeObj ## An XML tree consisting of XML nodes.
    ##
    ## Use `newXmlTree proc <#newXmlTree,string,openArray[XmlNode],XmlAttributes>`_
    ## for creating a new tree.

  XmlNodeKind* = enum ## Different kinds of XML nodes.
    xnText,           ## a text element
    xnVerbatimText,   ##
    xnElement,        ## an element with 0 or more children
    xnCData,          ## a CDATA node
    xnEntity,         ## an entity (like ``&thing;``)
    xnComment         ## an XML comment

  XmlAttributes* = StringTableRef ## An alias for a string to string mapping.
    ##
    ## Use `toXmlAttributes proc <#toXmlAttributes,varargs[tuple[string,string]]>`_
    ## to create `XmlAttributes`.

  XmlNodeObj {.acyclic.} = object
    case k: XmlNodeKind # private, use the kind() proc to read this field.
    of xnText, xnVerbatimText, xnComment, xnCData, xnEntity:
      fText: string
    of xnElement:
      fTag: string
      s: seq[XmlNode]
      fAttr: XmlAttributes
    fClientData: int    ## for other clients

const
  xmlHeader* = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n"
    ## Header to use for complete XML output.

template expect(node: XmlNode, kind: set[XmlNodeKind]) =
  ## Check the node's kind is within a set of values
  assert node.k in kind, "Got " & $node.k

template expect(node: XmlNode, kind: XmlNodeKind) =
  ## Check the node's kind equals a value
  assert node.k == kind, "Got " & $node.k

proc newXmlNode(kind: XmlNodeKind): XmlNode =
  ## Creates a new ``XmlNode``.
  result = XmlNode(k: kind)

proc newElement*(tag: sink string): XmlNode =
  ## Creates a new ``XmlNode`` of kind ``xnElement`` with the given `tag`.
  ##
  ## See also:
  ## * `newXmlTree proc <#newXmlTree,string,openArray[XmlNode],XmlAttributes>`_
  ## * [<> macro](#<>.m,untyped)
  runnableExamples:
    var a = newElement("firstTag")
    a.add newElement("childTag")
    assert a.kind == xnElement
    assert $a == """<firstTag>
  <childTag />
</firstTag>"""

  result = newXmlNode(xnElement)
  result.fTag = tag
  result.s = @[]
  # init attributes lazily to save memory

proc newText*(text: sink string): XmlNode =
  ## Creates a new ``XmlNode`` of kind ``xnText`` with the text `text`.
  runnableExamples:
    var b = newText("my text")
    assert b.kind == xnText
    assert $b == "my text"

  result = newXmlNode(xnText)
  result.fText = text

proc newVerbatimText*(text: sink string): XmlNode {.since: (1, 3).} =
  ## Creates a new ``XmlNode`` of kind ``xnVerbatimText`` with the text `text`.
  ## **Since**: Version 1.3.
  result = newXmlNode(xnVerbatimText)
  result.fText = text

proc newComment*(comment: sink string): XmlNode =
  ## Creates a new ``XmlNode`` of kind ``xnComment`` with the text `comment`.
  runnableExamples:
    var c = newComment("my comment")
    assert c.kind == xnComment
    assert $c == "<!-- my comment -->"

  result = newXmlNode(xnComment)
  result.fText = comment

proc newCData*(cdata: sink string): XmlNode =
  ## Creates a new ``XmlNode`` of kind ``xnCData`` with the text `cdata`.
  runnableExamples:
    var d = newCData("my cdata")
    assert d.kind == xnCData
    assert $d == "<![CDATA[my cdata]]>"

  result = newXmlNode(xnCData)
  result.fText = cdata

proc newEntity*(entity: string): XmlNode =
  ## Creates a new ``XmlNode`` of kind ``xnEntity`` with the text `entity`.
  runnableExamples:
    var e = newEntity("my entity")
    assert e.kind == xnEntity
    assert $e == "&my entity;"

  result = newXmlNode(xnEntity)
  result.fText = entity

proc newXmlTree*(tag: sink string, children: openArray[XmlNode],
                 attributes: XmlAttributes = nil): XmlNode =
  ## Creates a new XML tree with `tag`, `children` and `attributes`.
  ##
  ## See also:
  ## * `newElement proc <#newElement,string>`_
  ## * [<> macro](#<>.m,untyped)

  runnableExamples:
    var g = newElement("myTag")
    g.add newText("some text")
    g.add newComment("this is comment")
    var h = newElement("secondTag")
    h.add newEntity("some entity")
    let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
    let k = newXmlTree("treeTag", [g, h], att)

    doAssert $k == """<treeTag key1="first value" key2="second value">
  <myTag>some text<!-- this is comment --></myTag>
  <secondTag>&some entity;</secondTag>
</treeTag>"""

  result = newXmlNode(xnElement)
  result.fTag = tag
  newSeq(result.s, children.len)
  for i in 0..children.len-1: result.s[i] = children[i]
  result.fAttr = attributes

proc text*(n: XmlNode): lent string {.inline.} =
  ## Gets the associated text with the node `n`.
  ##
  ## `n` can be a CDATA, Text, comment, or entity node.
  ##
  ## See also:
  ## * `text= proc <#text=,XmlNode,string>`_ for text setter
  ## * `tag proc <#tag,XmlNode>`_ for tag getter
  ## * `tag= proc <#tag=,XmlNode,string>`_ for tag setter
  ## * `innerText proc <#innerText,XmlNode>`_
  runnableExamples:
    var c = newComment("my comment")
    assert $c == "<!-- my comment -->"
    assert c.text == "my comment"

  n.expect {xnText, xnComment, xnCData, xnEntity}
  result = n.fText

proc `text=`*(n: XmlNode, text: sink string) {.inline.} =
  ## Sets the associated text with the node `n`.
  ##
  ## `n` can be a CDATA, Text, comment, or entity node.
  ##
  ## See also:
  ## * `text proc <#text,XmlNode>`_ for text getter
  ## * `tag proc <#tag,XmlNode>`_ for tag getter
  ## * `tag= proc <#tag=,XmlNode,string>`_ for tag setter
  runnableExamples:
    var e = newEntity("my entity")
    assert $e == "&my entity;"
    e.text = "a new entity text"
    assert $e == "&a new entity text;"

  n.expect {xnText, xnComment, xnCData, xnEntity}
  n.fText = text

proc tag*(n: XmlNode): lent string {.inline.} =
  ## Gets the tag name of `n`.
  ##
  ## `n` has to be an ``xnElement`` node.
  ##
  ## See also:
  ## * `text proc <#text,XmlNode>`_ for text getter
  ## * `text= proc <#text=,XmlNode,string>`_ for text setter
  ## * `tag= proc <#tag=,XmlNode,string>`_ for tag setter
  ## * `innerText proc <#innerText,XmlNode>`_
  runnableExamples:
    var a = newElement("firstTag")
    a.add newElement("childTag")
    assert $a == """<firstTag>
  <childTag />
</firstTag>"""
    assert a.tag == "firstTag"

  n.expect xnElement
  result = n.fTag

proc `tag=`*(n: XmlNode, tag: sink string) {.inline.} =
  ## Sets the tag name of `n`.
  ##
  ## `n` has to be an ``xnElement`` node.
  ##
  ## See also:
  ## * `text proc <#text,XmlNode>`_ for text getter
  ## * `text= proc <#text=,XmlNode,string>`_ for text setter
  ## * `tag proc <#tag,XmlNode>`_ for tag getter
  runnableExamples:
    var a = newElement("firstTag")
    a.add newElement("childTag")
    assert $a == """<firstTag>
  <childTag />
</firstTag>"""
    a.tag = "newTag"
    assert $a == """<newTag>
  <childTag />
</newTag>"""

  n.expect xnElement
  n.fTag = tag

proc rawText*(n: XmlNode): string {.inline.} =
  ## Returns the underlying 'text' string by reference.
  ##
  ## This is only used for speed hacks.
  when defined(gcDestructors):
    result = move(n.fText)
  else:
    shallowCopy(result, n.fText)

proc rawTag*(n: XmlNode): string {.inline.} =
  ## Returns the underlying 'tag' string by reference.
  ##
  ## This is only used for speed hacks.
  when defined(gcDestructors):
    result = move(n.fTag)
  else:
    shallowCopy(result, n.fTag)

proc innerText*(n: XmlNode): string =
  ## Gets the inner text of `n`:
  ##
  ## - If `n` is `xnText` or `xnEntity`, returns its content.
  ## - If `n` is `xnElement`, runs recursively on each child node and
  ##   concatenates the results.
  ## - Otherwise returns an empty string.
  ##
  ## See also:
  ## * `text proc <#text,XmlNode>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newText("my text")
    f.add newComment("my comment")
    f.add newEntity("my entity")
    assert $f == "<myTag>my text<!-- my comment -->&my entity;</myTag>"
    assert innerText(f) == "my textmy entity"

  proc worker(res: var string, n: XmlNode) =
    case n.k
    of xnText, xnEntity:
      res.add(n.fText)
    of xnElement:
      for sub in n.s:
        worker(res, sub)
    else:
      discard

  result = ""
  worker(result, n)

proc add*(father, son: XmlNode) {.inline.} =
  ## Adds the child `son` to `father`.
  ## `father` must be of `xnElement` type
  ##
  ## See also:
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  ## * `delete proc <#delete,XmlNode,Natural>`_
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newText("my text")
    f.add newElement("sonTag")
    f.add newEntity("my entity")
    assert $f == "<myTag>my text<sonTag />&my entity;</myTag>"

  father.expect xnElement
  add(father.s, son)

proc add*(father: XmlNode, sons: openArray[XmlNode]) {.inline.} =
  ## Adds the children `sons` to `father`.
  ## `father` must be of `xnElement` type
  ##
  ## See also:
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  ## * `delete proc <#delete,XmlNode,Natural>`_
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add(@[newText("my text"), newElement("sonTag"), newEntity("my entity")])
    assert $f == "<myTag>my text<sonTag />&my entity;</myTag>"

  father.expect xnElement
  add(father.s, sons)


proc insert*(father, son: XmlNode, index: int) {.inline.} =
  ## Inserts the child `son` to a given position in `father`.
  ##
  ## `father` must be of `xnElement` kind.
  ##
  ## See also:
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `delete proc <#delete,XmlNode,Natural>`_
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newElement("first")
    f.insert(newElement("second"), 0)
    assert $f == """<myTag>
  <second />
  <first />
</myTag>"""

  father.expect xnElement
  if len(father.s) > index:
    insert(father.s, son, index)
  else:
    insert(father.s, son, len(father.s))

proc insert*(father: XmlNode, sons: openArray[XmlNode], index: int) {.inline.} =
  ## Inserts the children openArray[`sons`] to a given position in `father`.
  ##
  ## `father` must be of `xnElement` kind.
  ##
  ## See also:
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `delete proc <#delete,XmlNode,Natural>`_
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newElement("first")
    f.insert([newElement("second"), newElement("third")], 0)
    assert $f == """<myTag>
  <second />
  <third />
  <first />
</myTag>"""

  father.expect xnElement
  if len(father.s) > index:
    insert(father.s, sons, index)
  else:
    insert(father.s, sons, len(father.s))

proc delete*(n: XmlNode, i: Natural) =
  ## Deletes the `i`'th child of `n`.
  ##
  ## See also:
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newElement("first")
    f.insert(newElement("second"), 0)
    f.delete(0)
    assert $f == """<myTag>
  <first />
</myTag>"""

  n.expect xnElement
  n.s.delete(i)

proc delete*(n: XmlNode, slice: Slice[int]) =
  ## Deletes the items `n[slice]` of `n`.
  ##
  ## See also:
  ## * `delete proc <#delete.XmlNode,int>`_
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newElement("first")
    f.insert([newElement("second"), newElement("third")], 0)
    f.delete(0..1)
    assert $f == """<myTag>
  <first />
</myTag>"""

  n.expect xnElement
  n.s.delete(slice)

proc replace*(n: XmlNode, i: Natural, replacement: openArray[XmlNode]) =
  ## Replaces the `i`'th child of `n` with `replacement` openArray.
  ##
  ## `n` must be of `xnElement` kind.
  ##
  ## See also:
  ## * `replace proc <#replace.XmlNode,Slice[int],openArray[XmlNode]>`_
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `delete proc <#delete,XmlNode,Natural>`_
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newElement("first")
    f.insert(newElement("second"), 0)
    f.replace(0, @[newElement("third"), newElement("fourth")])
    assert $f == """<myTag>
  <third />
  <fourth />
  <first />
</myTag>"""

  n.expect xnElement
  n.s.delete(i)
  n.s.insert(replacement, i)

proc replace*(n: XmlNode, slice: Slice[int], replacement: openArray[XmlNode]) =
  ## Deletes the items `n[slice]` of `n`.
  ##
  ## `n` must be of `xnElement` kind.
  ##
  ## See also:
  ## * `replace proc <#replace.XmlNode,int,openArray[XmlNode]>`_
  ## * `add proc <#add,XmlNode,XmlNode>`_
  ## * `add proc <#add,XmlNode,openArray[XmlNode]>`_
  ## * `delete proc <#delete,XmlNode,Natural>`_
  ## * `delete proc <#delete.XmlNode,Slice[int]>`_
  ## * `insert proc <#insert,XmlNode,XmlNode,int>`_
  ## * `insert proc <#insert,XmlNode,openArray[XmlNode],int>`_
  runnableExamples:
    var f = newElement("myTag")
    f.add newElement("first")
    f.insert([newElement("second"), newElement("fifth")], 0)
    f.replace(0..1, @[newElement("third"), newElement("fourth")])
    assert $f == """<myTag>
  <third />
  <fourth />
  <first />
</myTag>"""

  n.expect xnElement
  n.s.delete(slice)
  n.s.insert(replacement, slic<style>pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008800 } /* Keyword.Pseudo */
.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.highlight .na { color: #336699 } /* Name.Attribute */
.highlight .nb { color: #003388 } /* Name.Builtin */
.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
.highlight .nd { color: #555555 } /* Name.Decorator */
.highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.highlight .nl { color: #336699; font-style: italic } /* Name.Label */
.highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.highlight .py { color: #336699; font-weight: bold } /* Name.Property */
.highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #336699 } /* Name.Variable */
.highlight .ow { color: #008800 } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */
.highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */
.highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */
.highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */
.highlight .vc { color: #336699 } /* Name.Variable.Class */
.highlight .vg { color: #dd7700 } /* Name.Variable.Global */
.highlight .vi { color: #3333bb } /* Name.Variable.Instance */
.highlight .vm { color: #336699 } /* Name.Variable.Magic */
.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */</style><div class="highlight"><pre><span></span><span class="c">#</span>
<span class="c">#</span>
<span class="c">#              Nim&#39;s Runtime Library</span>
<span class="c">#        (c) Copyright 2021 Nim Contributors</span>
<span class="c">#</span>
<span class="c">#    See the file &quot;copying.txt&quot;, included in this</span>
<span class="c">#    distribution, for details about the copyright.</span>
<span class="c">#</span>

<span class="sd">## This module provides some high performance string operations.</span>
<span class="sd">##</span>
<span class="sd">## Experimental API, subject to change.</span>

<span class="k">const</span><span class="w"> </span><span class="n">whitespaces</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="sc">&#39; &#39;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;</span><span class="se">\t</span><span class="sc">&#39;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;</span><span class="se">\v</span><span class="sc">&#39;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;</span><span class="se">\r</span><span class="sc">&#39;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;</span><span class="se">\l</span><span class="sc">&#39;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;</span><span class="se">\f</span><span class="sc">&#39;</span><span class="p">}</span>

<span class="k">proc</span><span class="w"> </span><span class="nf">add</span><span class="o">*</span><span class="p">(</span><span class="n">x</span><span class="p">:</span><span class="w"> </span><span class="kd">var</span><span class="w"> </span><span class="nb">string</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">:</span><span class="w"> </span><span class="n">openArray</span><span class="o">[</span><span class="nb">char</span><span class="o">]</span><span class="p">)</span><span class="w"> </span><span class="o">=</span>
<span class="w">  </span><span class="sd">## Concatenates `x` and `y` in place. `y` must not overlap with `x` to</span>
<span class="w">  </span><span class="sd">## allow future `memcpy` optimizations.</span>
<span class="w">  </span><span class="c"># Use `{.noalias.}` ?</span>
<span class="w">  </span><span class="k">let</span><span class="w"> </span><span class="n">n</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">x</span><span class="p">.</span><span class="n">len</span>
<span class="w">  </span><span class="n">x</span><span class="p">.</span><span class="n">setLen</span><span class="w"> </span><span class="n">n</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="p">.</span><span class="n">len</span>
<span class="w">    </span><span class="c"># pending https://github.com/nim-lang/Nim/issues/14655#issuecomment-643671397</span>
<span class="w">    </span><span class="c"># use x.setLen(n + y.len, isInit = false)</span>
<span class="w">  </span><span class="kd">var</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span>
<span class="w">  </span><span class="k">while</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">y</span><span class="p">.</span><span class="n">len</span><span class="p">:</span>
<span class="w">    </span><span class="n">x</span><span class="o">[</span><span class="n">n</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">i</span><span class="o">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">y</span><span class="o">[</span><span class="n">i</span><span class="o">]</span>
<span class="w">    </span><span class="n">i</span><span class="p">.</span><span class="n">inc</span>
<span class="w">  </span><span class="c"># xxx use `nimCopyMem(x[n].addr, y[0].addr, y.len)` after some refactoring</span>

<span class="k">func</span><span class="w"> </span><span class="nf">stripSlice</span><span class="p">(</span><span class="n">s</span><span class="p">:</span><span class="w"> </span><span class="n">openArray</span><span class="o">[</span><span class="nb">char</span><span class="o">]</span><span class="p">,</span><span class="w"> </span><span class="n">leading</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kp">true</span><span class="p">,</span><span class="w"> </span><span class="n">trailing</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kp">true</span><span class="p">,</span><span class="w"> </span><span class="n">chars</span><span class="p">:</span><span class="w"> </span><span class="nb">set</span><span class="o">[</span><span class="nb">char</span><span class="o">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">whitespaces</span><span class="p">):</span><span class="w"> </span><span class="n">Slice</span><span class="o">[</span><span class="nb">int</span><span class="o">]</span><span class="w"> </span><span class="o">=</span>
<span class="w">  </span><span class="sd">## Returns the slice range of `s` which is stripped `chars`.</span>
<span class="w">  </span><span class="n">runnableExamples</span><span class="p">:</span>
<span class="w">    </span><span class="n">assert</span><span class="w"> </span><span class="n">stripSlice</span><span class="p">(</span><span class="s">&quot; abc  &quot;</span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="p">..</span><span class="w"> </span><span class="mi">3</span>
<span class="w">  </span><span class="kd">var</span>
<span class="w">    </span><span class="n">first</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span>
<span class="w">    </span><span class="n">last</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">high</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="n">leading</span><span class="p">:</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="n">first</span><span class="w"> </span><span class="o">&lt;=</span><span class="w"> </span><span class="n">last</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">s</span><span class="o">[</span><span class="n">first</span><span class="o">]</span><span class="w"> </span><span class="ow">in</span><span class="w"> </span><span class="n">chars</span><span class="p">:</span><span class="w"> </span><span class="n">inc</span><span class="p">(</span><span class="n">first</span><span class="p">)</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="n">trailing</span><span class="p">:</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="n">last</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="n">first</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">s</span><span class="o">[</span><span class="n">last</span><span class="o">]</span><span class="w"> </span><span class="ow">in</span><span class="w"> </span><span class="n">chars</span><span class="p">:</span><span class="w"> </span><span class="n">dec</span><span class="p">(</span><span class="n">last</span><span class="p">)</span>
<span class="w">  </span><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="