tcllib-devel — Discussion of development for tcllib

Re: [Tcllib-devel] Writing tests - how?

[Andreas K. <and...@ac...>]

> Andreas Kupries skrev:
> >> Well, what about a small helper package? One could make the above
> >>
> >> package require tcllib::testutilities
> >> tcllib::testutilities::init
> >>
> >> or something like that. The separate [tcllib::testutilities::init] call
> >> would be needed to retrieve the [info script] data, although now that I
> >> think about it, one could (if really devious) embed such a call into
> >> the [package ifneeded] script as well. An explicit call does however
> >> have the advantage that one can, if necessary, customise the
> >> initialisation (no, I don't have a clear use-case for that right now;
> >> maybe too tired).

> Having slept on the matter, I now have "configuration for nonstandard
> test environment" as use-case. The initialisation command put in the
> .test file would do a default init (e.g. assuming tcllib CVS
> organisation of files, using current file as reference), but extra
> commands given before sourcing the test file could specify overrides
> for the defaults.


> For example, one might do:
>
> package require tcllib::testutilities
> tcllib::testutilities::declaredir modules/math \
>    /Library/Tcl/tcllib-1.6/math
> source foo.test

Ok, this is different from what I thought it was per your first email.
There it looked to me as if the

	package require tcllib::testutilities

statement was inside of foo.test, replacing the big source/file/info script
construction.
Now it has moved outside, to whatever is invoking the test script.

Is my understanding of both older and current/here setup right?


> to specify an override that "whenever the test file wants to [use]
> something in modules/math, it should use the corresponding file in
> /Library/Tcl/tcllib-1.6/math". There's no harm in doing [package
> require tcllib::testutilities] twice, unlike the corresponding explicit
> [source].

Uh. I am not sure if that sort of mapping is a useful feature. More thinking
required.

> >> What is gained by [package require tcllib::testutilities] is primarily
> >> that one avoids hardcoding paths (relative paths, yes, but still
> >> hardcoded paths) into the test files.
> >
> > The price you are paying for this is that you now cannot run
> the testsuite
> > anymore if Tcllib is not installed because the package won't be
> found. Or
> > using the wrong helper package if some other version of Tcllib
> is installed.
>
> That's a very pessimistic view of the matter. The only case I can think
> of in which one would like to run the tcllib testsuite without having
> /any/ version of tcllib installed is "make test"-style activities:
> testing new software before actually installing it.

Your view seems to be for a person/role getting the sources of Tcllib,
building, testing, then installing.
Not sure what name to give that role, it is not a 'developer' I would say.
Maybe 'installer'.

To me 'make test' is an integral part of 'development' activities. I.e.
testing the software while working on it, making sure that changes do not
break things. Like I did, for example, yesterday when speeding up the
struct::stack Tcl code a bit. Would be bad if it became fast, but also
wrong. Proactive testing before committing changes, instead of waiting for
installers to tell me what I broke.

> In this situation,
> the environment is fairly well controlled, so providing an extra
> package is not a problem.

Hm ...



> Developers working on tcllib should be expected to at least have some
> version installed,

It is likely. Do I want to depend on that? It makes for too much coupling to
the outside in my mind. I prefer that development is in a sandbox, something
self-contained, or, if not possible, minimal dependencies.

> so unless you foresee several radical changes in the
> testutilities API, problems because the installed version is not that
> of CVS HEAD should be rare, and easily recognised when they eventually
> occur. What could be inconvenient is the transition period when such a
> package is being introduced into tcllib, but OTOH it would probably
> take a couple of years before any large portion of tests were rewritten
> to take advantage of it. ;-)


> > Running the testsuite of Tcllib without Tcllib installed is IMHO an
> > important use case during development.
>
> What is *lost* with the
>

[stmt1]
> source [file join \
> 	[file dirname [file dirname [file join [pwd] [info script]]]] \
> 	devtools testutilities.tcl]
>
> arrangement is the ability to run tests /without having all of the
> tcllib repository at hand/.

I believe you meant 'source directory' instead of 'repository'.

I think I am beginning to understand our differences of view, which are
fundamental.

I am assuming and expecting that development on a part of Tcllib, i.e.
something like 'modules/report' always happens in a sandbox containing the
whole of the Tcllib sources. Together with my drive to avoid external
dependencies I arrive at [stmt1], which reflects both.

You seem to have the case where you copy 'modules/report' somewhere else,
being standalone, and still wish to be able to test it. At which point you
need the installed Tcllib, to find dependencies on other packages in Tcllib,
like struct::matrix.

Ok, that sounds quite artificial ...

A less-artificial case seems to be that: You develop a new package FOO, and
you start outside of Tcllib, do the testing outside, and then later wish to
drop it into Tcllib and have the tests working without change.

In that case I would have actually started developing FOO from within a
Tcllib sandbox, having the assumed envirnment available from the beginning.


My main conclusion here is that I see the non-ability to run tests without
having all of the tcllib source directory at hand as no loss at all.

In a way, we both need and assume the existence Tcllib, always, we simply
choose different locations where to find it.
You assume to have it installed, and I go and assume that I have all the
sources.

I like my approach because I believe it gives me better control about the
test environment and less possibility of interference, despite having to put
up with the longish command to load all that environment.


> Wherever I have a foo.test, it is assumed
> that there is a ../devtools/testutilities.tcl to source.

Yes.

> There will be
> such a file if you've checked out all of tcllib or tcllib/modules from
> CVS, but at least I find it much more prudent to check out only "my
> own" module (especially if the project hierarchy in which it was
> originally developed doesn't match tcllib).

Reading this now, after writing all of the above I feel stupid. It seems I
just paraphrased everything written now, and could have spared me the
effort. OTOH, seeing my inference of usecase matching your description now
makes me fairly sure that I have some understanding of your thoughts.

We seem to have fundamentally different views on the process and system.


> > To re-enable execution you have to extend the auto_path,
>
> Which is quite feasible to do from the environment in the "make test"
> scenario, and unnecessary otherwise.
>
> > adding again the path information you do not want to the .test files.
>
> Of course it shouldn't be the responsibility of the .test files to
> provide this information! The main point of having the [package]
> mechanism is to allow code to call upon other code without knowing
> exactly where it is found!

True. However with testing, where I want to rigorously control the
environment I consider exactly that a disadvantage.

> > Even so it stays
> > brittle because anybody can intercept this by adding a higher
> version of the
> > helper package anywhere on the auto_path.

> If that is brittle, then it is so only because the development of the
> helper package is being mismanaged!

> A higher version of the package
> will only be picked if it has the same major version number as the one
> you require. The major version number must be incremented if the
> package is changed so that it is not backwards compatible. So how could
> newer versions be a problem?

I agree, they shouldn't be. However, can you bet on that? It is easy to
mismanage this, have a bug


Thinking further, seems that my thoughts are churning (in a good way).

For one of the, right now half-baked, ideas which this discussion just
tossed up into my conscious mind is that our Tcllib 'testutilities' are in
some sense actually special, they are not a regular Tcllib package we
install. But they are, also, something, which is very common, similar to
'tcltest'. In a way they are an extension of 'tcltest' ... Can it be made
(or is) generic enough tthat we should/could install it ?

If it is generic enough we can move it ouf Tcllib. Then my feelings about it
as package required dependency seem to change and allow that, as it would
then be something managed externally anyway (i.e. like tcltest). The
question is, how much of the testutilities code is tied to the sepcialities
of Tcllib ... Oh, another flash of an idea ... With it outside, have it
overide the 'package unknown' command, search the code, like Tcllib for
packages first, and ignore packages of the same name outside ...

... I think I better stop here ... let it settle and think/sleep about it
more ...

Note: The testutils are a conglomeration of several groups of commands, each
group could be their own package ... Make a set of higher level test
framework packages ... Ok, I really have to settle and meditate ...

--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122

Re: [Tcllib-devel] Tcl 8.2 support

[Lars H. <Lar...@re...>]

This is an old thread, and an issue probably already settled, but it 
just occurred to me that the main argument for the strict 
interpretation is flawed, or requires changes also elsewhere.

On 2008-05-25, Jeff Hobbs wrote:
> Lars Hellström wrote:
>> I can understand a policy of "don't make any changes to patches, or 
>> otherwise restrain your coding style, just for the sake of preserving 
>> compatibility with Tcl 8.x if x<4". I can also understand not wanting 
>> to entertain old Tcl versions just for the sake of testing tcllib 
>> releases, in the hope that someone, somewhere might appreciate it.
>>
>> On the other hand, denying the actual compatibility level of a piece 
>> of software feels rather artificial.
>>
>> Is the catch the uncertainty factor: that one can _presume_ a package 
>> works with Tcl 8.2 based on the features it uses, but won't really 
>> _know_ whether this is the case until having tested it on an actual 
>> Tcl 8.2 interpreter?
> 
> This is the primary reason.  Unless someone else is secretly doing it, 
> tcllib hasn't been tested against anything below 8.4 in a long time.

This seems reasonable as long as one considers only the Tcl version, 
but in this context Tcl is just a package on which there is some 
dependence; one package among many. Hence if this "we can only have 
[package require] for versions actively tested" principle is to be 
taken seriously, then it should be applied also for all other packages, 
should it not?

Well, grepping in tcllib 1.10 finds:

package require Trf 2.0     (in base64/base64.tcl), but I have 2.1.
package require dns 1.0     (in dns/resolv.tcl), but I have 1.3.2.
package require cmdline 1.1 (in htmlparse/htmlparse.tcl), I have 1.3.
package require asn 0.7     (in ldap/ldap.tcl), I have 0.8.1.
package require uri 1.1.5   (in ldap/ldapx.tcl), I have 1.2.1.

and so on; the versions don't match more often than they do match, so 
should all these numbers be raised to the highest version in tcllib, 
because that is the only combination that is tested? Well, the majority 
of all non-Tcl [package require] in tcllib is not for a version lower 
than that currently in tcllib, because the majority of all calls don't 
specify any version at all -- which means every version that ever 
existed or ever will exist of that package is accepted! Is that a 
smaller problem than a deliberate but untested [package require Tcl 8.2]?

The conditional use of C extension packages (such as Trf) complicates 
the matter further, because making use of these then requires running 
the test both with and without the package in question, where the 
"with" case decomposes into separate cases for every version of the 
extension that is not ruled out by the version requirement.

Conclusion: I doubt we have ever conducted tests at the level of rigor 
that this principle aims for.

 > We have had issues where 8.4-isms crept into code that claimed to be
 > "8.2-compliant" and somebody noticed.

Realistically, there will always be bugs in not requiring a high enough 
version of a package (just as there will, more often, be other types of 
  bugs), it only happens for Tcl more often than for the other packages 
because Tcl is far more used.

Lars Hellström

Re: [Tcllib-devel] Writing tests - how?

[Lars H. <Lar...@re...>]

Andreas Kupries skrev:
>> Well, what about a small helper package? One could make the above
>>
>> package require tcllib::testutilities
>> tcllib::testutilities::init
>>
>> or something like that. The separate [tcllib::testutilities::init] call
>> would be needed to retrieve the [info script] data, although now that I
>> think about it, one could (if really devious) embed such a call into
>> the [package ifneeded] script as well. An explicit call does however
>> have the advantage that one can, if necessary, customise the
>> initialisation (no, I don't have a clear use-case for that right now;
>> maybe too tired).

Having slept on the matter, I now have "configuration for nonstandard 
test environment" as use-case. The initialisation command put in the 
.test file would do a default init (e.g. assuming tcllib CVS 
organisation of files, using current file as reference), but extra 
commands given before sourcing the test file could specify overrides 
for the defaults.

For example, one might do:

package require tcllib::testutilities
tcllib::testutilities::declaredir modules/math \
   /Library/Tcl/tcllib-1.6/math
source foo.test

to specify an override that "whenever the test file wants to [use] 
something in modules/math, it should use the corresponding file in 
/Library/Tcl/tcllib-1.6/math". There's no harm in doing [package 
require tcllib::testutilities] twice, unlike the corresponding explicit 
[source].


>> What is gained by [package require tcllib::testutilities] is primarily
>> that one avoids hardcoding paths (relative paths, yes, but still
>> hardcoded paths) into the test files.
> 
> The price you are paying for this is that you now cannot run the testsuite
> anymore if Tcllib is not installed because the package won't be found. Or
> using the wrong helper package if some other version of Tcllib is installed.

That's a very pessimistic view of the matter. The only case I can think
of in which one would like to run the tcllib testsuite without having
/any/ version of tcllib installed is "make test"-style activities:
testing new software before actually installing it. In this situation,
the environment is fairly well controlled, so providing an extra
package is not a problem.

Developers working on tcllib should be expected to at least have some
version installed, so unless you foresee several radical changes in the
testutilities API, problems because the installed version is not that
of CVS HEAD should be rare, and easily recognised when they eventually
occur. What could be inconvenient is the transition period when such a
package is being introduced into tcllib, but OTOH it would probably
take a couple of years before any large portion of tests were rewritten
to take advantage of it. ;-)

> Running the testsuite of Tcllib without Tcllib installed is IMHO an
> important use case during development.

What is *lost* with the

source [file join \
	[file dirname [file dirname [file join [pwd] [info script]]]] \
	devtools testutilities.tcl]

arrangement is the ability to run tests /without having all of the
tcllib repository at hand/. Wherever I have a foo.test, it is assumed
that there is a ../devtools/testutilities.tcl to source. There will be
such a file if you've checked out all of tcllib or tcllib/modules from
CVS, but at least I find it much more prudent to check out only "my
own" module (especially if the project hierarchy in which it was
originally developed doesn't match tcllib).

> To re-enable execution you have to extend the auto_path, 

Which is quite feasible to do from the environment in the "make test"
scenario, and unnecessary otherwise.

> adding again the path information you do not want to the .test files.

Of course it shouldn't be the responsibility of the .test files to
provide this information! The main point of having the [package]
mechanism is to allow code to call upon other code without knowing
exactly where it is found!

> Even so it stays
> brittle because anybody can intercept this by adding a higher version of the
> helper package anywhere on the auto_path.

If that is brittle, then it is so only because the development of the
helper package is being mismanaged! A higher version of the package
will only be picked if it has the same major version number as the one
you require. The major version number must be incremented if the
package is changed so that it is not backwards compatible. So how could
newer versions be a problem?

Lars Hellström

Re: [Tcllib-devel] Writing tests - how?

[Andreas K. <and...@ac...>]

> Well, what about a small helper package? One could make the above
>
> package require tcllib::testutilities
> tcllib::testutilities::init
>
> or something like that. The separate [tcllib::testutilities::init] call
> would be needed to retrieve the [info script] data, although now that I
> think about it, one could (if really devious) embed such a call into
> the [package ifneeded] script as well. An explicit call does however
> have the advantage that one can, if necessary, customise the
> initialisation (no, I don't have a clear use-case for that right now;
> maybe too tired).

> What is gained by [package require tcllib::testutilities] is primarily
> that one avoids hardcoding paths (relative paths, yes, but still
> hardcoded paths) into the test files.

The price you are paying for this is that you now cannot run the testsuite
anymore if Tcllib is not installed because the package won't be found. Or
using the wrong helper package if some other version of Tcllib is installed.

Running the testsuite of Tcllib without Tcllib installed is IMHO an
important use case during development.

To re-enable execution you have to extend the auto_path, adding again the
path information you do not want to the .test files. Even so it stays
brittle because anybody can intercept this by adding a higher version of the
helper package anywhere on the auto_path.

Extending the auto_path through the setup code done by 'sak test run' ... is
possible, however then the .test files become dependent on this exact tool,
and IIRC there are people who wish to run the tcllib testsuite through their
own tools, and not sak, making such a dependency a bad thing.


--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122

Re: [Tcllib-devel] Writing tests - how?

[Lars H. <Lar...@re...>]

Andreas Kupries skrev:
>> What is currently available /may/ of course be interpreted as "well,
>> just copy and modify pop3.test". I suppose this will work (many have
>> probably done that) but already the first commmand
> 
>> source [file join \
>>   	[file dirname [file dirname [file join [pwd] [info script]]]] \
>>   	devtools testutilities.tcl]
> 
>> there is enough to make me shun away. Surely there should be a better
>> way to do this?
> 
> As far as I know, no. This is the standard command to load the common
> support code for testsuites in Tcllib. It uses the location of the .test
> file to compute the location of the support code and the sourcing it. We
> cannot avoid its replication across all testsuites. Stuffing it into a
> procedure in the support code will not work, because then you will need the
> support code itself to make the support code available. And I do not have
> any other ideas. If you have some feel free to tell me.

Well, what about a small helper package? One could make the above

package require tcllib::testutilities
tcllib::testutilities::init

or something like that. The separate [tcllib::testutilities::init] call 
would be needed to retrieve the [info script] data, although now that I 
think about it, one could (if really devious) embed such a call into 
the [package ifneeded] script as well. An explicit call does however 
have the advantage that one can, if necessary, customise the 
initialisation (no, I don't have a clear use-case for that right now; 
maybe too tired).

What is gained by [package require tcllib::testutilities] is primarily 
that one avoids hardcoding paths (relative paths, yes, but still 
hardcoded paths) into the test files.

Lars Hellström

Re: [Tcllib-devel] Writing tests - how?

[Andreas K. <and...@ac...>]

> What is currently available /may/ of course be interpreted as "well,
> just copy and modify pop3.test". I suppose this will work (many have
> probably done that) but already the first commmand

> source [file join \
>   	[file dirname [file dirname [file join [pwd] [info script]]]] \
>   	devtools testutilities.tcl]

> there is enough to make me shun away. Surely there should be a better
> way to do this?

As far as I know, no. This is the standard command to load the common
support code for testsuites in Tcllib. It uses the location of the .test
file to compute the location of the support code and the sourcing it. We
cannot avoid its replication across all testsuites. Stuffing it into a
procedure in the support code will not work, because then you will need the
support code itself to make the support code available. And I do not have
any other ideas. If you have some feel free to tell me.


> Apologies if this has been discussed before

AFAIK no.

>(at least I'm certain I've
> been bothered by this before), but a search on the SF mail archives did
> not find anything within the last year and a half or so.

> Basic problem: The tcllib README states
>
>   * the module should have both documentation ([*]) and a test suite
>     (in the form of a group of *.test files in the module directory).
>   * the module must have either documentation or a test suite.  It can
>     not have neither.
>
> and README.developer continues
>
>   * If available the testsuite(s) should use 'tcltest' and the
>     general format as used by the other modules in Tcllib
>     (declaration of minimally needed Tcl, tcltest, supporting
>     packages, etc.). The file(s) should have the extension
>     '.test' for SAK to recognize them.
>
> but what does this mean concretely? I'd interpret it as saying that
> e.g. foo.tcl should come with foo.test, where the latter looks like:
>
>
> package require Tcl 8.4 ; # Declaration of minimally needed Tcl
> package require tcltest 2 ; # Ditto tcltest
> package require bar 1.3.2 ; # Supporting package

Actually:
	[std command to load testutilities.tcl]

	testsNeedTcl 8.4
	testsNeedTcltest 2

Is the supporting package bar in Tcllib ? If not

	package require bar 1.3.2

otherwise

	support {
	    use bar/bar.tcl bar ;# Assuming that 'bar' is in directory bar under
'modules'.
	}

> # Now follows the test(s). (Currently, there is only one.)
> tcltest::test foo-1.1 "Testing foo" -body {
>     foo
> } -result "baz"
>

>
> but I rather doubt this would work; for one, the foo package itself
> doesn't seem to be loaded. Is that perhaps the "etc." in
> README.developer ;-),

The file README.developer is incomplete, yes.

	testing {
	    use foo.tcl foo
	}

> or is there rather some automagic [source]ry
> going on?

No.

> More information seems to be required. (Yes, I will find out
> below that the above probably doesn't refer to [package require] at
> all, but rather to [testsNeedTcl] and friends.)

> A tcllib contributor might of course at this point choose to just
> duplicate whatever is done in existing .test files in tcllib, but
> doing-without-understanding is not a strategy I'm comfortable with.

Understandable.

> Besides, when I /have/ picked modules at random and looked at their
> .test files, I haven't come across anything that looked like a
> boilerplate test file.

The basic boilerplate is what I have inlined above. Differences come for
packages which have accelerators. Their tests can use the TestAccel
commands, if their accelerator management follows specific lines. Not all do
IIRC, yet.

> So, I took a look around the CVS archive, in hunt for better
> documentation. There is for example a devdoc directory
> (http://tcllib.cvs.sourceforge.net/tcllib/tcllib/devdoc/) -- maybe this
> contains more information on the matter? Sadly, it doesn't. Also, most
> of the information therein seems to be rather old (even if some files
> were modified 9 months ago).

IIRC they are outdated as well.

> What else is there?

>
> There is also a support/devel directory, which contains all.tcl and sak
>   -- since this is the software canonically running the tests, maybe
> this is where one might find some documentation on the matter? Sadly,
> no.

Running the tests doesn't really have to care about the boilerplate setup
and such as long as the test cases themselves are written with 'tcltest',
essentially.

> There are several help.txt files, but those only contain
> interactive help messages from the sak application, so the only actual
> documentation I can find therein is for the embedded pregistry package.
> Nothing to help with test files...
>
> The mail achive search did however turn up a mention of
> devtools/testutilities -- where might this be found? As it turns out,
> devtools is a *module* in the CVS repository
> (http://tcllib.cvs.sourceforge.net/tcllib/tcllib/modules/devtools/),
> although it doesn't get installed as a module (only natural, as it has
> neither documentation nor test suite; this is beginning to feel like a
> pattern).

> A lot of what is in devtools/ looks very interesting:
>
>    * testutilities.tcl:[useLocalFile] to make sure I'm testing the
> version of my package matching the test rather than some random older
> version I happen to have installed.
>    * coserv.tcl (for later, testing an IPC package I'm working on)
>
> but then there's the matter of missing documentation, and questions it
> should have answered:
>
>    * Should one use [useLocalFile], [useTcllibFile], [useLocal], or
> what? When and why?

Yes, all the time.

>    * How are these commands supposed to be made available? When can one
> rely on them?

See the first paragraph, I moved this to the top.


Yes, we have big hole in our developer support there.

I will try to come up with documentation and use you as the guinea pig to
test it on.

Of course, if someone else is willing to write such docs after picking my
brain (= firing questions at me and mangling the answers into a coherent
whole) I will gladly welcome that.

--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122

Re: [Tcllib-devel] Writing tests - how?

[KATO K. <k.k...@gm...>]

[tcltest] is not a module of tcllib but the more standard command.
Therefore, it can be said that it naturally is not written as a
document of tcllib.

About how to write a test script:
A source code is very often a good document especially to write one.
testsuits written by me may be consulted.
[modules/yaml/huddle.test, yaml.test]

It can operate as an independent simple-test and operates also as a
series of tests of sak.tcl.

----------------------------------------
$ cd modules/yaml; tclsh huddle.test
or
$ sak test run modules/yaml
----------------------------------------


About [devtools], the author's Mr.Andreas Kupries will reply.

[Tcllib-devel] Writing tests - how?

[Lars H. <Lar...@re...>]

Apologies if this has been discussed before (at least I'm certain I've 
been bothered by this before), but a search on the SF mail archives did 
not find anything within the last year and a half or so.

Basic problem: The tcllib README states

  * the module should have both documentation ([*]) and a test suite
    (in the form of a group of *.test files in the module directory).
  * the module must have either documentation or a test suite.  It can
    not have neither.

and README.developer continues

  * If available the testsuite(s) should use 'tcltest' and the
    general format as used by the other modules in Tcllib
    (declaration of minimally needed Tcl, tcltest, supporting
    packages, etc.). The file(s) should have the extension
    '.test' for SAK to recognize them.

but what does this mean concretely? I'd interpret it as saying that 
e.g. foo.tcl should come with foo.test, where the latter looks like:


package require Tcl 8.4 ; # Declaration of minimally needed Tcl
package require tcltest 2 ; # Ditto tcltest
package require bar 1.3.2 ; # Supporting package

# Now follows the test(s). (Currently, there is only one.)
tcltest::test foo-1.1 "Testing foo" -body {
    foo
} -result "baz"


but I rather doubt this would work; for one, the foo package itself 
doesn't seem to be loaded. Is that perhaps the "etc." in 
README.developer ;-), or is there rather some automagic [source]ry 
going on? More information seems to be required. (Yes, I will find out 
below that the above probably doesn't refer to [package require] at 
all, but rather to [testsNeedTcl] and friends.)

A tcllib contributor might of course at this point choose to just 
duplicate whatever is done in existing .test files in tcllib, but 
doing-without-understanding is not a strategy I'm comfortable with. 
Besides, when I /have/ picked modules at random and looked at their 
.test files, I haven't come across anything that looked like a 
boilerplate test file.

So, I took a look around the CVS archive, in hunt for better 
documentation. There is for example a devdoc directory 
(http://tcllib.cvs.sourceforge.net/tcllib/tcllib/devdoc/) -- maybe this 
contains more information on the matter? Sadly, it doesn't. Also, most 
of the information therein seems to be rather old (even if some files 
were modified 9 months ago). What else is there?

There is also a support/devel directory, which contains all.tcl and sak 
  -- since this is the software canonically running the tests, maybe 
this is where one might find some documentation on the matter? Sadly, 
no. There are several help.txt files, but those only contain 
interactive help messages from the sak application, so the only actual 
documentation I can find therein is for the embedded pregistry package. 
Nothing to help with test files...

The mail achive search did however turn up a mention of 
devtools/testutilities -- where might this be found? As it turns out, 
devtools is a *module* in the CVS repository 
(http://tcllib.cvs.sourceforge.net/tcllib/tcllib/modules/devtools/), 
although it doesn't get installed as a module (only natural, as it has 
neither documentation nor test suite; this is beginning to feel like a 
pattern).

A lot of what is in devtools/ looks very interesting:

   * testutilities.tcl:[useLocalFile] to make sure I'm testing the 
version of my package matching the test rather than some random older 
version I happen to have installed.
   * coserv.tcl (for later, testing an IPC package I'm working on)

but then there's the matter of missing documentation, and questions it 
should have answered:

   * Should one use [useLocalFile], [useTcllibFile], [useLocal], or 
what? When and why?
   * How are these commands supposed to be made available? When can one 
rely on them?

What is currently available /may/ of course be interpreted as "well, 
just copy and modify pop3.test". I suppose this will work (many have 
probably done that) but already the first commmand

source [file join \
  	[file dirname [file dirname [file join [pwd] [info script]]]] \
  	devtools testutilities.tcl]

there is enough to make me shun away. Surely there should be a better 
way to do this?


Lars Hellström

Re: [Tcllib-devel] key order problem for dict

[KATO K. <k.k...@gm...>]

I made a procedure based on "dictsort" for testcases.
Currently, I use this in modules/yaml/yaml.test

There is upward compatibility between dictsort2 and dictsort.
If dictsort2's 2nd argument is not given, as the same work of dictsort.


proc dictsort2 {dict {pattern d}} {
    set cur  [lindex $pattern 0]
    set subs [lrange $pattern 1 end]
    set out {}
    if {$cur eq "l"} {
        foreach {node} $dict {
            if {$subs ne ""} {set node [dictsort2 $node $subs]}
            lappend out $node
        }
        return $out
    }
    if {$cur ne "d"} {array set msubs $cur}
    array set map $dict
    foreach key [lsort [array names map]] {
        set node $map($key)
        if {$cur eq "d"} {
            if {$subs ne ""} {set node [dictsort2 $node $subs]}
        } else {
            if [array exists msubs($key)] {
                set node [dictsort2 $node $msubs($key)]]
            }
        }
        lappend out $key $node
    }
    return $out
}

# Working Sample
% set dict {bb {h1 g1 d1 s1} aa {y2 t2 r2 e2}}
bb {h1 g1 d1 s1} aa {y2 t2 r2 e2}

# sorting only top
% dictsort2 $dict
aa {y2 t2 r2 e2} bb {h1 g1 d1 s1}

# sorting 2 ranks
% dictsort2 $dict {d d}
aa {r2 e2 y2 t2} bb {d1 s1 h1 g1}

# sorting only "aa"
% dictsort2 $dict {{aa d}}
aa {y2 t2 r2 e2} bb {h1 g1 d1 s1}

# sorting dict in list
% dictsort2 {{c1 d1 b1 a1} {j2 l2 a2 d2}} {l d}
{b1 a1 c1 d1} {a2 d2 j2 l2}

Re: [Tcllib-devel] key order problem for dict

[KATO K. <k.k...@gm...>]

2008/5/27, Jeff Hobbs:
> Yes, tcl8.5/tests/dict.test, look for use of "getOrder".

(1)sorted a dict order by argment, and [lappend [dict size $dict].

2008/5/27, Andreas Kupries:
> Tcllib's testsuite support code contains a command 'dictsort' which sorts a
> dictionary by keys
>
> The definition is in Tcllib's file  modules/devtools/testutilities.tcl,

(2)sorted a dict order by alphabetical one.


1,2, All could be used for evaluation of a value by a future test.
Thank you for teaching.

By for the moment, although the difference is absorbed reflecting the
action of [dict create] in all values, it may be one with better using
these helpers in fact.




> If you are talking about Tcl 8.5's dict structre and command, then no, IIRC
> the ordering of keys is preserved by them (append order).

To be sure, such an action was able to be checked.
It did not know that it was decided as specification.
However, dict-extension in Tcl8.4 has not adopted such how to move.

> > # remove duplications with saving key order
> > proc ::yaml::_remove_duplication {dict} {
> >     array set tmp $dict
> >     array set tmp2 {}
> >     foreach {key nop} $dict {
> >         if [info exists tmp2($key)] continue
> >         lappend result $key $tmp($key)
>
> lappend result $key $nop
> and the array 'tmp' is not required.
>
> >         set tmp2($key) 1
> >     }
> >     return $result
> > }

Then, it does not become operation whose intention it has.
'key' is the given order and 'value' wants to evaluate the last thing.

Re: [Tcllib-devel] key order problem for dict

[Andreas K. <and...@ac...>]

> You know that Tcl interpreter doesn't ensure that dict key ordering.

If you are talking about Tcl 8.5's dict structre and command, then no, IIRC
the ordering of keys is preserved by them (append order).
If you are talking about the result of [array get], then yes, the order is
'random', based on the hashtable internals.

Tcllib's testsuite support code contains a command 'dictsort' which sorts a
dictionary by keys

The definition is in Tcllib's file  modules/devtools/testutilities.tcl,
and modules/uri/uri.test,
modules/mime/mime.test are examples of using it.


> That is not matter for almost cases.
>
> But when we write test cases,
> how to compare between program result and booked value?

> Especially, it is difficult problem for multi rank dict.

>
> Thoughts?
>
>
>
> I wrote a proc, and replaced from [dict create $key_duplicated_dict].
> (yaml.tcl)
>
> # remove duplications with saving key order
> proc ::yaml::_remove_duplication {dict} {
>     array set tmp $dict
>     array set tmp2 {}
>     foreach {key nop} $dict {
>         if [info exists tmp2($key)] continue
>         lappend result $key $tmp($key)

lappend result $key $nop
and the array 'tmp' is not required.

>         set tmp2($key) 1
>     }
>     return $result
> }

--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122

Re: [Tcllib-devel] key order problem for dict

[Jeff H. <je...@ac...>]

KATO Kanryu wrote:
>> I would look at the 8.5 dict.test for how it does it,
>> using a [getOrder] proc that ensures a known order.
> 
> Is it the test of the dict itself?
> It is likely to become helpful.

Yes, tcl8.5/tests/dict.test, look for use of "getOrder".

Jeff

Re: [Tcllib-devel] key order problem for dict

[KATO K. <k.k...@gm...>]

> I would look at the 8.5 dict.test for how it does it,
> using a [getOrder] proc that ensures a known order.

Is it the test of the dict itself?
It is likely to become helpful.

Thanks.

However, since he did not necessarily want to test the action of dict
itself, it decided to rewrite immediate values for the moment.
For a while, the test passed by building the data for comparison
dynamically using [list/dict create] commands.

Re: [Tcllib-devel] key order problem for dict

[Jeff H. <je...@ac...>]

KATO Kanryu wrote:
> You know that Tcl interpreter doesn't ensure that dict key ordering.
> 
> That is not matter for almost cases.
> 
> But when we write test cases,
> how to compare between program result and booked value?

dicts are order-preserving, but that doesn't help you here.  I would 
look at the 8.5 dict.test for how it does it, using a [getOrder] proc 
that ensures a known order.

Jeff

[Tcllib-devel] key order problem for dict

[KATO K. <k.k...@gm...>]

You know that Tcl interpreter doesn't ensure that dict key ordering.

That is not matter for almost cases.

But when we write test cases,
how to compare between program result and booked value?

Especially, it is difficult problem for multi rank dict.


Thoughts?



I wrote a proc, and replaced from [dict create $key_duplicated_dict].
(yaml.tcl)

# remove duplications with saving key order
proc ::yaml::_remove_duplication {dict} {
    array set tmp $dict
    array set tmp2 {}
    foreach {key nop} $dict {
        if [info exists tmp2($key)] continue
        lappend result $key $tmp($key)
        set tmp2($key) 1
    }
    return $result
}

Re: [Tcllib-devel] Tcl 8.2 support

[<dg...@ni...>]

Quoting Jeff Hobbs <je...@ac...>:
> ...  We also want to use 8.4 tcltest features in the test suite now.
  
Note that tcltest 2.2.9, the version bundled with Tcl 8.4.19 does *not*
require Tcl 8.4.  Works fine with Tcl 8.3.  Feel free to make your tests
for packages supporting Tcl 8.3 use the tcltest 2.2 features.

That is, failure to drop Tcl 8.3 support is not a matter holding back
test suite adoption of tcltest 2.2 features.

OTOH, tcltest 2.3.0, which comes with Tcl 8.5.*, actually requires
Tcl 8.5, since it makes some use of the new [info frame] features.

DGP

Re: [Tcllib-devel] Tcl 8.2 support

[Gerald W. L. <Ger...@co...>]

Jeff Hobbs wrote:
> Lars Hellström wrote:
>   
>> I can understand a policy of "don't make any changes to patches, or 
>> otherwise restrain your coding style, just for the sake of preserving 
>> compatibility with Tcl 8.x if x<4". I can also understand not wanting 
>> to entertain old Tcl versions just for the sake of testing tcllib 
>> releases, in the hope that someone, somewhere might appreciate it.
>>
>> On the other hand, denying the actual compatibility level of a piece of 
>> software feels rather artificial.
>>
>> Is the catch the uncertainty factor: that one can _presume_ a package 
>> works with Tcl 8.2 based on the features it uses, but won't really 
>> _know_ whether this is the case until having tested it on an actual Tcl 
>> 8.2 interpreter?
>>     
>
> This is the primary reason.  Unless someone else is secretly doing it, 
> tcllib hasn't been tested against anything below 8.4 in a long time.  We 
> also want to use 8.4 tcltest features in the test suite now.
>
> We have had issues where 8.4-isms crept into code that claimed to be 
> "8.2-compliant" and somebody noticed.  I contend that those people can 
> live with old bits if they want to live with old Tcl versions, and that 
> we should simply not encumber ourselves with development of tcllib to 
> anything prior to 8.4
Agreed, lets set 8.4 as the base and move on.

-- 
+--------------------------------+---------------------------------------+
| Gerald W. Lester                                                       |
|"The man who fights for his ideals is the man who is alive." - Cervantes|
+------------------------------------------------------------------------+

Re: [Tcllib-devel] Tcl 8.2 support

[Pat T. <pat...@us...>]

Jeff Hobbs <je...@ac...> writes:

>Lars Hellström wrote:
>> I can understand a policy of "don't make any changes to patches, or 
>> otherwise restrain your coding style, just for the sake of preserving 
>> compatibility with Tcl 8.x if x<4". I can also understand not wanting 
>> to entertain old Tcl versions just for the sake of testing tcllib 
>> releases, in the hope that someone, somewhere might appreciate it.
>> 
>> On the other hand, denying the actual compatibility level of a piece of 
>> software feels rather artificial.
>> 
>> Is the catch the uncertainty factor: that one can _presume_ a package 
>> works with Tcl 8.2 based on the features it uses, but won't really 
>> _know_ whether this is the case until having tested it on an actual Tcl 
>> 8.2 interpreter?
>
>This is the primary reason.  Unless someone else is secretly doing it, 
>tcllib hasn't been tested against anything below 8.4 in a long time.  We 
>also want to use 8.4 tcltest features in the test suite now.
>
>We have had issues where 8.4-isms crept into code that claimed to be 
>"8.2-compliant" and somebody noticed.  I contend that those people can 
>live with old bits if they want to live with old Tcl versions, and that 
>we should simply not encumber ourselves with development of tcllib to 
>anything prior to 8.4.

Pah. I test it occasionally with 8.2. Usually when a release is
up. However - I see no reason why people who stick with 10 year old
versions of Tcl shouldn't also stick with old versions of tcllib.

-- 
Pat Thoyts                            http://www.patthoyts.tk/
PGP fingerprint 2C 6E 98 07 2C 59 C8 97  10 CE 11 E6 04 E0 B9 DD

Re: [Tcllib-devel] Tcl 8.2 support

[Jeff H. <je...@ac...>]

Lars Hellström wrote:
> I can understand a policy of "don't make any changes to patches, or 
> otherwise restrain your coding style, just for the sake of preserving 
> compatibility with Tcl 8.x if x<4". I can also understand not wanting 
> to entertain old Tcl versions just for the sake of testing tcllib 
> releases, in the hope that someone, somewhere might appreciate it.
> 
> On the other hand, denying the actual compatibility level of a piece of 
> software feels rather artificial.
> 
> Is the catch the uncertainty factor: that one can _presume_ a package 
> works with Tcl 8.2 based on the features it uses, but won't really 
> _know_ whether this is the case until having tested it on an actual Tcl 
> 8.2 interpreter?

This is the primary reason.  Unless someone else is secretly doing it, 
tcllib hasn't been tested against anything below 8.4 in a long time.  We 
also want to use 8.4 tcltest features in the test suite now.

We have had issues where 8.4-isms crept into code that claimed to be 
"8.2-compliant" and somebody noticed.  I contend that those people can 
live with old bits if they want to live with old Tcl versions, and that 
we should simply not encumber ourselves with development of tcllib to 
anything prior to 8.4.

Jeff

Re: [Tcllib-devel] Tcl 8.2 support

[Lars H. <Lar...@re...>]

Andreas Kupries skrev:
>> Andreas Kupries wrote:
>>> * New packages have to promise to support at least Tcl 8.4.
>> One way to interpret that statement is that you will reject from
>> tcllib any packages that require Tcl 8.5.

In addition, out of context I'd interpret that as [package require Tcl 
8.3] being better than this minimum, [package require Tcl 8.2] being 
better still, and possibly [package require Tcl 8] being the optimum.

"Support at least" is confusing. (We're really considering a set of 
supported Tcl versions here, so "at least" should apply to the size of 
this set.) A phrase based on "require" would probably be clearer.

 >> Is that what you mean to say?
> 
> No. ... Let me see if I can be more clear.
> 
> New packages should promise to support Tcl 8.4 and higher, or promise to
> support Tcl 8.5 and higher.
> They should not promise to support a version below Tcl 8.4.

Gee... and I was just about to contribute a package that naturally 
comes in at [package require Tcl 8.2]. Better hurry it into CVS then? ;-)

I can understand a policy of "don't make any changes to patches, or 
otherwise restrain your coding style, just for the sake of preserving 
compatibility with Tcl 8.x if x<4". I can also understand not wanting 
to entertain old Tcl versions just for the sake of testing tcllib 
releases, in the hope that someone, somewhere might appreciate it.

On the other hand, denying the actual compatibility level of a piece of 
software feels rather artificial.

Is the catch the uncertainty factor: that one can _presume_ a package 
works with Tcl 8.2 based on the features it uses, but won't really 
_know_ whether this is the case until having tested it on an actual Tcl 
8.2 interpreter?

The rule that incrementing required Tcl version should lead to a (minor 
version) increment in package version seems wise.

Lars Hellström

Re: [Tcllib-devel] Tcl 8.2 support

[Andreas K. <and...@ac...>]

> Andreas Kupries wrote:
> > * New packages have to promise to support at least Tcl 8.4.
>
> One way to interpret that statement is that you will reject from
> tcllib any packages that require Tcl 8.5.  Is that what you mean
> to say?

No. ... Let me see if I can be more clear.

New packages should promise to support Tcl 8.4 and higher, or promise to
support Tcl 8.5 and higher.
They should not promise to support a version below Tcl 8.4.

--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122

Re: [Tcllib-devel] Tcl 8.2 support

[Jeff H. <je...@ac...>]

Andreas Kupries wrote:
> Note that I have said nothing about converting 8.3+ packages. This version
> of the core seems to be alive enough to keep that support around for a bit
> longer.

Who cares?  It is time for tcllib to be 8.4-based, period, end of paragraph.

8.3 users can stick with the ancient bits they like.

Jeff

[Tcllib-devel] Tcl 8.2 support

[Andreas K. <and...@ac...>]

In a recent patch I applied to the base64 package [1] I took out he supplied
'eq' and replaced it with 'string equal', to not break the promise of 8.2
compatibility the package has made. This prompted some discussion on the
tcler's chat and as a result of that discussion I am strongly considering
the following changes to our maintenance policies:

* New packages have to promise to support at least Tcl 8.4.

* Existing packages currently promising to support Tcl 8.2 are
  to be incrementally converted to 8.4 support.

  This conversion is likely done mostly on-demand, i.e. then
  patches for them arrive, however nothing speaks against a
  maintainer devoting some of their time to proactively convert
  packages as they have time.

  When converting a package to 8.4 the new version has to get a
  new minor version number. While the functionality has not changed
  doing this will allow users of the package to know exactly when
  8.4 support came into being and make a conscious choice whether
  to go to that version or not.

* Official testing of packages, i.e. for releases, is done only
  against Tcl 8.4 and 8.5 from now on.

  This change opens another venue for incremental improvement,
  that of the testsuites going from the old 8.0 format for
  test cases (name, description, ?constraints?, body) to the
  modern extensible option-based format (-body, -setup, -cleanup,
  ...).

Note that I have said nothing about converting 8.3+ packages. This version
of the core seems to be alive enough to keep that support around for a bit
longer.

Thoughts?

Some statistics.

	272	packages total
	  3	supporting 8.5+
	 73	supporting 8.4+
	 19	supporting 8.3+
	 97	supporting 8.2+
	  1	supporting 8.1+
	  4	supporting 8.0+
	  3	supporting 8+
	 72	undeclared what core is needed, assuming 8+.

[1]
https://sourceforge.net/tracker/?func=detail&atid=112883&aid=1969078&group_i
d=12883

--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122

Re: [Tcllib-devel] YAML load/dump library

[Andreas K. <and...@ac...>]

This library (rev 0.2.2) has been added to Tcllib.

Please welcome Kato Kanryu as the maintainer for that module.

--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122
 

> -----Original Message-----
> From: tcl...@li...
> [mailto:tcl...@li...]On Behalf Of KATO
> Kanryu
> Sent: Tuesday, April 22, 2008 2:14 AM
> To: tcl...@li...
> Subject: Re: [Tcllib-devel] YAML load/dump library
> 
> 
> > Thanks for this library. It looks good for a first pass.
> > You do have some very odd coding constructs that should be 
> corrected before release.
> Sorry, and Thanks.
> This library is my first lump of program in Tcl.
> So, there are many foolish logics in sourcecode, maybe. :(
> 
> > I think this is good for 0.1 commit, then fix after.
> Supposing it is adopted, I will welcome.
> 
> > but it looks like a rough conversion from another language (Perl?),
> That's right.
> The original library written in PHP.
> How to deal with container/structures differs considerably.
> 
> 
> 
> 
> Some amount of correction was made according to indication.
> http://knivez.homelinux.org/~spro/tcl/yapt-0.1.1.tar.gz
> 
> > * Use foreach instead of for constructs for lists
> > * Brace all expressions
> All "twirl-variables" on foreach-idiom to be braced.
> But "for constructs for lists", I don't understand these concrete places.
> Can I trouble you to show me there.
> 
> > * Some 'concat's look like string appending is meant
> > * Use 'eq' instead of string equal in exprs
> > * Use 'string match' instead of -length in some cases
> corrected
> 
> 
> > * Is 'isAliasNode' an incorrect conversion from Perl RE?
> now, "Alias Node" is no implemented in the library.
> So I comment outed the procedures.(and some not used)
> 
> 
> > * Use 'string is bool' over lsearch of type - if valid.
> It seems to be the treatment which is partly different.
> 
> Tcl:([string is true/false $token])
>  1 == {1 true yes or on}
>  0 == {0 false no off}
> YAML:
>  1 == {true on + yes y}
>  0 == {false off - no n}
> 
> However, I am seldom scrupulous about this point... :)
> 
> -------------------------------------------------------------------------
> This SF.net email is sponsored by the 2008 JavaOne(SM) Conference 
> Don't miss this year's exciting event. There's still time to save $100. 
> Use priority code J8TL2D2. 
> http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun
.com/javaone
_______________________________________________
Tcllib-devel mailing list
Tcl...@li...
https://lists.sourceforge.net/lists/listinfo/tcllib-devel

Re: [Tcllib-devel] Support for pictures (screenshots) in man pages?

[Andreas K. <and...@ac...>]

> Hello,

> I am thinking of writing a tutorial for Plotchart. Because
> Plotchart is all about the graphical presentation of data,
> I was wondering how I can include screenshots in that
> document. I would use the doctools to mark up the text
> of course, hence my question.

Currently doctools has no official support for images. There is only a
sort-of indirect support through the [uri] command which allows the
embedding of urls in a document.

However even in HTML this is formatted as an <a> tag, not as an <img>, i.e.
a link to the image, instead of an image embedded in the document.

The other formats are worse, as they can only embed the text of the url in
the output instead of the image itself.

Ok, that is the current state. Now what can we do about it ?

The only format in the Tcl world I am aware of which is similar (Text input,
multiple backends) is the TIP format. This format is described in
http://tip.tcl.tk/3 and actually handles images. It does so by having the
user specify a symbolic name and then letting the backend decide on the
actual name of the image file and how to embed it in the output document.
The relevant part of the TIP format specification is

	If the paragraph consists of the sequence "#image:"
	followed by some text, then it is a request to insert
	an image. The first word of the following text is a
	reference to the image, and the other words are an
	optional caption for the image (in plain text.) Image
	references that consist of just letters, numbers,
	hyphens and underscores are handled specially by the
	current implementation, which can map them to the
	correct media type for its current output format
	(assuming it has a suitable image in its repository.)

In essence you say

	#image: foo

and the backends then look for foo.png/gif/txt/ps/eps etc. and do the proper
embedding, i.e. direct insert, <img>-link, etc.

This is something I can see that we can add to doctools with relatively
little work.

Even so, if there are other ideas floating around I am interested in hearing
about them.


--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122