feat(cli): ARK-336, accept '-' as a filename to mean 'read code from stdin'

Author: SuperFola

.github/workflows/ci.yml

@@ -160,6 +160,92 @@ jobs:
           echo /tmp/ArkScript/lib; ls /tmp/ArkScript/lib
           DYLD_PRINT_LIBRARIES=1 /tmp/ArkScript/bin/arkscript -e '(import std.List) (print list:map " is a function")' || exit 1
 
+  cli:
+    runs-on: ${{ matrix.os }}
+    name: Test ArkScript CLI on ${{ matrix.os }}
+    needs: [ check ]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-24.04
+          - macos-14
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+
+      - name: Setup compilers, dependencies, project and build
+        uses: ./.github/workflows/setup-compilers
+        with:
+          os_name: ${{ matrix.os }}
+          compiler: clang
+          compiler_version: 16
+          sanitizers: "On"
+          with_deps: false
+
+      - name: Execute script normally
+        run: |
+          export ARKSCRIPT_PATH=$(pwd)/lib
+          CODE='(import std.Sys) (if (!= ["1" "2" "3"] sys:args) { (print sys:args) (sys:exit 1) })'
+          echo $CODE > a.ark
+          rm -rf __arkscript__
+
+          ./build/arkscript a.ark 1 2 3
+          # the cache should be created
+          if ! [ -d __arkscript__ ]; then
+            echo "Cache folder doesn't exist"
+            exit 1
+          fi
+
+      - name: -fno-cache should not create cache folder
+        run: |
+          export ARKSCRIPT_PATH=$(pwd)/lib
+          CODE='(import std.Sys) (if (!= ["1" "2" "3"] sys:args) { (print sys:args) (sys:exit 1) })'
+          echo $CODE > a.ark
+          rm -rf __arkscript__
+          
+          ./build/arkscript -fno-cache a.ark 1 2 3
+          # -fno-cache should prevent the cache creation
+          if [ -d __arkscript__ ]; then
+            echo "Cache folder exists"
+            exit 1
+          fi
+
+      - name: Take input from stdin
+        run: |
+          export ARKSCRIPT_PATH=$(pwd)/lib
+          CODE='(import std.Sys) (if (!= ["1" "2" "3"] sys:args) { (print sys:args) (sys:exit 1) })'
+          echo $CODE > a.ark
+          rm -rf __arkscript__
+          
+          ./build/arkscript - 1 2 3 <a.ark
+          # we read from stdin, there should be no cache created
+          if [ -d __arkscript__ ]; then
+            echo "Cache folder exists"
+            exit 1
+          fi
+
+      - name: Take input from CLI with heredoc
+        run: |
+          export ARKSCRIPT_PATH=$(pwd)/lib
+          rm -rf __arkscript__
+
+          ./build/arkscript - 1 2 3 << EOF
+          (import std.Sys)
+          (if (!= ["1" "2" "3"] sys:args)
+            {
+              (print sys:args)
+              (sys:exit 1) })
+          EOF
+          # there should not be any cache generated when evaluating code from the CLI
+          if [ -d __arkscript__ ]; then
+            echo "Cache folder exists"
+            exit 1
+          fi
+
   build:
     runs-on: ${{ matrix.config.os }}
     name: ${{ matrix.config.name }}

CHANGELOG.md

@@ -10,6 +10,7 @@
 - `builtin__slice` builtin, for strings and lists: `(builtin__slice data start end [step=1])` ; **this is an experimentation and may be removed in future versions**
 - arguments of builtin macros are properly type-checked and will now raise runtime errors if the type is incorrect
 - `-fno-cache` cli option to disable the creation of the bytecode cache folder `__arkscript__`
+- in the CLI, `file` can be `-` to read code from stdin
 
 ## [4.2.0] - 2026-02-04
 ### Breaking changes

README.md

@@ -195,7 +195,6 @@ OPTIONS
         -v, --version               Display ArkScript version and exit
         --dev-info                  Display development information and exit
         -e, --eval                  Evaluate ArkScript expression
-
         -d, --debug...              Increase debug level (default: 0)
 
         -L, --lib                   Set the location of the ArkScript standard library. Paths can be
@@ -215,6 +214,7 @@ OPTIONS
         -fdump-ir                   Dump IR to file.ark.ir
         -fno-cache                  Disable the bytecode cache creation
         -c, --compile               Compile the given program to bytecode, but do not run
+        <file>                      If file is -, it reads code from stdin
         -f, --format                Format the given source file in place
         --dry-run                   Do not modify the file, only print out the changes
         --check                     Check if a file formating is correctly, without modifying it.

src/arkscript/main.cpp

@@ -101,14 +101,14 @@ int main(int argc, char** argv)
         | option("-v", "--version").set(selected, mode::version).doc("Display ArkScript version and exit")
         | option("--dev-info").set(selected, mode::dev_info).doc("Display development information and exit")
         | (
-            required("-e", "--eval").set(selected, mode::eval).doc("Evaluate ArkScript expression\n")
+            required("-e", "--eval").set(selected, mode::eval).doc("Evaluate ArkScript expression")
             & value("expression", eval_expression)
         )
         | (
             run_flags
             , (
                 required("-c", "--compile").set(selected, mode::compile).doc("Compile the given program to bytecode, but do not run")
-                & value("file", file)
+                & value("file", file).doc("If file is -, it reads code from stdin")
             )
             | value("file", file).set(selected, mode::run)
         )
@@ -166,7 +166,7 @@ int main(int argc, char** argv)
                               .append_section("BUILD DATE", fmt::format("        {}", ARK_BUILD_DATE))
                               .append_section("LICENSE", "        Mozilla Public License 2.0");
 
-    if (parse(argc, argv, cli))
+    if (auto result = parse(argc, argv, cli))
     {
         using namespace Ark;
 
@@ -186,9 +186,9 @@ int main(int argc, char** argv)
                     return std::filesystem::path(path);
                 });
             }
-            else if (Utils::fileExists("./lib"))
+            else if (Utils::fileExists("./lib") && Utils::fileExists("./lib/std/Prelude.ark"))
                 lib_paths.emplace_back("lib");
-            else
+            else if (debug > 0)
                 fmt::println("{}:  Couldn't read ARKSCRIPT_PATH environment variable", fmt::styled("Warning", fmt::fg(fmt::color::dark_orange)));
         }
 
@@ -251,7 +251,15 @@ int main(int argc, char** argv)
                 state.setDebug(debug);
                 state.setArgs(script_args);
 
-                if (!state.doFile(file, passes))
+                if (file == "-")
+                {
+                    std::string content, line;
+                    while (std::getline(std::cin, line))
+                        content += line;
+                    if (!state.doString(content, passes))
+                        return ArkErrorExitCode;
+                }
+                else if (!state.doFile(file, passes))
                     return ArkErrorExitCode;
 
                 Ark::VM vm(state);
@@ -327,6 +335,50 @@ int main(int argc, char** argv)
             }
         }
     }
+    else
+    {
+        std::cerr << "Could not parse CLI arguments" << std::endl;
+
+        auto doc_label = [](const parameter& p) {
+            if (!p.flags().empty())
+                return p.flags().front();
+            if (!p.label().empty())
+                return p.label();
+            return doc_string { "<?>" };
+        };
+
+        std::cout << "args -> parameter mapping:\n";
+        for (const auto& m : result)
+        {
+            std::cout << "#" << m.index() << " " << m.arg() << " -> ";
+            if (const parameter* p = m.param(); p)
+            {
+                std::cout << doc_label(*p) << " \t";
+                if (m.repeat() > 0)
+                {
+                    std::cout << (m.bad_repeat() ? "[bad repeat " : "[repeat ")
+                              << m.repeat() << "]";
+                }
+                if (m.blocked())
+                    std::cout << " [blocked]";
+                if (m.conflict())
+                    std::cout << " [conflict]";
+                std::cout << '\n';
+            }
+            else
+                std::cout << " [unmapped]\n";
+        }
+
+        std::cout << "missing parameters:\n";
+        for (const auto& m : result.missing())
+        {
+            if (const parameter* p = m.param(); p)
+            {
+                std::cout << doc_label(*p) << " \t";
+                std::cout << " [missing after " << m.after_index() << "]\n";
+            }
+        }
+    }
 
     return 0;
 }