solidity/libsolidity/InterfaceHandler.cpp

#include <libsolidity/InterfaceHandler.h>
#include <libsolidity/AST.h>
#include <libsolidity/CompilerStack.h>
using namespace std;

namespace dev
{
namespace solidity
{

/* -- public -- */

InterfaceHandler::InterfaceHandler()
{
	m_lastTag = DocTagType::None;
}

string InterfaceHandler::documentation(
	ContractDefinition const& _contractDef,
	DocumentationType _type
)
{
	switch(_type)
	{
	case DocumentationType::NatspecUser:
		return userDocumentation(_contractDef);
	case DocumentationType::NatspecDev:
		return devDocumentation(_contractDef);
	case DocumentationType::ABIInterface:
		return abiInterface(_contractDef);
	case DocumentationType::ABISolidityInterface:
		return ABISolidityInterface(_contractDef);
	}

	BOOST_THROW_EXCEPTION(InternalCompilerError() << errinfo_comment("Unknown documentation type"));
	return "";
}

string InterfaceHandler::abiInterface(ContractDefinition const& _contractDef)
{
	Json::Value abi(Json::arrayValue);

	auto populateParameters = [](vector<string> const& _paramNames, vector<string> const& _paramTypes)
	{
		Json::Value params(Json::arrayValue);
		solAssert(_paramNames.size() == _paramTypes.size(), "Names and types vector size does not match");
		for (unsigned i = 0; i < _paramNames.size(); ++i)
		{
			Json::Value param;
			param["name"] = _paramNames[i];
			param["type"] = _paramTypes[i];
			params.append(param);
		}
		return params;
	};

	for (auto it: _contractDef.interfaceFunctions())
	{
		auto externalFunctionType = it.second->externalFunctionType();
		Json::Value method;
		method["type"] = "function";
		method["name"] = it.second->declaration().name();
		method["constant"] = it.second->isConstant();
		method["inputs"] = populateParameters(
			externalFunctionType->parameterNames(),
			externalFunctionType->parameterTypeNames()
		);
		method["outputs"] = populateParameters(
			externalFunctionType->returnParameterNames(),
			externalFunctionType->returnParameterTypeNames()
		);
		abi.append(method);
	}
	if (_contractDef.constructor())
	{
		Json::Value method;
		method["type"] = "constructor";
		auto externalFunction = FunctionType(*_contractDef.constructor()).externalFunctionType();
		solAssert(!!externalFunction, "");
		method["inputs"] = populateParameters(
			externalFunction->parameterNames(),
			externalFunction->parameterTypeNames()
		);
		abi.append(method);
	}

	for (auto const& it: _contractDef.interfaceEvents())
	{
		Json::Value event;
		event["type"] = "event";
		event["name"] = it->name();
		event["anonymous"] = it->isAnonymous();
		Json::Value params(Json::arrayValue);
		for (auto const& p: it->parameters())
		{
			Json::Value input;
			input["name"] = p->name();
			input["type"] = p->type()->toString(true);
			input["indexed"] = p->isIndexed();
			params.append(input);
		}
		event["inputs"] = params;
		abi.append(event);
	}
	return Json::FastWriter().write(abi);
}

string InterfaceHandler::ABISolidityInterface(ContractDefinition const& _contractDef)
{
	string ret = "contract " + _contractDef.name() + "{";

	auto populateParameters = [](vector<string> const& _paramNames, vector<string> const& _paramTypes)
	{
		string r = "";
		solAssert(_paramNames.size() == _paramTypes.size(), "Names and types vector size does not match");
		for (unsigned i = 0; i < _paramNames.size(); ++i)
			r += (r.size() ? "," : "(") + _paramTypes[i] + " " + _paramNames[i];
		return r.size() ? r + ")" : "()";
	};
	if (_contractDef.constructor())
	{
		auto externalFunction = FunctionType(*_contractDef.constructor()).externalFunctionType();
		solAssert(!!externalFunction, "");
		ret +=
			"function " +
			_contractDef.name() +
			populateParameters(externalFunction->parameterNames(), externalFunction->parameterTypeNames()) +
			";";
	}
	for (auto const& it: _contractDef.interfaceFunctions())
	{
		ret += "function " + it.second->declaration().name() +
			populateParameters(it.second->parameterNames(), it.second->parameterTypeNames()) +
			(it.second->isConstant() ? "constant " : "");
		if (it.second->returnParameterTypes().size())
			ret += "returns" + populateParameters(it.second->returnParameterNames(), it.second->returnParameterTypeNames());
		else if (ret.back() == ' ')
			ret.pop_back();
		ret += ";";
	}

	return ret + "}";
}

string InterfaceHandler::userDocumentation(ContractDefinition const& _contractDef)
{
	Json::Value doc;
	Json::Value methods(Json::objectValue);

	for (auto const& it: _contractDef.interfaceFunctions())
	{
		Json::Value user;
		auto strPtr = it.second->documentation();
		if (strPtr)
		{
			resetUser();
			parseDocString(*strPtr, CommentOwner::Function);
			if (!m_notice.empty())
			{// since @notice is the only user tag if missing function should not appear
				user["notice"] = Json::Value(m_notice);
				methods[it.second->externalSignature()] = user;
			}
		}
	}
	doc["methods"] = methods;

	return Json::StyledWriter().write(doc);
}

string InterfaceHandler::devDocumentation(ContractDefinition const& _contractDef)
{
	// LTODO: Somewhere in this function warnings for mismatch of param names
	// should be thrown
	Json::Value doc;
	Json::Value methods(Json::objectValue);

	auto contractDoc = _contractDef.documentation();
	if (contractDoc)
	{
		m_contractAuthor.clear();
		m_title.clear();
		parseDocString(*contractDoc, CommentOwner::Contract);

		if (!m_contractAuthor.empty())
			doc["author"] = m_contractAuthor;

		if (!m_title.empty())
			doc["title"] = m_title;
	}

	for (auto const& it: _contractDef.interfaceFunctions())
	{
		Json::Value method;
		auto strPtr = it.second->documentation();
		if (strPtr)
		{
			resetDev();
			parseDocString(*strPtr, CommentOwner::Function);

			if (!m_dev.empty())
				method["details"] = Json::Value(m_dev);

			if (!m_author.empty())
				method["author"] = m_author;

			Json::Value params(Json::objectValue);
			vector<string> paramNames = it.second->parameterNames();
			for (auto const& pair: m_params)
			{
				if (find(paramNames.begin(), paramNames.end(), pair.first) == paramNames.end())
					// LTODO: mismatching parameter name, throw some form of warning and not just an exception
					BOOST_THROW_EXCEPTION(
						DocstringParsingError() <<
						errinfo_comment("documented parameter \"" + pair.first + "\" not found in the parameter list of the function.")
					);					
				params[pair.first] = pair.second;
			}

			if (!m_params.empty())
				method["params"] = params;

			if (!m_return.empty())
				method["return"] = m_return;

			if (!method.empty()) // add the function, only if we have any documentation to add
				methods[it.second->externalSignature()] = method;
		}
	}
	doc["methods"] = methods;

	return Json::StyledWriter().write(doc);
}

/* -- private -- */
void InterfaceHandler::resetUser()
{
	m_notice.clear();
}

void InterfaceHandler::resetDev()
{
	m_dev.clear();
	m_author.clear();
	m_return.clear();
	m_params.clear();
}

static inline string::const_iterator skipLineOrEOS(
	string::const_iterator _nlPos,
	string::const_iterator _end
)
{
	return (_nlPos == _end) ? _end : ++_nlPos;
}

string::const_iterator InterfaceHandler::parseDocTagLine(
	string::const_iterator _pos,
	string::const_iterator _end,
	string& _tagString,
	DocTagType _tagType,
	bool _appending
)
{
	auto nlPos = find(_pos, _end, '\n');
	if (_appending && _pos < _end && *_pos != ' ')
		_tagString += " ";
	copy(_pos, nlPos, back_inserter(_tagString));
	m_lastTag = _tagType;
	return skipLineOrEOS(nlPos, _end);
}

string::const_iterator InterfaceHandler::parseDocTagParam(
	string::const_iterator _pos,
	string::const_iterator _end
)
{
	// find param name
	auto currPos = find(_pos, _end, ' ');
	if (currPos == _end)
		BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("End of param name not found" + string(_pos, _end)));


	auto paramName = string(_pos, currPos);

	currPos += 1;
	auto nlPos = find(currPos, _end, '\n');
	auto paramDesc = string(currPos, nlPos);
	m_params.push_back(make_pair(paramName, paramDesc));

	m_lastTag = DocTagType::Param;
	return skipLineOrEOS(nlPos, _end);
}

string::const_iterator InterfaceHandler::appendDocTagParam(
	string::const_iterator _pos,
	string::const_iterator _end
)
{
	// Should never be called with an empty vector
	solAssert(!m_params.empty(), "Internal: Tried to append to empty parameter");

	auto pair = m_params.back();
	if (_pos < _end && *_pos != ' ')
		pair.second += " ";
	auto nlPos = find(_pos, _end, '\n');
	copy(_pos, nlPos, back_inserter(pair.second));

	m_params.at(m_params.size() - 1) = pair;

	return skipLineOrEOS(nlPos, _end);
}

string::const_iterator InterfaceHandler::parseDocTag(
	string::const_iterator _pos,
	string::const_iterator _end,
	string const& _tag,
	CommentOwner _owner
)
{
	// LTODO: need to check for @(start of a tag) between here and the end of line
	// for all cases. Also somehow automate list of acceptable tags for each
	// language construct since current way does not scale well.
	if (m_lastTag == DocTagType::None || _tag != "")
	{
		if (_tag == "dev")
			return parseDocTagLine(_pos, _end, m_dev, DocTagType::Dev, false);
		else if (_tag == "notice")
			return parseDocTagLine(_pos, _end, m_notice, DocTagType::Notice, false);
		else if (_tag == "return")
			return parseDocTagLine(_pos, _end, m_return, DocTagType::Return, false);
		else if (_tag == "author")
		{
			if (_owner == CommentOwner::Contract)
				return parseDocTagLine(_pos, _end, m_contractAuthor, DocTagType::Author, false);
			else if (_owner == CommentOwner::Function)
				return parseDocTagLine(_pos, _end, m_author, DocTagType::Author, false);
			else
				// LTODO: for now this else makes no sense but later comments will go to more language constructs
				BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("@author tag is legal only for contracts"));
		}
		else if (_tag == "title")
		{
			if (_owner == CommentOwner::Contract)
				return parseDocTagLine(_pos, _end, m_title, DocTagType::Title, false);
			else
				// LTODO: Unknown tag, throw some form of warning and not just an exception
				BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("@title tag is legal only for contracts"));
		}
		else if (_tag == "param")
			return parseDocTagParam(_pos, _end);
		else
			// LTODO: Unknown tag, throw some form of warning and not just an exception
			BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("Unknown tag " + _tag + " encountered"));
	}
	else
		return appendDocTag(_pos, _end, _owner);
}

string::const_iterator InterfaceHandler::appendDocTag(
	string::const_iterator _pos,
	string::const_iterator _end,
	CommentOwner _owner
)
{
	switch (m_lastTag)
	{
	case DocTagType::Dev:
		return parseDocTagLine(_pos, _end, m_dev, DocTagType::Dev, true);
	case DocTagType::Notice:
		return parseDocTagLine(_pos, _end, m_notice, DocTagType::Notice, true);
	case DocTagType::Return:
		return parseDocTagLine(_pos, _end, m_return, DocTagType::Return, true);
	case DocTagType::Author:
		if (_owner == CommentOwner::Contract)
			return parseDocTagLine(_pos, _end, m_contractAuthor, DocTagType::Author, true);
		else if (_owner == CommentOwner::Function)
			return parseDocTagLine(_pos, _end, m_author, DocTagType::Author, true);
		else
			// LTODO: Unknown tag, throw some form of warning and not just an exception
			BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("@author tag in illegal comment"));
	case DocTagType::Title:
		if (_owner == CommentOwner::Contract)
			return parseDocTagLine(_pos, _end, m_title, DocTagType::Title, true);
		else
			// LTODO: Unknown tag, throw some form of warning and not just an exception
			BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("@title tag in illegal comment"));
	case DocTagType::Param:
		return appendDocTagParam(_pos, _end);
	default:
		BOOST_THROW_EXCEPTION(InternalCompilerError() << errinfo_comment("Internal: Illegal documentation tag type"));
		break;
	}
}

static inline string::const_iterator firstSpaceOrNl(
	string::const_iterator _pos,
	string::const_iterator _end
)
{
	auto spacePos = find(_pos, _end, ' ');
	auto nlPos = find(_pos, _end, '\n');
	return (spacePos < nlPos) ? spacePos : nlPos;
}

void InterfaceHandler::parseDocString(string const& _string, CommentOwner _owner)
{
	auto currPos = _string.begin();
	auto end = _string.end();

	while (currPos != end)
	{
		auto tagPos = find(currPos, end, '@');
		auto nlPos = find(currPos, end, '\n');

		if (tagPos != end && tagPos < nlPos)
		{
			// we found a tag
			auto tagNameEndPos = firstSpaceOrNl(tagPos, end);
			if (tagNameEndPos == end)
				BOOST_THROW_EXCEPTION(
					DocstringParsingError() <<
					errinfo_comment("End of tag " + string(tagPos, tagNameEndPos) + "not found"));

			currPos = parseDocTag(tagNameEndPos + 1, end, string(tagPos + 1, tagNameEndPos), _owner);
		}
		else if (m_lastTag != DocTagType::None) // continuation of the previous tag
			currPos = appendDocTag(currPos, end, _owner);
		else if (currPos != end)
		{
			// if it begins without a tag then consider it as @notice
			if (currPos == _string.begin())
			{
				currPos = parseDocTag(currPos, end, "notice", CommentOwner::Function);
				continue;
			}
			else if (nlPos == end) //end of text
				return;
			// else skip the line if a newline was found and we get here
			currPos = nlPos + 1;
		}
	}
}

} //solidity NS
} // dev NS