Document timezone and add Exmaple to markdown generation

Signed-off-by: Lehlogonolo Poole <[email protected]>

Author: yetnt

docs/libs/timezone.md

@@ -12,6 +12,7 @@
 import com.jaiva.interpreter.libs.Globals;
 import com.jaiva.interpreter.runtime.IConfig;
 import com.jaiva.tokenizer.*;
+import com.jaiva.tokenizer.tokens.TSymbol;
 import com.jaiva.tokenizer.tokens.Token;
 import com.jaiva.tokenizer.tokens.specific.TArrayVar;
 import com.jaiva.tokenizer.tokens.specific.TDocsComment;
@@ -364,7 +365,7 @@ public static ArrayList<Token<?>> parseTokens(String filePath, boolean returnVfs
         ArrayList<Token<?>> tokens = new ArrayList<>();
         MultipleLinesOutput m = null;
         BlockChain b = null;
-        Scanner scanner = null;
+        Scanner scanner;
         try {
             scanner = new Scanner(myObj);
         } catch (FileNotFoundException e) {
@@ -394,8 +395,7 @@ public static ArrayList<Token<?>> parseTokens(String filePath, boolean returnVfs
                                 tks.remove(t);
                                 continue;
                             }
-                            if (comment == null || (!(l instanceof TArrayVar) && !(l instanceof TUnknownScalar)
-                                    && !(l instanceof TFunction)))
+                            if (comment == null || !(l instanceof TSymbol))
                                 continue;
                             JDoc doc = new JDoc(lineNum, comment.trim());
                             l.tooltip = doc;
@@ -404,7 +404,7 @@ public static ArrayList<Token<?>> parseTokens(String filePath, boolean returnVfs
                         }
                     }
                     comment = null;
-                    tokens.addAll((ArrayList<Token<?>>) tks);
+                    tokens.addAll(tks);
                 }
                 case BlockChain blockChain -> {
                     m = null;
@@ -418,12 +418,11 @@ public static ArrayList<Token<?>> parseTokens(String filePath, boolean returnVfs
                             + ((TDocsComment) token1.value()).comment;
                 }
                 case Token<?> token -> {
-                    TokenDefault t = ((TokenDefault) token.value());
+                    TokenDefault t = token.value();
                     if (returnVfs && !t.exportSymbol) {
                         // dont do anythin.
                     } else if (comment != null
-                            && ((t instanceof TArrayVar) || (t instanceof TUnknownScalar)
-                            || (t instanceof TFunction))) {
+                            && t instanceof TSymbol) {
 
                         JDoc doc = new JDoc(lineNum, comment.trim());
                         t.tooltip = doc;

src/main/java/com/jaiva/Main.java

@@ -78,14 +78,14 @@ private void run(IConfig<?> i, Path outputDir, boolean globals) throws IOExcepti
         } else if (option == 'y') {
             ArrayList<ArrayList<TokenDefault>> buckets = Buckets.of(
                     new ArrayList<>(exportables),
-                    TVariable.class,
-                    TFunction.class);
+                    TFunction.class,
+                    TVariable.class);
             printToFile();
             for (int j = 0; j < buckets.size(); j++) {
                 ArrayList<TokenDefault> bucket = buckets.get(j);
                 printToFile(
                         new MarkDownLiteral(
-                                (j == 0 ? "Variables" : "Functions")
+                                (j == 0 ? "Functions" : "Variables")
                         ).title(MarkDownLiteral.Title.SUBTITLE).toString()
                 );
                 for (TokenDefault t : bucket) {
@@ -208,8 +208,6 @@ private void printSymbolToFile(char option, TokenDefault symbol) throws Tokenize
 
         printToFile();
         printToFile(jDoc.getDescription());
-        // TODO: When example JDoc tag is added, add here.
-        // printToFile();
 
         if (!jDoc.getParameters().isEmpty()) {
             printToFile();
@@ -237,6 +235,17 @@ private void printSymbolToFile(char option, TokenDefault symbol) throws Tokenize
             );
         }
 
+        if (!jDoc.getExample().isEmpty()) {
+            printToFile();
+            printToFile(new MarkDownLiteral("Example:").bold().toString());
+            printToFile(
+                    MarkDownLiteral.asCodeBlock(
+                            jDoc.getExample(),
+                            "jaiva"
+                    )
+            );
+        }
+
         if (!jDoc.getNote().isEmpty()) {
             printToFile();
             printToFile(

src/main/java/com/jaiva/ToMarkdown.java

@@ -6,6 +6,8 @@
 
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
+import java.util.function.BiFunction;
 
 /**
  * "vfs" stands for Variable FunctionS. It's a class that extends HashMap and in term inherits all it's properties.
@@ -103,4 +105,62 @@ public ArrayList<Token<?>> toTokenList() {
         this.forEach((s, mv) -> tokens.add(mv.getValue().token.toToken()));
         return tokens;
     }
+
+    /**
+     * Sorts the keys of the Vfs in alphabetical order.
+     */
+    public void sortKeys() {
+        ArrayList<String> keys = new ArrayList<>(this.keySet());
+        keys.sort(String::compareTo);
+        HashMap<String, MapValue> sorted = new HashMap<>();
+        for (String key : keys) {
+            sorted.put(key, this.get(key));
+        }
+        this.clear();
+        this.putAll(sorted);
+    }
+
+    public ArrayList<MapValue> sortKeys(BiFunction<String, String, Integer> comparator, boolean returnSorted) {
+        ArrayList<String> keys = new ArrayList<>(this.keySet());
+        keys.sort(comparator::apply);
+        HashMap<String, MapValue> sorted = new HashMap<>();
+        ArrayList<MapValue> sortedValues = new ArrayList<>();
+        for (String key : keys) {
+            MapValue mv = this.get(key);
+            sorted.put(key, mv);
+            sortedValues.add(mv);
+        }
+        this.clear();
+        this.putAll(sorted);
+        return returnSorted ? sortedValues : null;
+    }
+
+    /**
+     * Sorts the keys of the Vfs giving priority to the provided top keys.
+     * The top keys will appear first in the order they are provided, followed by the rest in alphabetical order.
+     * @param topKeys The keys to prioritize.
+     */
+    public void sortWithKeyPriority(String ...topKeys) {
+        ArrayList<String> keys = new ArrayList<>(this.keySet());
+        ArrayList<String> topKeysList = new ArrayList<>(List.of(topKeys));
+        keys.sort((a, b) -> {
+            boolean aIsTop = topKeysList.contains(a);
+            boolean bIsTop = topKeysList.contains(b);
+            if (aIsTop && bIsTop) {
+                return Integer.compare(topKeysList.indexOf(a), topKeysList.indexOf(b));
+            } else if (aIsTop) {
+                return -1;
+            } else if (bIsTop) {
+                return 1;
+            } else {
+                return a.compareTo(b);
+            }
+        });
+        HashMap<String, MapValue> sorted = new HashMap<>();
+        for (String key : keys) {
+            sorted.put(key, this.get(key));
+        }
+        this.clear();
+        this.putAll(sorted);
+    }
 }

src/main/java/com/jaiva/interpreter/Vfs.java

@@ -29,8 +29,20 @@ public TimeZone() {
                         new ArrayList<>(zoneIds.stream().map(Pair::getSecond).toList()),
                         -1,
                         JDoc.builder()
-                                .addDesc("The complete list of timezone variable constants")
+                                .addDesc("The complete list of IANA format timezone constants.")
                                 .sinceVersion("4.2.0")
+                                .addExample("""
+                                        tsea "jaiva/timezone"!
+                                        
+                                        @ Get all timezone constants
+                                        maak list <- tz_getAll!
+                                        @ Print everything with Etc prefix
+                                        colonize item with list ->
+                                            if (item ? "Etc") ->
+                                                khuluma(item)!
+                                            <~
+                                        <~
+                                        """)
                                 .build()
                 ), new ArrayList<>(zoneIds.stream().map(Pair::getSecond).toList()));
         getAll.freeze();

src/main/java/com/jaiva/interpreter/libs/time/TimeZone.java

@@ -18,6 +18,7 @@ public MarkDownLiteral(String input) {
         literal.add(input);
     }
 
+
     /**
      * Applies bold formatting to the literal.
      *
@@ -69,7 +70,7 @@ public MarkDownLiteral blockQuote() {
      */
     public MarkDownLiteral linkTo(String URL) {
         literal.addFirst("[");
-        literal.add("](\"" + URL + "\")");
+        literal.add("](" + URL + ")");
         return this;
     }
 
@@ -106,6 +107,44 @@ public MarkDownLiteral comment() {
         return this;
     }
 
+    /**
+     * Wraps the input list of strings in a Markdown code block with the specified language.
+     *
+     * @param input The list of strings to be wrapped.
+     * @param languageIdentifier The language identifier for the code block.
+     * @return An ArrayList of strings representing the formatted code block.
+     */
+    public static ArrayList<String> asCodeBlock(ArrayList<String> input, String languageIdentifier) {
+        ArrayList<String> out = new ArrayList<>();
+        out.add("```" + languageIdentifier);
+        out.addAll(input);
+        out.add("```");
+        return out;
+    }
+
+    /**
+     * Converts headers and rows into a Markdown table format.
+     *
+     * @param headers The list of header strings.
+     * @param rows The list of rows, where each row is a list of strings.
+     * @return An ArrayList of strings representing the formatted Markdown table.
+     */
+    public static ArrayList<String> asTable(ArrayList<String> headers, ArrayList<ArrayList<String>> rows) {
+        ArrayList<String> out = new ArrayList<>();
+        // Create header row
+        String headerRow = "| " + String.join(" | ", headers) + " |";
+        out.add(headerRow);
+        // Create separator row
+        String separatorRow = "| " + String.join(" | ", headers.stream().map(h -> "---").toArray(String[]::new)) + " |";
+        out.add(separatorRow);
+        // Create data rows
+        for (ArrayList<String> row : rows) {
+            String dataRow = "| " + String.join(" | ", row) + " |";
+            out.add(dataRow);
+        }
+        return out;
+    }
+
     /**
      * Creates a GitHub-style blockquote with a specific alert type.
      *