Files
qelectrotech-source-mirror/sources/scripting/qetscripting.cpp
T
ispyisail eba258f6cd Add JavaScript scripting: --run and "Run Script..." (bugtracker #162)
Following up on my own comments there: a deliberately small, mostly
read-only scripting surface, exposed to scripts as a single global
`qet` object (QetScriptApi) built on QJSEngine rather than an embedded
Python interpreter -- no new toolchain to package (QJSEngine ships in
every Qt SDK QET already targets, via the Qml module), no GIL, no
version pinning, automatic reflection of the QObject-derived core
classes' own methods with no hand-written binding layer.

## What a script can do

- Read the model: project title, file path, folio count/titles,
  element/conductor counts per folio.
- Trigger the same operations the --export-* CLI flags already do
  (pdf/png/svg/cables/wires/bom/wiring/nets/links/info), plus
  set-titleblock and save -- thin wrappers around CLIExport::run(),
  reusing its already-tested logic rather than duplicating it.

Deliberately NOT in this version: creating or editing diagram
geometry, undo integration, driving the GUI. All explicitly out of
scope per the discussion on #162.

## Two entry points, both built and tested

- `qelectrotech --run script.js project.qet` -- headless/CI.
- Projet > "Exécuter un script..." -- an interactive macro against the
  currently open project. Export/save calls act on the project's file
  on disk (see QetScriptApi's class comment for why), so unsaved GUI
  edits aren't visible to the script; save first if that matters.

## Optional dependency, not a hard requirement

Qt::Qml is probed the same way QtPdf already is in this codebase:
QUIET, non-fatal, behind a QET_HAS_SCRIPTING compile definition. A
build without it compiles and links identically; the CLI flag and
menu action are simply absent (main.cpp) or compile to a clear
"not available" stderr message rather than silently disappearing
(qetscripting.cpp), matching the existing QtPdf pattern rather than
introducing a new one.

One real bug caught building this, not assumed away: my first pass
conditionally excluded the new source files from QET_SRC_FILES behind
`if(QET_HAS_SCRIPTING)` inside qet_compilation_vars.cmake -- but that
file is included before QET_HAS_SCRIPTING is set in the top-level
CMakeLists.txt, so the variable didn't exist yet at that point and the
files were silently never compiled, only caught by an undefined-symbol
link error. Fixed by following the QtPdf file's own precedent:
compile the files unconditionally, guard their Qt::Qml-dependent
content internally instead.

## Verified

Qt6, build clean, ctest 6/6.

- Headless: a script reading project/folio/element/conductor counts,
  calling exportInfo() and exportPdf() against a real project --
  correct JSON, a real single-page PDF confirmed with `file`.
  Error paths: a thrown script exception reports file:line:message and
  exit 1; missing script/project arguments exit 2 (matching
  CLIExport's own usage-error convention); a missing project file is
  reported and does not hang.
- Corpus: the same read-model script run against all 24 shipped
  example projects, 0 failures.
- GUI: "Exécuter un script..." opens a real file dialog filtered to
  *.js, running the picked script against the live open project
  produced the exact expected JSON export file, and the application
  was still fully responsive afterward.

Refs #162.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-16 19:44:14 +12:00

127 lines
3.7 KiB
C++

/*
Copyright 2006-2026 The QElectroTech Team
This file is part of QElectroTech.
QElectroTech 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 2 of the License, or
(at your option) any later version.
QElectroTech 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 QElectroTech. If not, see <http://www.gnu.org/licenses/>.
*/
#include "qetscripting.h"
#include "qetscriptapi.h"
#include "../qetproject.h"
#include <QFile>
#include <QFileInfo>
#include <QTextStream>
#ifdef QET_HAS_SCRIPTING
#include <QJSEngine>
#endif
namespace {
QTextStream out(stdout);
QTextStream err(stderr);
}
namespace QetScripting {
bool isRunRequest(const QStringList &args)
{
return args.contains(QStringLiteral("--run"));
}
#ifdef QET_HAS_SCRIPTING
int run(const QStringList &args)
{
const int idx = args.indexOf(QStringLiteral("--run"));
const QString script_path = args.value(idx + 1);
const QString project_path = args.value(idx + 2);
if (script_path.isEmpty() || project_path.isEmpty()) {
err << "Usage: qelectrotech --run <script.js> <project.qet>\n";
return 2;
}
if (!QFileInfo::exists(script_path)) {
err << "Script not found: " << script_path << "\n";
return 2;
}
if (!QFileInfo::exists(project_path)) {
err << "Project not found: " << project_path << "\n";
return 2;
}
QETProject project(project_path);
if (project.state() != QETProject::Ok) {
err << "Failed to open project: " << project_path
<< " (state " << project.state() << ")\n";
return 1;
}
return runOnProject(script_path, &project) ? 0 : 1;
}
bool runOnProject(const QString &scriptPath, QETProject *project)
{
QFile file(scriptPath);
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
err << "Cannot open script: " << scriptPath << "\n";
return false;
}
const QString source = QString::fromUtf8(file.readAll());
file.close();
QJSEngine engine;
auto *api = new QetScriptApi(project, &engine);
QJSValue qet_value = engine.newQObject(api);
// newQObject() takes ownership by default (QJSEngine::JavaScriptOwnership),
// which would delete api as soon as the engine's GC decides to -- api's
// real owner is the engine itself via the parent-child relationship set
// above, so keep the engine, not the GC, in charge of its lifetime.
engine.setObjectOwnership(api, QJSEngine::CppOwnership);
engine.globalObject().setProperty(QStringLiteral("qet"), qet_value);
QJSValue result = engine.evaluate(source, scriptPath);
if (result.isError()) {
err << "Script error: " << scriptPath << ":"
<< result.property(QStringLiteral("lineNumber")).toInt() << ": "
<< result.toString() << "\n";
return false;
}
return true;
}
#else // !QET_HAS_SCRIPTING
// Qt::Qml was not found at configure time (see the QET_HAS_SCRIPTING probe
// in the top-level CMakeLists.txt). Compile to a clear, non-silent failure
// rather than omitting these symbols -- the same "always compiled, the
// disabled path says why" shape as the QtPdf feature guard.
int run(const QStringList &)
{
err << "This build of QElectroTech was compiled without the Qt Qml "
"module, so JavaScript scripting (--run) is not available.\n";
return 1;
}
bool runOnProject(const QString &, QETProject *)
{
err << "This build of QElectroTech was compiled without the Qt Qml "
"module, so JavaScript scripting is not available.\n";
return false;
}
#endif // QET_HAS_SCRIPTING
}