From 7f8f137aa0214573703896a8ab1d065b59d6c753 Mon Sep 17 00:00:00 2001 From: Markus Triska Date: Wed, 25 Jan 2023 23:27:45 +0100 Subject: [PATCH] DOC: convert library(si) documentation to DocLog format --- src/lib/si.pl | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/src/lib/si.pl b/src/lib/si.pl index d697c8a8..a1705343 100644 --- a/src/lib/si.pl +++ b/src/lib/si.pl @@ -1,28 +1,36 @@ -/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Safe type tests - =============== +/** Safe type tests. - "si" stands for "sufficiently instantiated". + "si" stands for "sufficiently instantiated". It can also be read as + "safe inference", so possibly also other predicates are candidates + for this library. - These predicates: + A safe type test: - - throw instantiation errors if the argument is + - throws an *instantiation error* if the argument is not sufficiently instantiated to make a sound decision - - succeed if the argument is of the specified type - - fail otherwise. + - *succeeds* if the argument is of the specified type + - *fails* otherwise. - For instance, atom_si(A) yields an *instantiation error* if A is a + For instance, `atom_si(A)` yields an *instantiation error* if `A` is a variable. This is logically sound, since in that case the argument is not sufficiently instantiated to make any decision. - The definitions are taken from: - - https://stackoverflow.com/questions/27306453/safer-type-tests-in-prolog - - "si" can also be read as "safe inference", so possibly also other - predicates are candidates for this library. -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */ + The definitions are taken from [Safer type tests in Prolog](https://stackoverflow.com/questions/27306453/safer-type-tests-in-prolog). + + Examples: + +``` +?- chars_si(Cs). + error(instantiation_error,list_si/1). +?- chars_si([h|Cs]). + error(instantiation_error,list_si/1). +?- chars_si("hello"). + true. +?- chars_si(hello). + false. +``` +*/ :- module(si, [atom_si/1, integer_si/1, -- 2.54.0