[Wrapl-discussion] Corrections to the documentation

[Roman M. <rom...@gm...>]

Raja,

here I collected some things that I feel might be corrected in the
documentation or implemented in the language.
If you see some of them as inappropriate, skip them. They are grouped by
Module:

================================================================================
Libraries:Std:String (http://wrapl.sourceforge.net/doc/Std/String.html):
================================================================================

A typo:

:begins(a @ T, b @ T) : T
Returns a if it begins with a, fails otherwise.

should be

Returns a if it begins with b, fails otherwise.

--------------------------------------------------------------------------------

There are undocumented (not mentioned but working) :reverse and :"+"
methods.

--------------------------------------------------------------------------------

:"~="(_ @ T, _ @ T) should go up on the page, near to :"="(_ @ T, _ @ T)

================================================================================
Libraries:Agg:List (http://wrapl.sourceforge.net/doc/Agg/List.html):
================================================================================

:reverse(list @ T) : T

The list itself becomes reversed. So "in place" might be added to the
description (likewise for :sort method).

================================================================================
Libraries:Agg:Table (http://wrapl.sourceforge.net/doc/Agg/Table.html)
================================================================================

Since a Table with keys but no values can be thought of as a Set, the
following might be added to the descriptions:

:"*"(a @ T, b @ T) : T
Intersection.

:"+"(a @ T, b @ T) : T
Union.

:"-"(a @ T, b @ T) : T
Difference.

--------------------------------------------------------------------------------

:insert(t @ T, key) : T

should be

:insert(t @ T, key, value) : T

if value is omitted, NIL is supplied.

--------------------------------------------------------------------------------

Collect(func @ Std.Function.T) : T
"... values returned by func as keys ..."

should be

Collect(func @ Std.Function.T, args) : T
"... values returned by func(args) as keys ..."

Otherwise it is not obvious from the description that the arguments can
actually be passed to the func as Table.Collect(func, args); I didn't test
this with multiple arguments, though.

The same is true for the description of the List.Collect function.

--------------------------------------------------------------------------------

An observation (for the sake of consistency):
There are Collect function and :collect method for Lists.
There is only Collect function for Tables. No :collect method.

--------------------------------------------------------------------------------

Suggestion to create new expression:

UNIQ expr
Returns a set of the values produced by expr.

Likewise ALL expr for creating a list.

Rephrasing ALL's description on the Syntax page (
http://wrapl.sourceforge.net/ref/syntax.html):
Sets can also be constructed using UNIQ expressions: UNIQ expression will
return a set consisting of the unique, sorted keys that are values produced
by expression. If expression fails to produce any value, the result will be
an empty table {}. For example: UNIQ " ac bed gfa de":chars \ NOT $ IN "
\t\n\r" will give the set {"a", "b", "c", "d", "e", "f", "g"}. Another
example: UNIQ [3, 2, 1, 4, 1, 4]:values will give the set {1, 2, 3, 4}.

================================================================================
Libraries:Sys:FileSys (http://wrapl.sourceforge.net/doc/Sys/FileSys.html):
================================================================================

TempFile() returns UNIX-like file name on Windows.

Interactive Wrapl [1.9:1074]
--> IMP Sys.FileSys;
NIL
--> FileSys.TempFile();
"/tmp/t92c.0"
-->

--------------------------------------------------------------------------------
The following is going on Linux (Ubuntu 10.04):

Interactive Wrapl [1.9.1074:1074]
--> IMP Sys.Environ;
NIL
--> Environ.GetCwd();
"/home/roman/Downloads/Wrapl"
--> IMP Sys.FileSys;
NIL
--> VAR d <- FileSys.ListDirInfo(".");
<value>
--> d:name;
"wrapl-1.7-1041.tar.bz2"
--> d:size;
NIL
--> d:type;
32768
--> FileSys.FileSize("./wrapl-1.7-1041.tar.bz2");
2380542
--> FileSys.FileType("./wrapl-1.7-1041.tar.bz2");
33261
-->

The result of FileSys.FileSize is what ls command gives but d:size is NIL.
The results of d:type and FileSys.FileType are different.

What is the bitmask of the types of the file? How to use (to decipher) it?

:exists(info @ InfoT) and :time(info @ InfoT) methods would be handy too.

================================================================================
>From the Expressions page (http://wrapl.sourceforge.net/ref/expressions.html
):
"| expr" Generate all the values of expr repeatedly.

>From the Tutorial (http://wrapl.sourceforge.net/ref/tutorial/chapter3.html):
The expression @ expr1 produces all the values produced by expr1 ad
infinitum.

I believe there should be "@ expr" instead of "| expr" on the Expressions
page.

--------------------------------------------------------------------------------

NOT and IN might be mentioned on the Expressions page.

--------------------------------------------------------------------------------

I saw ^ (caret) somewhere in your code as a prefix to a variable.
What does it perform? Could it be mentioned also?

================================================================================
Using GTK+ (http://wrapl.sourceforge.net/samples/gtk.html):

On Linux:

Gtk1.wrapl
...
dialog:Vbox:PackStartDefaults(label);

method Vbox not found

================================================================================
Tutorial (http://wrapl.sourceforge.net/ref/tutorial.html):

Chapters 6, 7 and 8 lack navigational arrows.

================================================================================
On the Download page (http://wrapl.sourceforge.net/download.html):

A typo in the link to Lua (http://http//www.lua.org/).

================================================================================
Website Search doesn't work currently:
"Cannot connect to database, check if username, password and host are
correct."

Google has managed to index 9 pages only:
http://www.google.ru/search?q=site:http://wrapl.sourceforge.net/

Embedding Google Custom Search (http://www.google.com/cse/) could be an
option.

-- 
Roman