api_read_script_documentation (public)

 api_read_script_documentation path

Defined in packages/acs-api-browser/tcl/acs-api-documentation-procs.tcl

Reads the contract from a Tcl content page.

Parameters:

path (required)

the path of the Tcl file to examine, relative to the OpenACS root directory.

Returns:

a list representation of the documentation element array, or an empty list if the file does not contain a doc_page_contract block.

Error:

if the file does not exist.

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

Testcases:

acs_api_browser_api_read_script_documentation

Source code:

    # First, examine the file to determine whether the first non-comment
    # line begins with the string "ad_page_contract".
    set has_contract_p 0

    if { ![file exists "$::acs::rootdir/$path"] } {
        error "File $path does not exist"
    }

    set file [open "$::acs::rootdir/$path" "r"]
    while { [gets $file line] >= 0 } {
        # Eliminate any comment characters.
        regsub -all -- {\#.*$} $line "" line
        set line [string trim $line]
        if { $line ne "" } {
            set has_contract_p [regexp {(^ad_(page|include)_contract\s)|(Package initialize )} $line]
            break
        }
    }
    close $file

    if { !$has_contract_p } {
        return [list]
    }

    doc_set_page_documentation_mode 1
    #ns_log notice "Sourcing $::acs::rootdir/$path in documentation mode"
    ad_try {
        #
        # Sourcing in documentation mode fills "doc_elements"
        #
        source "$::acs::rootdir/$path"
    } on error {errorMsg} {
        #
        # This is a strange construct: in case, the ::$errorInfo
        # starts with ad_page_contract, we get the documentation
        # elements from the $errorMsg
        #
        if {[regexp {^ad_page_contract documentation} $::errorInfo] } {
            array set doc_elements $errorMsg
        } else {
            ns_log notice "api_read_script_documentation: got unexpected result while sourcing $::acs::rootdir/$path $errorMsg"
            return -code error $errorMsg
        }
    } finally {
        doc_set_page_documentation_mode 0
    }

    return [array get doc_elements]

XQL Not present:

Generic, PostgreSQL, Oracle