doc::parse_namespace (private)

 doc::parse_namespace text_lines

Defined in packages/acs-templating/tcl/doc-tcl-procs.tcl

text between two namespace markers in a Tcl library file and parses out procedure source and comments

Parameters:

text_lines (required)

namespace text body

Author:

simon

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Source code:

    # total_result_listing will contain our complete data set,
    # namespace_list is just a temp variable used for easy bookkeeping;
    # it contains an alphabetized lists of namespaces only
    upvar 2 result total_result_listing
    upvar 2 namespace_list namespace_list

    set text_list $text_lines
    if { [doc::util::text_divider text_list {\n#\s*@(?:public|private)\s+} ] } {
        # @private or @public directives were found, continue with parsing
    } else {
        return 0
    }

    # before parsing out the proc info, we'll deal with the comments for the namespace itself

    set namespace_comments [lindex $text_list 0 ]

    set parsed_namespace [template::parse_directives [template::util::quote_space $namespace_comments]]

    # just in case these variables aren't set from the comment text
    set namespace_author ""
    set namespace_see ""
    set has_comments 0

    foreach directive $parsed_namespace {
        set directive_type [lindex $directive 0]
        set directive_comments [template::util::comment_text_normalize [lindex $directive 1]]

        switch -exact $directive_type {

            namespace {

                set namespace_name [lindex $directive_comments 0]
                set namespace_description [lrange $directive_comments 1 end]
                if {$namespace_description ne "" } {
                    set has_comments 1
                }
            }

            see {
                doc::sort_see namespace_$directive_type $directive_comments
                set has_comments 1
            }

            author {
                set namespace_author $directive_comments
                set has_comments 1
            }
        }
    }

    #
    # The variable "has_comments" is set to 1 if it appears as though
    # descriptive comments were written to describe the namespace --
    # as would be expected if the namespace were being described for
    # the first time; otherwise it is set to 0; the problem i'm trying
    # to resolve here is multiple uses of the @namespace directive and
    # determining which occurrence of the directive is followed by
    # comments by comments we want to parse into our static files.
    #
    # namespace_index tells us where to insert the info, or is -1 if
    # the namespace has already been described
    set namespace_index [template::util::alphabetized_index $namespace_list $namespace_name]


    if { $namespace_index == -1 } {
        # this namespace is already recorded, so we will just add
        # or revise info about its procs

        set namespace_entry [lindex $total_result_listing [lsearch -exact $namespace_list $namespace_name]]

        set namespace_info [lindex $namespace_entry 0 1]
        set namespace_public [lindex $namespace_entry 1 1]
        set namespace_private [lindex $namespace_entry 2 1]

    } else {
        set namespace_info [list name "$namespace_name" overview "$namespace_description" author "$namespace_author" see "$namespace_see"]
        set namespace_public ""
        set namespace_private ""

    }

    if { $has_comments } {

        # this check determines whether or not we want the comments
        # following this occurrence of the @namespace directive for
        # this namespace to be included in our static files

        set namespace_info [list name "$namespace_name" overview "$namespace_description" author "$namespace_author" see "$namespace_see"]

    }

    set procedure_list [lrange $text_list 1 end]

    foreach proc_block $procedure_list {

        # each pro_block text block contains both the directive-marked comments and
        # the source code for the procedure
        doc::parse_comment_text $proc_block
    }

    if { $namespace_index >= 0 } {
        # if the namespace has not already been described, then we group all info together
        # {{info - name, overview} {public proc info} {private proc info}}
        # and insert it into the monster list of all namespaces

        set total_result_listing [linsert $total_result_listing $namespace_index [list [list info $namespace_info] [list public $namespace_public] [list private $namespace_private]]]

        set namespace_list [linsert $namespace_list $namespace_index $namespace_name]

    } else {

        # the name and overview info is already set, we'll just replace the augmented
        # listings for private and public procedures

        set namespace_index [lsearch -exact $namespace_list $namespace_name ]

        lset total_result_listing $namespace_index [list [list info "$namespace_info"] [list public "$namespace_public"] [list private "$namespace_private"]]
    }

XQL Not present:

Generic, PostgreSQL, Oracle