Forum OpenACS Development: Re: Tcl Web Services Toolkit: TWiST

Collapse
Posted by Tom Jackson on
Malte said:

And for the documentation, at the moment I always have to manually go into the tcl directory to find the procedure. This is why I would love to exchange all occurances of "proc ::" with "ad_proc ::", so at least the procedure is avialable for browsing in the ACS API and I do not have to go back to the shell, go to the directory, open the file,search for the procedure, look what it does and what variables it expects and what variables it returns. This makes development really burdensome 😊. This could be quickly fixed by you however. Just have a wrapper in init.tcl like:

You will not get very far with tWSDL or TWiST if you rely on the _static_ definition of ad_proc. You should use the inspect package which is part of tWSDL. You mount inspect anywhere you wish, by creating a symlink. I don't expect everyone to agree with me, but inspect gives you the current state of namespace variables and procedures, not what you think they are, or were at one point in time. Since most of the code in TWiST is autogenerated, you have to use something like this.

I know that as of right now, <ws>type and <ws>element are not documented, they are still in development and subject to minor changes. This does not mean that I need to rush out and use ad_proc, which would help nobody. I'm not really sure why anyone would recommend this. Did someone really do such a thing with tDOM, or with tcllib? How about Tcl itself? The world does not revolve around the OpenACS API, and complaints of this sort don't help anyone or solve any real problem. In fact, if I followed your instructions, the package would immediately only work for full installations of OpenACS. But, my goal is to abstract out even the dependencies on AOLserver, which will take very few hours as it only involves _one_ procedure in all of tWSDL! In the same way, I'm sure we can come up with a very thin layer to integrate TWiST with OpenACS, but not by hacking away on code which works.

Please keep in mind that TWiST is a _user_ API, tWSDL is a developer API. Unless you are very comfortable with how both work, it is way premature to start 'fixing' any code.

Collapse
Posted by Malte Sussdorff on
Contrary to perception, I looked at the inspect code before working on anything and have to say, I do not share your believes. But that is fine. I would only suggest to keep the proc definition and the arg_parser close to each other, as http://e4.cognovis.biz/twsdl/inspect/ns.tcl?ns=::pm::task is already hard to read but with both of them seperated it is even harder (again, only in my opinion and I do not have to rely on it).

My suggestion for ad_proc also and solemnly was referring to the procedures which we are actually using to create the webservices, not the auto generated code. Obviously that would be a little bit harder to achieve. Though I still think having support for < wsdl:documentation > would come in handy (but maybe it already does this and I just did not find in the documentation where). The way I would probably find ist useful:

< ws >type pattern datetime::year $yearAnchored xsd:integer documentation:"Year of the datetime"

Or use the way your hated (sorry 😊 ) ad_proc does it for procedures

< ws >proc ::datetime::DayNameFromNumber {
{DayNumber:datetime::dayNumber}
} {
Returns the day of the week for a given number
} {
return .....
} returns {DayName:datetime::dayName}

Please be not offended by this suggestion. If you don't like it throw it away. I would be pleased to see your suggestions for creation and integration of < wsdl:documentation > tags, especially using the < ws > procedure.