Suppress confusion! Two suggestions for the online docs (atom_codes/2, atom_chars/2)

Request For Comments
1

In

https://www.swi-prolog.org/pldoc/doc_for?object=atom_codes/2

the description says;

atom_codes (?Atom, ?String)

Convert between an atom and a list of character codes. If Atom is instantiated, it will be translated into a list of character codes and the result is unified with String. If Atom is unbound and String is a list of character codes, Atom will be unified with an atom constructed from this list.

I suggest to change the description to talk about CharList (i.e. a list of characters, which integers corresponding to unicode code points) as String has another meaning in SWI-Prolog.

Similarly

atom_chars/2

atom_chars (?Atom, ?CharList) As atom_codes/2, but CharList is a list of one-character atoms rather than a list of character codes.

It should talk about MonoatomList as Char has another meaning in Prolog.

Addendum:

https://eu.swi-prolog.org/pldoc/doc_for?object=msort/2

Equivalent to sort/2, but does not remove duplicates. Raises a type_error if List is a cyclic list or not a list.

It is unclear whether the sort is stable…

2

I agree that a change may be necessary but not so sure about the specific change as proposed.

Having a personal history as noted in What type is a single quoted string? to me this is just the tip of an iceberg. A change should note the ISO Prolog standard and how SWI-Prolog can differ with the use of Prolog flags. A change should also show examples of using the type checking predicates such as atom/1, string/1, is_list/1, is_of_type/2, and output predicates such as write_canonical/1, etc. as a user would expect those to be in-sync with the description. This then leads to the idea that an entire bottom up review of all of the related definitions and usages be checked and re-aligned as needed and then this could become a mini-thesis project.

Examples of some predicates for demonstration but not an exhaustive list.

?- atom_codes('abc',String).
String = [97, 98, 99].

?- atom_codes('abc',String),string(String).
false.

?- atom_codes('abc',String),error:has_type(text,String).
String = [97, 98, 99].

?- atom_codes('abc',String),error:has_type(chars,String).
false.

?- atom_codes('abc',String),error:has_type(codes,String).
String = [97, 98, 99].

?- atom_codes('abc',String),error:has_type(string,String).
false.

?- atom('string').
true.

?- write_canonical('string').
string
true.

So while I agree the idea is noble, I also see it as a potential problem for others learning in the future, as an example from a different concept; while I understood use_module/1, having seen consult/1 in a directive confused me ( Using consult in a directive to load source code; it puzzles me?) because it was old but until I learned it was old thought it might be new and the better way to go. Only having asked and getting useful feedback did I learn it was not the way to go. So a user new to Prolog might find conflicting descriptions and then pick the wrong one, which I agree is part of your goal, but also has the potential to add conflicting knowledge. So I believe that any update should also show correct and incorrect ways to use the predicates with SWI-Prolog and also with ISO Prolog in case a user is using another Prolog but reading the description at SWI-Prolog and extrapolating that to the Prolog they are using.

As always feel free to disagree or ignore. :slightly_smiling_face:

1 Like
3

For msort, it does not matter. It matters for keysort.

1 Like
5

String used to be a list of character codes before SWI-Prolog added “real” strings. As @j4n_bur53 says Prolog has atoms of length 1 that is a char and integers that represent characters that are, well, integers. The Prolog standard says nothing about their range, neither how the codes maps to a char, but the predicate char_code/2 implements the conversion. SWI-Prolog defines codes to be Unicode code points. Possibly the ISO standard would have standardized it this way if it was written now.

A lot of occurrences of String in the docs should be CodeList. Anyone is invited to create a pull request for that. Please no pull requests with only a single fix though. Say at least fixing a section and preferably more.

2 Likes