Error processing request
Parameters
CONTENT_LENGTH | 0 |
REQUEST_METHOD | GET |
REQUEST_URI | /revision/docstring?V=23 |
QUERY_STRING | V=23 |
CONTENT_TYPE | |
DOCUMENT_URI | /revision/docstring |
DOCUMENT_ROOT | /var/www/nikit/nikit/nginx/../docroot |
SCGI | 1 |
SERVER_PROTOCOL | HTTP/1.1 |
HTTPS | on |
REMOTE_ADDR | 172.70.130.136 |
REMOTE_PORT | 62056 |
SERVER_PORT | 4443 |
SERVER_NAME | wiki.tcl-lang.org |
HTTP_HOST | wiki.tcl-lang.org |
HTTP_CONNECTION | Keep-Alive |
HTTP_ACCEPT_ENCODING | gzip, br |
HTTP_X_FORWARDED_FOR | 3.137.178.133 |
HTTP_CF_RAY | 87a611413e1e2d4c-ORD |
HTTP_X_FORWARDED_PROTO | https |
HTTP_CF_VISITOR | {"scheme":"https"} |
HTTP_ACCEPT | */* |
HTTP_USER_AGENT | Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; [email protected]) |
HTTP_CF_CONNECTING_IP | 3.137.178.133 |
HTTP_CDN_LOOP | cloudflare |
HTTP_CF_IPCOUNTRY | US |
Body
Error
Unknow state transition: LINE -> END
-code
1
-level
0
-errorstack
INNER {returnImm {Unknow state transition: LINE -> END} {}} CALL {my render_wikit docstring {if 0 {[Richard Suchenwirth] 2004-01-25 - Languages like [Lisp] and [Python] have
the ''docstring'' feature, where a string in the beginning of a function
can be retrieved for on-line (or printed) documentation. Tcl doesn't
have this mechanism built-in (and it would be hard to do it exactly the
same way, because [everything is a string]), but a similar mechanism can
easily be adopted, and it doesn't look bad in comparison:
* Common Lisp: (documentation 'foo 'function)
* Python: foo.__doc__
* Tcl: docstring foo
If the docstring is written in comments at the top of a proc body, it is
easy to parse it out. In addition, for all procs, even without
docstring, you get the "signature" (proc name and arguments with
defaults). The code below also serves as usage example:
}
======
proc docstring procname {
# reports a proc's args and leading comments.
# Multiple documentation lines are allowed.
set res "{usage: $procname [uplevel 1 [list args $procname]]}"
# This comment should not appear in the docstring
foreach line [split [uplevel 1 [list info body $procname]]] {
if {[string trim $line] eq ""} continue
if ![regexp {\s*#(.+)} $line -> line] break
lappend res [string trim $line]
}
join $res
}
proc args procname {
# Signature of a proc: arguments with defaults
set res ""
foreach a [info args $procname] {
if [info default $procname $a default] {
lappend a $default
}
lappend res $a
}
set res
}
======
if 0 {Testing:
% docstring docstring
usage: docstring procname
reports a proc's args and leading comments.
Multiple documentation lines are allowed.
% docstring args
usage: args procname
Signature of a proc: arguments with defaults
}
----
[NEM] (23Feb2005) offers the following simple proc:
======
# describe.tcl --
#
# Simple documentation comments.
#
# Copyright (c) 2005 Neil Madden.
# License: Tcl/BSD-style
package provide describe 1.0
namespace eval describe {
variable desc
array set desc {}
}
proc describe {cmd args} {
if {[llength $args] > 1} {
return -code error
"wrong # args: should be "describe cmd ?description?"
}
set name [uplevel 1 [list namespace which -command $cmd]]
if {[llength $args] == 1} {
set ::describe::desc($name) [lindex $args 0]
} else {
if {[info exists ::describe::desc($name)]} {
return $::describe::desc($name)
} else {
return "no description available"
}
}
}
======
describe describe "usage: describe cmd ?description?
Gets or sets a textual description associated with a command."
It works like so:
% describe describe
usage: describe cmd ?description?
Gets or sets a textual description associated with a command.
% describe set
no description available
% describe set "usage: set var ?value?
Gets or sets the current value of a variable"
usage: set var ?value?
Gets or sets the current value of a variable
% describe set
usage: set var ?value?
Gets or sets the current value of a variable
Advantages are that it separates the documentation from the implementation of a command, so you can add descriptions for C-coded commands (including built-ins), and you could localise the descriptions by having separate description files loaded for different languages (useful if you were using the descriptions for [tooltip]s in a GUI, say). It also works for objects, widgets, etc - anything which has a command interface. Disadvantages are that it separates the documentation from the implementation of a command ;) i.e. the descriptions may not be next to the implementations, so people may forget to keep them up-to-date.
----
[LES] on 20070528: I use a slightly different approach. I have a big mama file with lots of procs that I reuse all the time and sometimes I forget how to use one of them. Since I am on [Tkcon] most of the time, I implemented it like this:
======
proc procdoc {args} {
# proc 2 of 86
# prints the name, arguments and documentation of current parent proc
# it accepts "args", but only ? is recognized to trigger this help text
if {[lindex $args 1] == "?" } {procdoc}
set _wholeProc [info level -1]
set _procName [@ $_wholeProc 0]
set _procArgs [info args $_procName]
set _procBody [info body $_procName]
# set initial ProcDoc content:
set _procDoc "$_procName $_procArgs \n\n"
# turn proc's body into a list
set _procBody [split $_procBody "\n"]
# remove first element because it is always empty
set _procBody [lrange $_procBody 1 end]
# iterate on _procBody
# keep getting lines that start with #; stop when we run out of them
for {set i 0} {$i < [llength $_procBody]} {incr i} {
set _line [lindex $_procBody $i]
if {[regexp {^\s*#.*} $_line] == 0} {break}
append _procDoc "$_line\n"
}
# remove trailing line break
regsub (.*)\n $_procDoc \\1 _procDoc
return "usage: $_procDoc"
}
======
Which captures the initial comments in all other procs that contain the magic line ('''if {[[lindex [[info level 0]] 1]] == "?"} {procdoc; return}''') and displays them whenever '''"?"''' is the first argument (the proc may require several arguments):
======
proc demonstration {thisArg thatArg} {
# proc 19 of 86
# Two arguments required: thisArg does this, thatArg does that.
# This proc is a quick and dirty demonstration
# to those nice folks at wiki.tcl.tk
# Every proc has to contain this next line:
if {[lindex [info level 0] 1] == "?"} {procdoc; return}
catch {{do some stuff} dothis dothat} Data
return $Data
}
======
Test:
% demonstration ?
wrong # args: should be "demonstration thisArg thatArg ..."
% demonstration ? ?
usage: demonstration thisArg thatArg
# proc 19 of 86
# Two arguments required: thisArg does this, thatArg does that.
# This proc is a quick and dirty demonstration
# to those nice folks at wiki.tcl.tk
# Every proc has to contain this next line:
''But the error itself (introspection) is enough to provide the required arguments'', you'd think. Yes, but it does not provide the detailed explanation. Most of my procs take just one or no argument, so I usually get my little canned help right away instead of the error message.
======
My <a href="http://balkansoft.blogspot.com/2012/03/docstrings-in-tcl-and-incrtcl.html">variant</a> supports Itcl classes, usual procs, also generates documentation file (in .rst format)
----
!!!!!!
%| [Category Documentation] |%
[Arts and crafts of Tcl-Tk programming]
!!!!!!} regexp2} CALL {my render docstring {if 0 {[Richard Suchenwirth] 2004-01-25 - Languages like [Lisp] and [Python] have
the ''docstring'' feature, where a string in the beginning of a function
can be retrieved for on-line (or printed) documentation. Tcl doesn't
have this mechanism built-in (and it would be hard to do it exactly the
same way, because [everything is a string]), but a similar mechanism can
easily be adopted, and it doesn't look bad in comparison:
* Common Lisp: (documentation 'foo 'function)
* Python: foo.__doc__
* Tcl: docstring foo
If the docstring is written in comments at the top of a proc body, it is
easy to parse it out. In addition, for all procs, even without
docstring, you get the "signature" (proc name and arguments with
defaults). The code below also serves as usage example:
}
======
proc docstring procname {
# reports a proc's args and leading comments.
# Multiple documentation lines are allowed.
set res "{usage: $procname [uplevel 1 [list args $procname]]}"
# This comment should not appear in the docstring
foreach line [split [uplevel 1 [list info body $procname]]] {
if {[string trim $line] eq ""} continue
if ![regexp {\s*#(.+)} $line -> line] break
lappend res [string trim $line]
}
join $res
}
proc args procname {
# Signature of a proc: arguments with defaults
set res ""
foreach a [info args $procname] {
if [info default $procname $a default] {
lappend a $default
}
lappend res $a
}
set res
}
======
if 0 {Testing:
% docstring docstring
usage: docstring procname
reports a proc's args and leading comments.
Multiple documentation lines are allowed.
% docstring args
usage: args procname
Signature of a proc: arguments with defaults
}
----
[NEM] (23Feb2005) offers the following simple proc:
======
# describe.tcl --
#
# Simple documentation comments.
#
# Copyright (c) 2005 Neil Madden.
# License: Tcl/BSD-style
package provide describe 1.0
namespace eval describe {
variable desc
array set desc {}
}
proc describe {cmd args} {
if {[llength $args] > 1} {
return -code error
"wrong # args: should be "describe cmd ?description?"
}
set name [uplevel 1 [list namespace which -command $cmd]]
if {[llength $args] == 1} {
set ::describe::desc($name) [lindex $args 0]
} else {
if {[info exists ::describe::desc($name)]} {
return $::describe::desc($name)
} else {
return "no description available"
}
}
}
======
describe describe "usage: describe cmd ?description?
Gets or sets a textual description associated with a command."
It works like so:
% describe describe
usage: describe cmd ?description?
Gets or sets a textual description associated with a command.
% describe set
no description available
% describe set "usage: set var ?value?
Gets or sets the current value of a variable"
usage: set var ?value?
Gets or sets the current value of a variable
% describe set
usage: set var ?value?
Gets or sets the current value of a variable
Advantages are that it separates the documentation from the implementation of a command, so you can add descriptions for C-coded commands (including built-ins), and you could localise the descriptions by having separate description files loaded for different languages (useful if you were using the descriptions for [tooltip]s in a GUI, say). It also works for objects, widgets, etc - anything which has a command interface. Disadvantages are that it separates the documentation from the implementation of a command ;) i.e. the descriptions may not be next to the implementations, so people may forget to keep them up-to-date.
----
[LES] on 20070528: I use a slightly different approach. I have a big mama file with lots of procs that I reuse all the time and sometimes I forget how to use one of them. Since I am on [Tkcon] most of the time, I implemented it like this:
======
proc procdoc {args} {
# proc 2 of 86
# prints the name, arguments and documentation of current parent proc
# it accepts "args", but only ? is recognized to trigger this help text
if {[lindex $args 1] == "?" } {procdoc}
set _wholeProc [info level -1]
set _procName [@ $_wholeProc 0]
set _procArgs [info args $_procName]
set _procBody [info body $_procName]
# set initial ProcDoc content:
set _procDoc "$_procName $_procArgs \n\n"
# turn proc's body into a list
set _procBody [split $_procBody "\n"]
# remove first element because it is always empty
set _procBody [lrange $_procBody 1 end]
# iterate on _procBody
# keep getting lines that start with #; stop when we run out of them
for {set i 0} {$i < [llength $_procBody]} {incr i} {
set _line [lindex $_procBody $i]
if {[regexp {^\s*#.*} $_line] == 0} {break}
append _procDoc "$_line\n"
}
# remove trailing line break
regsub (.*)\n $_procDoc \\1 _procDoc
return "usage: $_procDoc"
}
======
Which captures the initial comments in all other procs that contain the magic line ('''if {[[lindex [[info level 0]] 1]] == "?"} {procdoc; return}''') and displays them whenever '''"?"''' is the first argument (the proc may require several arguments):
======
proc demonstration {thisArg thatArg} {
# proc 19 of 86
# Two arguments required: thisArg does this, thatArg does that.
# This proc is a quick and dirty demonstration
# to those nice folks at wiki.tcl.tk
# Every proc has to contain this next line:
if {[lindex [info level 0] 1] == "?"} {procdoc; return}
catch {{do some stuff} dothis dothat} Data
return $Data
}
======
Test:
% demonstration ?
wrong # args: should be "demonstration thisArg thatArg ..."
% demonstration ? ?
usage: demonstration thisArg thatArg
# proc 19 of 86
# Two arguments required: thisArg does this, thatArg does that.
# This proc is a quick and dirty demonstration
# to those nice folks at wiki.tcl.tk
# Every proc has to contain this next line:
''But the error itself (introspection) is enough to provide the required arguments'', you'd think. Yes, but it does not provide the detailed explanation. Most of my procs take just one or no argument, so I usually get my little canned help right away instead of the error message.
======
My <a href="http://balkansoft.blogspot.com/2012/03/docstrings-in-tcl-and-incrtcl.html">variant</a> supports Itcl classes, usual procs, also generates documentation file (in .rst format)
----
!!!!!!
%| [Category Documentation] |%
[Arts and crafts of Tcl-Tk programming]
!!!!!!}} CALL {my revision docstring} CALL {::oo::Obj1499556 process revision/docstring} CALL {::oo::Obj1499554 process}
-errorcode
NONE
-errorinfo
Unknow state transition: LINE -> END
while executing
"error $msg"
(class "::Wiki" method "render_wikit" line 6)
invoked from within
"my render_$default_markup $N $C $mkup_rendering_engine"
(class "::Wiki" method "render" line 8)
invoked from within
"my render $name $C"
(class "::Wiki" method "revision" line 31)
invoked from within
"my revision $page"
(class "::Wiki" method "process" line 56)
invoked from within
"$server process [string trim $uri /]"
-errorline
4