From 2ffbd7fcc178e68e7132d2f8f649d131c5a5d3af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Tue, 19 Jul 2022 14:49:24 +0200
Subject: Add comments.

---
 c/pl.cpp | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

(limited to 'c/pl.cpp')

diff --git a/c/pl.cpp b/c/pl.cpp
index fb3d4af..ef8aaf9 100644
--- a/c/pl.cpp
+++ b/c/pl.cpp
@@ -3,6 +3,8 @@
 
 #include "pl.h"
 
+/* Frame: Wrapper for opening and closing Prolog foreign frames. */
+
 Frame::Frame()
 {
 	m_f = PL_open_foreign_frame();
@@ -18,6 +20,7 @@ void Frame::Close()
 	PL_close_foreign_frame(m_f);
 }
 
+/* Close foreign frame and invalidate associated data. */
 void Frame::Discard()
 {
 	PL_discard_foreign_frame(m_f);
@@ -28,6 +31,8 @@ void Frame::Rewind()
 	PL_rewind_foreign_frame(m_f);
 }
 
+/* Mark: Wrapper for marking and releasing strings on the Prolog stack. */
+
 Mark::Mark()
 {
 	PL_mark_string_buffers(&m_m);
@@ -38,6 +43,8 @@ Mark::~Mark()
 	PL_release_string_buffers_from_mark(m_m);
 }
 
+/* Query: Wrapper for opening, solving and cutting Prolog query. */
+
 Query::Query(const module_t ctx, const predicate_t p, const term_t t0)
 {
 	m_q = PL_open_query(ctx, PL_Q_CATCH_EXCEPTION, p, t0);
@@ -55,6 +62,7 @@ int Query::Cut()
 	return 0;
 }
 
+/* Cut query and invalidate associated data. */
 int Query::Close()
 {
 	if (PL_close_query(m_q)) return 1;
@@ -69,6 +77,7 @@ int Query::NextSolution()
 	return 0;
 }
 
+/* Convert Prolog term to normal or wide characters. */
 int PL_get_tchars(const term_t t, TCHAR** const pTsz, const int iFlags)
 {
 #ifdef UNICODE
@@ -83,6 +92,7 @@ int PL_get_tchars(const term_t t, TCHAR** const pTsz, const int iFlags)
 #endif
 }
 
+/* Call nullary Prolog predicate, propagating Prolog exceptions. */
 int Plx(const char* const szMod, const char* const szPred)
 {
 	Frame f;
@@ -90,3 +100,13 @@ int Plx(const char* const szMod, const char* const szPred)
 	Query q(NULL, PL_predicate(szPred, 0, szMod), t);
 	return q.NextSolution();
 }
+
+/* Call nullary Prolog predicate, ignoring Prolog exceptions. */
+int Pl(const char* const szMod, const char* const szPred)
+{
+	try {
+		return Plx(szMod, szPred);
+	} catch (term_t& t) {
+		return 0;
+	}
+}
-- 
cgit v1.2.3