branch: externals/triples
commit 3c42e4b3c891cfbc2dd32fe10d7fa82047027bc6
Author: Andrew Hyatt <ahy...@gmail.com>
Commit: GitHub <nore...@github.com>
Add an optional limit to triples-search, and document the function (#17)
---
NEWS.org | 2 ++
README.org | 3 +++
triples.el | 21 +++++++++++++--------
3 files changed, 18 insertions(+), 8 deletions(-)
diff --git a/NEWS.org b/NEWS.org
index 978649ff70..357779fb6e 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -1,5 +1,7 @@
TITLE: Changelog for the triples module for GNU Emacs.
+* 0.5.1
+- Add an optional limit for =triples-search=, and document it.
* 0.5.0
- Add FTS for adding full text search.
- Fix for emacsql using an obsolete (or wrong) db opening function.
diff --git a/README.org b/README.org
index 587bb35190..1e4112e24b 100644
--- a/README.org
+++ b/README.org
@@ -91,6 +91,7 @@ There are other useful functions, including:
- =triples-with-predicate=, gets all triples that is about a specific property,
- =triples-subject-with-predicate-object=, get all subjects whose predicate is
equal to /object/,
- =triples-subjects-of-type=, get all subjects which have a particular type.
+- =triples-search=, get all properties where a predicate matches given text.
Can take an optional limit to restrict the number of results.
- =triples-remove-schema-type= , remove a type and all associated data from
the schema (should be rarely used).
** Predicates, with type and without
Sometimes the triples library will require predicates that are without type,
and sometimes with type, or "combined predicates". The rule is that if the
type is already specified in the function, it does not need to be respecified.
If the type is not specified, it is included in the combined predicate.
@@ -127,6 +128,8 @@ Triples supports
[[https://www.sqlite.org/fts5.html][SQLite's FTS5 extension]],
;; The same, but with substitution with an abbreviation.
(triples-fts-query-subject db "desc:panda" '(("desc" . "description/text")))
#+end_src
+
+This is different than =triples-search= which does a straight text match on a
particular predicate only, and returns results without ranking them.
** Backups
If your application wants to back up your database, the function
=triples-backup= provides the capability to do so safely. It can be called
like:
#+begin_src emacs-lisp
diff --git a/triples.el b/triples.el
index daa74a6044..4eb1412295 100644
--- a/triples.el
+++ b/triples.el
@@ -6,7 +6,7 @@
;; Homepage: https://github.com/ahyatt/triples
;; Package-Requires: ((seq "2.0") (emacs "28.1"))
;; Keywords: triples, kg, data, sqlite
-;; Version: 0.5.0
+;; Version: 0.5.1
;; 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 2 of the
@@ -307,7 +307,7 @@ DB is the database to delete from."
('emacsql (emacsql db [:delete :from triples :where (= subject $s1) :and
(like predicate $r2)]
subject (format "%s/%%" (triples--decolon
pred-prefix))))))
-(defun triples-db-select-pred-op (db pred op val &optional properties)
+(defun triples-db-select-pred-op (db pred op val &optional properties limit)
"Select matching predicates with PRED having OP relation to VAL.
DB is the database to select from.
@@ -317,7 +317,8 @@ is a symbol for a standard numerical comparison such as `=',
`!=', `>', or, when `val' is a strings, `like'. All alphabetic
comparison is case insensitive.
-If PROPERTIES is given, triples must match the given properties."
+If PROPERTIES is given, triples must match the given properties.
+If LIMIT is a positive integer, limit the results to that number."
(unless (symbolp pred)
(error "Predicates in triples must always be symbols"))
(let ((pred (triples--decolon pred)))
@@ -331,7 +332,8 @@ If PROPERTIES is given, triples must match the given
properties."
"CAST(object AS INTEGER) "
"object COLLATE NOCASE ")
(symbol-name op) " ?"
- (when properties " AND properties = ?"))
+ (when properties " AND properties = ?")
+ (when (and limit (> limit 0)) (format " LIMIT %d"
limit)))
(append
(list (triples-standardize-val pred)
(triples-standardize-val val))
@@ -350,7 +352,9 @@ If PROPERTIES is given, triples must match the given
properties."
('like [(like object $s2)]))
(when (stringp val) [:collate :nocase])
(when properties
- (list :and '(= properties $s3))))
+ (list :and '(= properties $s3)))
+ (when (and limit (> limit 0))
+ (list :limit limit)))
pred val properties)))))
(defun triples-db-select-pred-prefix (db subject pred-prefix)
@@ -702,9 +706,10 @@ This usually should not be called, it's better to just
delete
data you own with `triples-remove-type'."
(triples-db-delete db subject))
-(defun triples-search (db cpred text)
- "Search DB for instances of combined property CPRED with TEXT."
- (triples-db-select-pred-op db cpred 'like (format "%%%s%%" text)))
+(defun triples-search (db cpred text &optional limit)
+ "Search DB for instances of combined property CPRED with TEXT.
+If LIMIT is a positive integer, limit the results to that number."
+ (triples-db-select-pred-op db cpred 'like (format "%%%s%%" text) nil limit))
(defun triples-with-predicate (db cpred)
"Return all triples in DB with CPRED as its combined predicate."
