As part of a) kakoune or user implemented b) script.kak? Viewing code files without document string markup in a declared mode

Complaints & Improvements
1

Is this just a single person use-case (me) or have wider merit?

As part of:

  • a) kakoune

or user implemented

  • b) script.kak

I thought I would ask you guys before going down the ‘Feature Request’ path, as I have never officially made one and don’t wish to add to the clutter of issues.

  • a) declaration of document markup tags as part of language filetype.kak.

  • b) user opens a file in the declared mode.

    • copies source file to temp file.
    • parses the temp file document strings and removes html / markup / other declared tags.
    • shows temp file in read-only mode / pager with syntax highlighting based on file extension.

Reading source code files without markup tags in the document strings, demonstration pseudo-code `script.kak`

Updated links have a better regex with a bigger doc-string example.
read only: https://pl.kotl.in/EMhEpMBHH?theme=darcula&readOnly=true
hack-able: https://pl.kotl.in/NZW8Ku2wL

If this can already be done, please tell me.
Cool guys. Bye :wave:

Lets say a language code file has document strings with markup like below. I would like to view the code file and authors document strings without the markup noise.

/**
 *  The {@code StdIn} class provides static methods for reading strings
 *  and numbers from standard input.
 *  These functions fall into one of four categories:
 *  <ul>
 *  <li>those for reading individual tokens from standard input, one at a time,
 *      and converting each to a number, string, or boolean
 *  <li>those for reading characters from standard input, one at a time
 *  <li>those for reading lines from standard input, one at a time
 *  <li>those for reading a sequence of values of the same type from standard input,
 *      and returning the values in an array
 *  </ul>
 *  <p>
 *  Generally, it is best not to mix functions from the different
 *  categories in the same program.
 *  <p>
 *  <b>Getting started.</b>
 *  To use this class, you must have {@code StdIn.class} in your
 *  Java classpath. If you used our autoinstaller, you should be all set.
 *  Otherwise, either download
 *  <a href = "https://introcs.cs.princeton.edu/java/code/stdlib.jar">stdlib.jar</a>
 *  and add to your Java classpath or download
 *  <a href = "https://introcs.cs.princeton.edu/java/stdlib/StdIn.java">StdIn.java</a>
 *  and put a copy in your working directory.
 *  <p>
 *  <b>Reading tokens from standard input and converting to numbers and strings.</b>
 *  You can use the following methods to read numbers, strings, and booleans
 *  from standard input one at a time:
 *  <ul>
 *  <li> {@link #isEmpty()}
 *  <li> {@link #readInt()}
 *  <li> {@link #readDouble()}
 *  <li> {@link #readString()}
 *  <li> {@link #readShort()}
 *  <li> {@link #readLong()}
 *  <li> {@link #readFloat()}
 *  <li> {@link #readByte()}
 *  <li> {@link #readBoolean()}
 *  </ul>
 *  <p>
 *  The first method returns true if standard input has no more tokens.
 *  Each other method skips over any input that is whitespace. Then, it reads
 *  the next token and attempts to convert it into a value of the specified
 *  type. If it succeeds, it returns that value; otherwise, it
 *  throws an {@link InputMismatchException}.
 *  <p>
 */

You have given me the alternate thought of just rendering the markup while viewing (easier said than done :frowning:).

Ok I’ll check out tools/doc.kak, play with it, and come back next week with some additional thought on this, thanks.

View and play the code in your browser with iframe.
I am enjoying it :smile:.

<!DOCTYPE html>
<html>
  <head>
    <style>
      body {background-color:#393834;}
      p {color:#f0f0f0; text-align:center;}
      h4 {color:#f0f0f0; text-align:center;}
      a {color:#ffa500; text-align:center;}
    </style>
  </head>
  <body>
    <p>
      Press the right hand side <em>`green`</em> play button to execute the demo code in the browser.<br />
      Then scroll to the bottom of the page to view the output.<br />
      <br /><a href="https://github.com/mawww/kakoune/blob/master/rc/tools/doc.kak" target="_blank">tools/doc.kak</a><br />
      <h4>
        Reading source code files without markup tags in the document strings, demonstration pseudo-code <em>`script.kak`</em>.
      </h4>
      <br />
      <iframe src="https://pl.kotl.in/EMhEpMBHH?theme=darcula" width="1000px" height="1200px" style="border:none;" name="demo code"></iframe>
    </p>
  </body>
</html>
2

Isn’t that basically how the :doc command works? It loads a file in AsciiDoc markup, applies some regexes to figure out where the syntax highlighting goes, then removes the markup characters leaving behind plain, human-readable text.

3

Alright going to let this one go. I did end up using the implementation below.

$ kotlinc -verbose -include-runtime -jvm-target 13 -no-reflect ParseDocumentStringsToStdOut.kt
$ rm -r META-INF
$ echo 'java ParseStringsToStdOutKt "{@:1}"' > stringstostdout

$ chmod u+x,u-w,og-rwx stringtostdout
$ chmod u-wx,og-rwx ParseStringsToStdOutKt.class

$ mv stringstostdout ~/local/bin/
$ mv ParseStringsToStdOutKt.class ~/local/classes/

# $CLASSPATH and $PATH have been set 
# Then in kak editor I run the shellit.kak command which opens stdout in a temp file

:sh stringstostdout file.java
ParseStringsToStdOut.kt 
import java.io.File
// -----------------------------------------------------------------------------
// Assumptions:
//   /** ... */
//   /*  ... */
//   docstrings are balanced
//   no string templates or regexes with enclosed docstring tags
// -----------------------------------------------------------------------------
private fun String.parseText(): String {

  val start = """/\*""".toRegex()
  val stop  = """\*/""".toRegex()

  val clean = """\{@\w+\h(.*?)\}|<[^">\n]*>|<a\hhref\h*?=\h*?"(.*)"(.*?)>""".toRegex()

  val begin = start.findAll(this)
  val endin = stop.findAll(this)

  val top = mutableListOf<Int>()
  val bot = mutableListOf<Int>()

  var count = 0

  do {
    top += begin.elementAt(count).groups[0]!!.range.first
    bot += endin.elementAt(count).groups[0]!!.range.endInclusive
    count++
  } while (begin.elementAtOrNull(count) != null)

  if (top.size != bot.size) return ""

  val tuple = top.zip(bot)
  val tsize = tuple.size
  val sb    = StringBuilder()

  if (begin.elementAt(0).groups[0]!!.range.first > 2)
     sb.append(this.substring(0, tuple[0].first))

  count = 0

  do {
    sb.append(this.substring(tuple[count].first, tuple[count].second).replace(clean, "$1$2"))

    if (count + 1 != tsize)
       sb.append(this.substring(tuple[count].second, tuple[count + 1].first))

    count++
  } while (count < tsize)

  if (bot[bot.lastIndex] < this.length - 1)
     sb.append(this.substring(tuple[tuple.lastIndex].second, this.length))

  return sb.toString()
}
// ---------------------------------------------------------------------------------------------------
private fun readFile(file: String): String {

  val origin = File(file)

  val changes = origin.readText(Charsets.UTF_8).parseText()

  check(changes.isNotEmpty()) { "ERROR: Unbalanced document strings" }

  return changes
}
// ---------------------------------------------------------------------------------------------------
fun main(args: Array<String>) {
  if (args.size != 0) {
    var index = 0
    do {
      val file = args[index].toString()
      val text = readFile(file)
      println(text)
      println("\n// --------------------------------------------------------------------------------------------------- //\n\n")
      index++
    } while (args.getOrNull(index) != null)
  } else println("Usage: ParseDocumentStrings.kt filename...")
}

Someone may be able to build on/from it, who knows. Bye :wave: