[Xotcl] Re: XOTcl 0.83 questions (bugs?)

[Gustaf Neumann]

>>>>> "Zoran" == Zoran Vasiljevic <zoran at munich.com> writes:

Zoran> Hi Uwe and Gustaf !
Zoran> This is one of the first messages in sequence, you're going
Zoran> to receive from me. I'm sorry for (eventual) inconvenience
Zoran> but I have to master this great package and there is nobody
Zoran> else to ask !

Dear Zoran, 

many thanks for your feedback. i am pretty sure, uwe is currently
preparing an email concerning the assertion issues.... so i all
address the later issues.

Zoran> subject. Also, need some examples for "parameterclass".
Zoran> Reference mentions it but the tutorial is silent abut it ???
Zoran> Have any working code which uses them ?

The basic idea is to make the parameter mechanism in a similar way
extensible as the extension mechanisms work for normal oo-methods. One
can extend the predefined Class::Parameters class with someInstproc
and use later

    C c1 {{a -default 1 -someInstproc x} ...}

or subclcass it like

    Class MyParameters -superclass Class::Parameters
    Class X -parameterclass MyParameters -parameters ......                                                                             
The parameter classes are still in an early state, we are not happy
about the need to specify -parameterclass for interesting cases, and
we hope to find more elegant ways to express these semantics. Here is
an simple example for illustration:

===========================================================================
Class::Parameter instproc comments {param args} {
  puts "[self] [self class] parameter: $param args: $args"
}
Class::Parameter instproc values {param args} {
  set ci [[self class] info instinvar]
  set valueTest {}
  foreach a $args {
    lappend valueTest "\[\[self\] set $param\] == [list $a]"
  }
  lappend ci [join $valueTest " || "]
  [self] instinvar $ci
}
 
Class X -parameter {
  {a 1 2 3 -comments a b c d e}
  {b -default 2 -comments 1 2 3 4}
  {e -default 3 -values 1 2 3}
  {Self -default [self]}
}
X instproc checkInvar {} {
  [self] check instinvar
  [self] set e 9
}
X x -checkInvar

 
Class C -superclass {Class::Parameter Class}
C instproc comments {param args} {
  puts "[self] [self class] parameter: $param args: $args"
  next
}
Class Y -superclass X -parameterclass C -parameter {
    {a 1 2 3 -comments a b c d e}
    {b -default 2 -comments 1 2 3 4}
    {e -default 3 -values 1 2 3}
    {Self -default [self]}
}
Y y -checkInvar
===========================================================================

Zoran> What the heck is the "@" good for ???
Zoran> I notice such constructs in your code pretty often...

Zoran> Class SomeClass
Zoran> @ @File {description {
Zoran> This is a file which provides a blablablabla....
Zoran> }
Zoran> }

Zoran> What does this mean ?

the @ is used for documentation issues: check out
xotcl/doc/langRef.xotcl for the largest example.  The basic ideas
behind xoDoc are:

  - the comments are first class xotcl commands; by defining 
    alternate @ commands (e.g. via per object mixins etc),
    one can do different things with the comments;
    currently, we have only the HTML backend, but the basic idea is to
    provide support for several other usages as well (e.g. XML, RDF,
    online help, documentation of dynamic structures, etc).
 
  - We have an Object "@" that handles comments via
    its unknown method. xoDoc adds the appropriate instprocs to @
    to produce HTML output. The appropriate command is:
      xotclsh src/lib/makeDoc.xotcl <DOCDIR> <DOCFILES>
 
  - The source of a documentation is structurally very similar to 
    the xotcl constructs being commented. e.g. one can copy an 
    instproc and add comments at the right places. eg.
 
    Class C
    C instproc m {a1 a2} {
       return [expr {$a1+$a2}]
    }
 
    can be commented as follows
 
    @ Class C { description { "my sample class"} }
    @ C instproc m {a1 "first number" a2 "second number"} {
       description "add two numbers"
       return "sum of a1 and a2"
    }
 
   One can do essentially a copy+paste of the source and add
   the comments via  attribute value pairs, every basic language
   construct can have a "description". If you want to include
   other properties to the description, you can add e.g.

    @ C instproc m {a1 "first number" a2 "second number"} {
       author "GN+UZ"
       date "Feb 31"
       description "add two numbers"
       return "sum of a1 and a2"
    }
 
    This way, author and date are added automatically to the generated
    HTML file.
    
    In addition, there is a @File hook for a per file description.

Zoran> Cheer's (and thanks for help!)
Zoran> Zoran

Hope this helps
-gustaf

Zoran> ______________________________________________
Zoran> FREE Personalized Email at Mail.com
Zoran> Sign up at http://www.mail.com/?sr=signup