# See the file "COPYING" in the main distribution directory for copyright.

##! Functions for querying script, package, or variable documentation.

%%{
#include "zeek/zeekygen/Manager.h"
#include "zeek/zeekygen/IdentifierInfo.h"
#include "zeek/zeekygen/PackageInfo.h"
#include "zeek/zeekygen/ScriptInfo.h"
#include "zeek/util.h"

static zeek::StringValPtr comments_to_val(const vector<string>& comments)
	{
	return zeek::make_intrusive<zeek::StringVal>(zeek::util::implode_string_vector(comments));
	}
%%}

## Retrieve the Zeekygen-style comments (``##``) associated with an identifier
## (e.g. a variable or type).
##
## name: a script-level identifier for which to retrieve comments.
##
## Returns: comments associated with *name*.  If *name* is not a known
##          identifier, an empty string is returned.
function get_identifier_comments%(name: string%): string
	%{
	using namespace zeekygen;
	zeek::zeekygen::detail::IdentifierInfo* d = zeek::detail::zeekygen_mgr->GetIdentifierInfo(name->CheckString());

	if ( ! d )
		return zeek::val_mgr->EmptyString();

	return comments_to_val(d->GetComments());
	%}

## Retrieve the Zeekygen-style summary comments (``##!``) associated with
## a Zeek script.
##
## name: the name of a Zeek script.  It must be a relative path to where
##       it is located within a particular component of ZEEKPATH and use
##       the same file name extension/suffix as the actual file (e.g. ".zeek").
##
## Returns: summary comments associated with script with *name*.  If
##          *name* is not a known script, an empty string is returned.
function get_script_comments%(name: string%): string
	%{
	using namespace zeekygen;
	zeek::zeekygen::detail::ScriptInfo* d = zeek::detail::zeekygen_mgr->GetScriptInfo(name->CheckString());

	if ( ! d )
		return zeek::val_mgr->EmptyString();

	return comments_to_val(d->GetComments());
	%}

## Retrieve the contents of a Zeek script package's README file.
##
## name: the name of a Zeek script package.  It must be a relative path
##       to where it is located within a particular component of ZEEKPATH.
##
## Returns: contents of the package's README file.  If *name* is not a known
##          package, an empty string is returned.
function get_package_readme%(name: string%): string
	%{
	using namespace zeekygen;
	zeek::zeekygen::detail::PackageInfo* d = zeek::detail::zeekygen_mgr->GetPackageInfo(name->CheckString());

	if ( ! d )
		return zeek::val_mgr->EmptyString();

	return comments_to_val(d->GetReadme());
	%}

## Retrieve the Zeekygen-style comments (``##``) associated with a record field.
##
## name: the name of a record type and a field within it formatted like
##       a typical record field access: "<record_type>$<field>".
##
## Returns: comments associated with the record field.  If *name* does
##          not point to a known record type or a known field within a record
##          type, an empty string is returned.
function get_record_field_comments%(name: string%): string
	%{
	using namespace zeekygen;
	string accessor = name->CheckString();
	size_t i = accessor.find('$');

	if ( i > accessor.size() - 2 )
		return zeek::val_mgr->EmptyString();

	string id = accessor.substr(0, i);

	zeek::zeekygen::detail::IdentifierInfo* d = zeek::detail::zeekygen_mgr->GetIdentifierInfo(id);

	if ( ! d )
		return zeek::val_mgr->EmptyString();

	string field = accessor.substr(i + 1);
	return comments_to_val(d->GetFieldComments(field));
	%}
