Merge branch '__rultor'

src/main/kotlin/org/objectionary/aoi/generate/PlGenerator.kt

@@ -11,9 +11,22 @@ import org.w3c.dom.Node
 import java.io.File
 
 typealias GraphAbstracts = MutableMap<String, MutableSet<Node>>
+
+/**
+ * @todo #22 this global constant need to be removed
+ */
 const val prologFile = "proloog.pl"
 
+/**
+ * Constructs Prolog facts from xmir
+ */
 class PlGenerator {
+
+    /**
+     * Generates Prolog script for each xmir file from input directory.
+     *
+     * @param path path to the input directory
+     */
     fun generatePrologScripts(path: String) {
         File(prologFile).createNewFile()
         val sourcesExtractor = SourcesExtractor()
@@ -24,12 +37,21 @@ class PlGenerator {
         rules()
     }
 
+    /**
+     * Generates Prolog script for a single [document]
+     *
+     * @param document Document from which Prolog facts will be collected
+     */
     private fun generatePrologScript(document: Document) {
+        /**
+         * @todo #22 this piece of code (5 lines below) do nothing
+         */
         val objects: MutableList<Node> = mutableListOf()
         val docObjects = document.getElementsByTagName("o")
         for (i in 0 until docObjects.length) {
             objects.add(docObjects.item(i))
         }
+        //
         val obj = document.getElementsByTagName("objects").item(0)
         val children = obj.childNodes ?: return
         for (i in 0 until children.length) {
@@ -40,7 +62,15 @@ class PlGenerator {
         }
     }
 
+    /**
+     * Recursively iterates over the children of [node] and write facts into Prolog file
+     *
+     * @param node node to be iterated over
+     */
     private fun collectNodeInfo(node: Node) {
+        /**
+         * @todo #22 refactor this method (too much nesting)
+         */
         val children = node.childNodes ?: return
         var offset = 0
         for (i in 0 until children.length) {
@@ -75,7 +105,7 @@ class PlGenerator {
     }
 
     /**
-     * @return concatenated test of bases, nu,ber of passed children, true if name == "@" else false
+     * @return concatenated text of base nodes; number of passed children; true if name == "@" else false
      */
     private fun walkDotChain(
         node: Node
@@ -105,6 +135,9 @@ class PlGenerator {
         return name
     }
 
+    /**
+     * @todo #22 this method is not used here; also it defined at SourceExtractor
+     */
     @Suppress("PARAMETER_NAME_IN_OUTER_LAMBDA")
     private fun abstracts(objects: MutableList<Node>) {
         val abstracts: GraphAbstracts = mutableMapOf()

src/main/kotlin/org/objectionary/aoi/generate/util/PrologFileWriter.kt

@@ -4,13 +4,29 @@ import org.objectionary.aoi.generate.prologFile
 import java.io.File
 
 val plFile = File(prologFile).outputStream()
-val nodes = mutableSetOf<String>() // todo write them to file
+/**
+ * @todo #22 write them to file
+ */
+val nodes = mutableSetOf<String>()
 
+
+/**
+ * Prints a "contains_attr(Obj, Attr, fact)" fact to a prolog file
+ *
+ * @param nodeName name of object
+ * @param childName name of attribute that object contain
+ */
 fun containsAttrFact(nodeName: String, childName: String) {
     plFile.write("contains_attr(${nodeName.replace('.', '-')}, ${childName.replace('.', '-')}, fact).\n".toByteArray())
     nodes.add(nodeName)
 }
 
+/**
+ * Prints a "parent(Base, Obj, fact)" fact to a prolog file
+ *
+ * @param nodeName name of base object (parent)
+ * @param childName name of derived object
+ */
 fun parentFact(nodeName: String, childName: String) {
     plFile.write("parent(${nodeName.replace('.', '-')}, ${childName.replace('.', '-')}, fact).\n".toByteArray())
 }
@@ -19,21 +35,34 @@ fun isInstanceFact(nodeName: String, childName: String) {
     plFile.write("is_instance(${nodeName.replace('.', '-')}, ${childName.replace('.', '-')}, fact).\n".toByteArray())
 }
 
+/**
+ * Prints a "dot(Obj, Fa, Attr, fact)" fact to a prolog file
+ *
+ * @param obj the name of object where dot notation is occurred
+ * @param attr the name of the free attribute to which dot notation applies
+ * @param appliedAttr the name of the attribute that is applied using dot notation
+ */
 fun appliedFact(obj: String, attr: String, appliedAttr: String) {
     plFile.write(
         ("dot(${obj.replace('.', '-')}, ${attr.replace('.', '-')}, " +
                 "${appliedAttr.replace('.', '-').replace("QQ", "qq")}, fact).\n").toByteArray()
     )
 }
 
+/**
+ * Prints a set of rules to a prolog file
+ */
 fun rules() {
-    val rules = "\n% rules\n" +
-            "contains_attr(X, Y, rule) :- parent(Z, X, _),\n" +
-            "                             contains_attr(Z, Y, _).\n" +
-            "contains_attr(X, Y, rule) :- is_instance(X, Z, fact),\n" +
-            "                             contains_attr(Z, Y, _).\n" +
-            "parent(X, Y, rule) :- parent(X, Z, fact), parent(Z, Y, fact).\n" +
-            "dot(Base, Fa, Attr, rule) :- is_instance(X, Base, fact), dot(X, Fa, Attr, _).\n"
+    val rules = """
+        
+        % rules
+        contains_attr(Obj, Attr, rule) :- parent(Base, Obj, _),
+                                     contains_attr(Base, Attr, _).
+        contains_attr(Inst, Attr, rule) :- is_instance(Inst, Obj, fact),
+                                     contains_attr(Obj, Attr, _).
+        parent(Base, Obj2, rule) :- parent(Base, Obj1, fact), parent(Obj1, Obj2, fact).
+        dot(Obj, Fa, Attr, rule) :- is_instance(Inst, Obj, fact), dot(Inst, Fa, Attr, _).
+        """.trimIndent()
 
     plFile.write(rules.toByteArray())
 }

src/main/kotlin/org/objectionary/aoi/launch/AoiLauncher.kt

@@ -6,15 +6,16 @@ import java.io.File
 import java.nio.file.Files
 import java.nio.file.Paths
 
-fun main() {
-    launchAoi("C:\\Users\\lesya\\aoi-l\\src\\test\\resources\\integration\\in\\basic\\app.xmir")
-}
-
+/**
+ * Aggregates the whole pipeline.
+ *
+ * @param path path to input directory
+ */
 fun launchAoi(path: String) {
     Files.walk(Paths.get(path))
         .filter(Files::isRegularFile)
         .forEach {
             PlGenerator().generatePrologScripts(it.toString())
             PrologInteraction().execute()
         }
-}
+}

src/main/kotlin/org/objectionary/aoi/launch/Main.kt

@@ -0,0 +1,9 @@
+package org.objectionary.aoi.launch
+
+/**
+ * @param args command line arguments
+ * - args[0] path to the folder with the program to be analyzed
+ */
+fun main(args: Array<String>) {
+    launchAoi(path = args[0])
+}

src/main/kotlin/org/objectionary/aoi/sources/SourcesExtractor.kt

@@ -22,14 +22,23 @@ typealias GraphAbstracts = MutableMap<String, MutableSet<Node>>
 
 val abstracts: GraphAbstracts = mutableMapOf()
 
-
+/**
+ * Extract information from source xmir files
+ */
 class SourcesExtractor {
     private val logger = LoggerFactory.getLogger("org.objectionary.deog.launch.DeogLauncher")
     private val sep = File.separatorChar
     companion object {
         val documents: MutableMap<Document, String> = mutableMapOf()
     }
 
+    /**
+     * Collects [documents] from input directory. Also invokes [createTempDirectories], [transformXml] and
+     * [findAbstracts] methods.
+     *
+     * @param path path to directory with xmir files
+     * @return [documents] - map with all Documents and paths to them
+     */
     fun collectDocuments(path: String): MutableMap<Document, String> {
         Files.walk(Paths.get(path))
             .filter(Files::isRegularFile)
@@ -44,15 +53,15 @@ class SourcesExtractor {
             for (i in 0 until docObjects.length) {
                 objects.add(docObjects.item(i))
             }
-            abstracts(objects)
+            findAbstracts(objects)
         }
         return documents
     }
 
     /**
-     * Creates a new xml by applying several xsl transformations to it
+     * Creates a new xml by applying several xsl transformations to it. The result is written to the output file.
      *
-     * @param inFilename to the input file
+     * @param inFilename path to the input file
      * @param outFilename path to the output file
      */
     private fun transformXml(
@@ -74,6 +83,8 @@ class SourcesExtractor {
     }
 
     /**
+     * Get Document from source xml file
+     *
      * @param filename source xml filename
      * @return generated Document
      */
@@ -87,6 +98,12 @@ class SourcesExtractor {
         return null
     }
 
+    /**
+     * Creates a new temporary directory ending with "_aoi2" for transformed xmir files
+     *
+     * @param path path to source xmir files
+     * @return path to file in temporary directory
+     */
     private fun createTempDirectories(path: String): String {
         val tmpPath =
             "${path.substringBeforeLast(sep)}_aoi2$sep${path.substringAfterLast(sep)}"
@@ -101,8 +118,14 @@ class SourcesExtractor {
         return tmpPath
     }
 
+    /**
+     * Iterates through [objects] list and collects all abstract objects into [abstracts].
+     *
+     * @param objects list of object nodes
+     * @return result of forEach
+     */
     @Suppress("PARAMETER_NAME_IN_OUTER_LAMBDA")
-    private fun abstracts(objects: MutableList<Node>) =
+    private fun findAbstracts(objects: MutableList<Node>) =
         objects.forEach {
             val name = name(it)
             if (abstract(it) != null && name != null) {

src/test/resources/integration/in/example/app.xmir

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<program ms="160"
+          name="sandbox.app"
+          source="/Users/c71n93/Programming/EOLANG/sandbox/eo/sandbox/app.eo"
+          time="2023-02-24T11:46:15.652234Z"
+          version="0.29.1">
+   <listing>+package sandbox
++alias org.eolang.io.stdout
+
+[] &gt; animal
+  [] &gt; talk
+    stdout "talk" &gt; @
+
+[] &gt; dog
+  animal &gt; @
+  [] &gt; move
+    TRUE &gt; @
+
+[x] &gt; main
+  x.move &gt; @
+
+[args...] &gt; app
+  main dog &gt; @
+</listing>
+   <errors/>
+   <sheets/>
+   <license/>
+   <metas>
+      <meta line="1">
+         <head>package</head>
+         <tail>sandbox</tail>
+         <part>sandbox</part>
+      </meta>
+      <meta line="2">
+         <head>alias</head>
+         <tail>org.eolang.io.stdout</tail>
+         <part>org.eolang.io.stdout</part>
+      </meta>
+   </metas>
+   <objects>
+      <o abstract="" line="4" name="animal" pos="0">
+         <o abstract="" line="5" name="talk" pos="2">
+            <o base="stdout" line="6" name="@" pos="4">
+               <o base="string" data="bytes" line="6" pos="11">74 61 6C 6B</o>
+            </o>
+         </o>
+      </o>
+      <o abstract="" line="8" name="dog" pos="0">
+         <o base="animal" line="9" name="@" pos="2"/>
+         <o abstract="" line="10" name="move" pos="2">
+            <o base="bool" data="bytes" line="11" name="@" pos="4">01</o>
+         </o>
+      </o>
+      <o abstract="" line="13" name="main" pos="0">
+         <o line="13" name="x" pos="1"/>
+         <o base="x" line="14" pos="2"/>
+         <o base=".move" line="14" method="" name="@" pos="3"/>
+      </o>
+      <o abstract="" line="16" name="app" pos="0">
+         <o line="16" name="args" pos="1" vararg=""/>
+         <o base="main" line="17" name="@" pos="2">
+            <o base="dog" line="17" pos="7"/>
+         </o>
+      </o>
+   </objects>
+</program>