feat: Query parameters in interactive mode (:param) (#98)

* feat: Add :param command for query parameters in interactive mode

Add cypher-shell-style query parameters to the interactive REPL:

  :param <name> <expression>   set a parameter to a server-evaluated value
  :params                      list all set parameters
  :params clear                remove all parameters

Expressions are evaluated server-side via RETURN, giving full Cypher type
support, and may reference previously set parameters. Set parameters are
passed to every subsequent query via mg_session_run.

The parser (ParseParamCommand) and parameter store (ParamStore) live in a
new mgclient-only `params` library and are covered by unit tests. mg_memory
is extracted into its own header so the library and its test don't depend on
replxx. The REPL wiring (dispatch, server-eval, ExecuteQuery params arg) is
thin glue verified manually.

* fix: Stop replxx aborting when navigating multi-line buffers

mgconsole assembles multi-line queries itself via the continuation prompt and
does not use replxx's in-buffer multiline editing, which is buggy in the pinned
release-0.0.4. history_previous() calls prev_newline_position(_pos - 1) without
the `_pos > 0` guard its sibling history_next() has; with a newline at buffer
position 0 (navigating up through a recalled multi-line history entry) it passes
-1 and trips an assertion that aborts the process. Separately, in-buffer
multiline redraws clear to end of screen and erase already-printed output.

Patch replxx (replxx-patches/, applied via the replxx-proj PATCH_COMMAND) to add
the missing bounds guard to history_previous. This fixes the abort for any
newline-bearing buffer, including multi-line entries decoded from the history
file.

Rebind Ctrl-J (line feed, 0x0A) to commit_line so a bare newline submits the
current line like Enter instead of feeding replxx's NEW_LINE action. A multi-line
paste then submits one physical line at a time, which is what GetQuery expects,
and keeps pasted or typed newlines out of the buffer so the redraw corruption
stays unreachable for the common paste case. It does not cover newlines that
arrive from history, which is why the bounds guard is the actual crash fix.

Author: Ignition

.gitattributes

@@ -0,0 +1,3 @@
+# git apply needs LF context lines to match an LF-checked-out source tree;
+# Windows autocrlf would otherwise rewrite these to CRLF and break the patch.
+*.patch text eol=lf

src/CMakeLists.txt

@@ -119,6 +119,14 @@ if(MGCONSOLE_ON_WINDOWS)
   add_compile_options(-Wno-narrowing)
 endif()
 
+# Parameter handling (`:param`/`:params`). Kept as its own library with a
+# minimal dependency surface (mgclient only) so it can be unit tested.
+add_library(params STATIC parameters.cpp)
+add_dependencies(params mgclient)
+target_compile_definitions(params PUBLIC MGCLIENT_STATIC_DEFINE)
+target_include_directories(params PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} ${MGCLIENT_INCLUDE_DIRS})
+target_link_libraries(params ${MGCLIENT_LIBRARY})
+
 add_executable(mgconsole main.cpp interactive.cpp serial_import.cpp batch_import.cpp parsing.cpp)
 target_compile_definitions(mgconsole PRIVATE MGCLIENT_STATIC_DEFINE)
 target_include_directories(mgconsole
@@ -131,6 +139,7 @@ target_link_libraries(mgconsole
   PRIVATE
   ${GFLAGS_LIBRARY}
   utils
+  params
   ${MGCLIENT_LIBRARY}
   ${OPENSSL_LIBRARIES})
 if(MGCONSOLE_ON_WINDOWS)

src/interactive.cpp

@@ -15,16 +15,78 @@
 
 #include "interactive.hpp"
 
+#include <sstream>
 #include <thread>
 
 #include <gflags/gflags.h>
 
+#include "parameters.hpp"
 #include "utils/constants.hpp"
 
 namespace mode::interactive {
 
 using namespace std::string_literals;
 
+namespace {
+
+namespace params = query::params;
+
+// Evaluates a Cypher expression server-side and returns a copy of the resulting
+// value. Existing parameters are made available to the expression.
+mg_memory::MgValuePtr EvaluateParamExpression(mg_session *session, const std::string &expression,
+                                              const params::ParamStore &store) {
+  auto result = query::ExecuteQuery(session, "RETURN " + expression, store.AsMap().get());
+  if (result.records.empty() || mg_list_size(result.records.front().get()) == 0) {
+    throw utils::ClientQueryException("expression did not produce a value");
+  }
+  const mg_value *value = mg_list_at(result.records.front().get(), 0);
+  return mg_memory::MakeCustomUnique<mg_value>(mg_value_copy(value));
+}
+
+void ListParams(const params::ParamStore &store) {
+  if (store.Empty()) {
+    console::EchoInfo("No parameters set");
+    return;
+  }
+  for (const auto &name : store.Names()) {
+    std::ostringstream os;
+    os << name << ": ";
+    utils::PrintValue(os, store.Get(name));
+    console::EchoInfo(os.str());
+  }
+}
+
+// Handles a `:param`/`:params` command line. Query-level failures (e.g. a bad
+// expression) are reported without aborting the shell; fatal connection
+// failures propagate to the reconnect logic in Run.
+void HandleParamCommand(mg_session *session, params::ParamStore &store, const std::string &line) {
+  const auto parsed = params::ParseParamCommand(line);
+  if (!parsed.command) {
+    console::EchoFailure("Invalid parameter command", parsed.error);
+    return;
+  }
+  switch (parsed.command->kind) {
+    case params::ParamCommand::Kind::kSet:
+      try {
+        auto value = EvaluateParamExpression(session, parsed.command->expression, store);
+        store.Set(parsed.command->name, value.get());
+        console::EchoInfo("Set parameter '" + parsed.command->name + "'");
+      } catch (const utils::ClientQueryException &e) {
+        console::EchoFailure("Failed to evaluate parameter expression", e.what());
+      }
+      break;
+    case params::ParamCommand::Kind::kList:
+      ListParams(store);
+      break;
+    case params::ParamCommand::Kind::kClear:
+      store.Clear();
+      console::EchoInfo("Cleared all parameters");
+      break;
+  }
+}
+
+}  // namespace
+
 int Run(utils::bolt::Config &bolt_config, const std::string &history, bool no_history,
         bool verbose_execution_info, const format::CsvOptions &csv_opts, const format::OutputOptions &output_opts) {
   Replxx *replxx_instance = InitAndSetupReplxx();
@@ -97,6 +159,9 @@ int Run(utils::bolt::Config &bolt_config, const std::string &history, bool no_hi
     return 1;
   }
 
+  // Query parameters set via `:param`, passed to every executed query.
+  params::ParamStore param_store;
+
   console::EchoInfo("mgconsole "s + gflags::VersionString());
   console::EchoInfo("Connected to 'memgraph://" + bolt_config.host + ":" + std::to_string(bolt_config.port) + "'");
   console::EchoInfo("Type :help for shell usage");
@@ -113,7 +178,16 @@ int Run(utils::bolt::Config &bolt_config, const std::string &history, bool no_hi
     }
 
     try {
-      auto ret = query::ExecuteQuery(session.get(), query->query);
+      if (query->is_param_command) {
+        HandleParamCommand(session.get(), param_store, query->query);
+        auto history_ret = save_history();
+        if (history_ret != 0) {
+          cleanup_resources();
+          return history_ret;
+        }
+        continue;
+      }
+      auto ret = query::ExecuteQuery(session.get(), query->query, param_store.AsMap().get());
       if (ret.records.size() > 0) {
         Output(ret.header, ret.records, output_opts, csv_opts);
       }

src/parameters.cpp

@@ -0,0 +1,99 @@
+// Copyright (C) 2016-2023 Memgraph Ltd. [https://memgraph.com]
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+#include "parameters.hpp"
+
+namespace query::params {
+
+namespace {
+
+constexpr const char *kWhitespace = " \t\r\n\f\v";
+
+std::string Trim(const std::string &s) {
+  const auto begin = s.find_first_not_of(kWhitespace);
+  if (begin == std::string::npos) return "";
+  const auto end = s.find_last_not_of(kWhitespace);
+  return s.substr(begin, end - begin + 1);
+}
+
+}  // namespace
+
+ParamParse ParseParamCommand(const std::string &line) {
+  const std::string trimmed = Trim(line);
+  const auto head_end = trimmed.find_first_of(kWhitespace);
+  const std::string head = trimmed.substr(0, head_end);
+  const std::string rest = head_end == std::string::npos ? "" : Trim(trimmed.substr(head_end));
+
+  if (head == ":params") {
+    if (rest.empty()) {
+      ParamCommand command;
+      command.kind = ParamCommand::Kind::kList;
+      return {.is_param_command = true, .command = command, .error = ""};
+    }
+    if (rest == "clear") {
+      ParamCommand command;
+      command.kind = ParamCommand::Kind::kClear;
+      return {.is_param_command = true, .command = command, .error = ""};
+    }
+    return {.is_param_command = true, .command = std::nullopt, .error = "expected ':params' or ':params clear'"};
+  }
+
+  if (head != ":param") return {};  // not a parameter command
+
+  const auto name_end = rest.find_first_of(kWhitespace);
+  ParamCommand command;
+  command.kind = ParamCommand::Kind::kSet;
+  command.name = rest.substr(0, name_end);
+  command.expression = name_end == std::string::npos ? "" : Trim(rest.substr(name_end));
+
+  if (command.name.empty() || command.expression.empty()) {
+    return {.is_param_command = true, .command = std::nullopt, .error = "expected ':param <name> <expression>'"};
+  }
+
+  return {.is_param_command = true, .command = command, .error = ""};
+}
+
+bool ParamStore::Empty() const { return params_.empty(); }
+
+std::size_t ParamStore::Size() const { return params_.size(); }
+
+void ParamStore::Set(const std::string &name, const mg_value *value) {
+  params_.insert_or_assign(name, mg_memory::MakeCustomUnique<mg_value>(mg_value_copy(value)));
+}
+
+const mg_value *ParamStore::Get(const std::string &name) const {
+  const auto it = params_.find(name);
+  return it == params_.end() ? nullptr : it->second.get();
+}
+
+std::vector<std::string> ParamStore::Names() const {
+  std::vector<std::string> names;
+  names.reserve(params_.size());
+  for (const auto &[name, value] : params_) names.push_back(name);
+  return names;  // std::map keeps keys sorted
+}
+
+void ParamStore::Clear() { params_.clear(); }
+
+mg_memory::MgMapPtr ParamStore::AsMap() const {
+  auto map = mg_memory::MakeCustomUnique<mg_map>(mg_map_make_empty(static_cast<uint32_t>(params_.size())));
+  for (const auto &[name, value] : params_) {
+    // mg_map_insert copies the key and takes ownership of the value copy.
+    mg_map_insert(map.get(), name.c_str(), mg_value_copy(value.get()));
+  }
+  return map;
+}
+
+}  // namespace query::params

src/parameters.hpp

@@ -0,0 +1,79 @@
+// Copyright (C) 2016-2023 Memgraph Ltd. [https://memgraph.com]
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstddef>
+#include <map>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "utils/mg_memory.hpp"
+
+namespace query::params {
+
+/// A parsed `:param` / `:params` interactive command.
+struct ParamCommand {
+  enum class Kind {
+    kSet,    ///< `:param <name> <expression>`
+    kList,   ///< `:params`
+    kClear,  ///< `:params clear`
+  };
+
+  Kind kind;
+  std::string name;        ///< populated for kSet
+  std::string expression;  ///< populated for kSet
+};
+
+/// Result of attempting to parse a line as a parameter command.
+struct ParamParse {
+  /// True if the line is a `:param`/`:params` command (well-formed or not).
+  bool is_param_command{false};
+  /// Set iff the command parsed successfully.
+  std::optional<ParamCommand> command{std::nullopt};
+  /// Human-readable reason, set iff `is_param_command && !command`.
+  std::string error{};
+};
+
+/// Parses a single line as a parameter command.
+///
+/// Returns `is_param_command == false` for anything that is not a
+/// `:param`/`:params` command, so other command handlers can take over.
+ParamParse ParseParamCommand(const std::string &line);
+
+/// Holds the query parameters set via `:param`, owning a copy of each value,
+/// and exposes them as an `mg_map` for `mg_session_run`.
+class ParamStore {
+ public:
+  bool Empty() const;
+  std::size_t Size() const;
+
+  /// Stores a copy of `value` under `name`, overwriting any existing entry.
+  void Set(const std::string &name, const mg_value *value);
+  /// Returns the value stored under `name`, or nullptr if none.
+  const mg_value *Get(const std::string &name) const;
+  /// Returns all parameter names in sorted order.
+  std::vector<std::string> Names() const;
+  /// Removes all parameters.
+  void Clear();
+  /// Builds an `mg_map` copy of all parameters, suitable for `mg_session_run`.
+  mg_memory::MgMapPtr AsMap() const;
+
+ private:
+  std::map<std::string, mg_memory::MgValuePtr> params_;
+};
+
+}  // namespace query::params

src/utils/CMakeLists.txt

@@ -9,10 +9,24 @@ else()
 endif()
 
 get_filename_component(REPLXX_LIB_PATH "${REPLXX_PREFIX}/${MG_INSTALL_LIB_DIR}/libreplxx${REPLXX_LIB_POSTFIX}.a" ABSOLUTE)
+
+# Local fixes applied on top of the pinned replxx tag.
+find_package(Git REQUIRED)
 ExternalProject_Add(replxx-proj
         PREFIX ${REPLXX_PREFIX}
         GIT_REPOSITORY https://github.com/AmokHuginnsson/replxx.git
         GIT_TAG release-0.0.4
+        # Force an LF checkout so the LF patch below applies. Windows/MSYS2 git
+        # defaults to core.autocrlf=true, which rewrites the sources with CRLF
+        # endings and makes the patch fail with "patch does not apply" (the
+        # trailing-CR context lines no longer match). --config persists into the
+        # cloned repo, so the update-step checkout stays LF too.
+        GIT_CONFIG core.autocrlf=false
+        # --3way makes this idempotent: the patch step chains off the git
+        # update step and can re-run, and --3way no-ops cleanly when the fix is
+        # already present (plain `git apply` would error "patch does not apply").
+        PATCH_COMMAND ${GIT_EXECUTABLE} apply --3way
+        "${CMAKE_CURRENT_SOURCE_DIR}/replxx-patches/0001-history_previous-bounds-check.patch"
         CMAKE_ARGS "-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>"
         "-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}"
         "-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}"

src/utils/constants.hpp

@@ -19,7 +19,12 @@ constexpr const std::string_view kInteractiveUsage =
     "are printed out.\n\n"
     "The following interactive commands are supported:\n\n"
     "\t:help\t Print out usage for interactive mode\n"
-    "\t:quit\t Exit the shell\n";
+    "\t:quit\t Exit the shell\n"
+    "\t:param <name> <expression>\t Set a query parameter to the value of a "
+    "Cypher expression (e.g. ':param age 21 * 2'); use it in queries as "
+    "$<name>\n"
+    "\t:params\t List all currently set query parameters\n"
+    "\t:params clear\t Remove all query parameters\n";
 
 constexpr const std::string_view kDocs =
     "If you are new to Memgraph or the Cypher query language, check out these "
@@ -33,6 +38,8 @@ constexpr const std::string_view kDocs =
 constexpr const std::string_view kCommandQuit = ":quit";
 constexpr const std::string_view kCommandHelp = ":help";
 constexpr const std::string_view kCommandDocs = ":docs";
+constexpr const std::string_view kCommandParam = ":param";
+constexpr const std::string_view kCommandParams = ":params";
 
 // Supported formats.
 constexpr const std::string_view kCsvFormat = "csv";