mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
341 lines
10 KiB
C++
341 lines
10 KiB
C++
|
|
#include <libsolidity/InterfaceHandler.h>
|
|
#include <libsolidity/AST.h>
|
|
#include <libsolidity/CompilerStack.h>
|
|
|
|
namespace dev
|
|
{
|
|
namespace solidity
|
|
{
|
|
|
|
/* -- public -- */
|
|
|
|
InterfaceHandler::InterfaceHandler()
|
|
{
|
|
m_lastTag = DocTagType::NONE;
|
|
}
|
|
|
|
std::unique_ptr<std::string> InterfaceHandler::getDocumentation(ContractDefinition const& _contractDef,
|
|
DocumentationType _type)
|
|
{
|
|
switch(_type)
|
|
{
|
|
case DocumentationType::NATSPEC_USER:
|
|
return getUserDocumentation(_contractDef);
|
|
case DocumentationType::NATSPEC_DEV:
|
|
return getDevDocumentation(_contractDef);
|
|
case DocumentationType::ABI_INTERFACE:
|
|
return getABIInterface(_contractDef);
|
|
}
|
|
|
|
BOOST_THROW_EXCEPTION(InternalCompilerError() << errinfo_comment("Unknown documentation type"));
|
|
return nullptr;
|
|
}
|
|
|
|
std::unique_ptr<std::string> InterfaceHandler::getABIInterface(ContractDefinition const& _contractDef)
|
|
{
|
|
Json::Value methods(Json::arrayValue);
|
|
|
|
for (FunctionDefinition const* f: _contractDef.getInterfaceFunctions())
|
|
{
|
|
Json::Value method;
|
|
Json::Value inputs(Json::arrayValue);
|
|
Json::Value outputs(Json::arrayValue);
|
|
|
|
auto populateParameters = [](std::vector<ASTPointer<VariableDeclaration>> const& _vars)
|
|
{
|
|
Json::Value params(Json::arrayValue);
|
|
for (ASTPointer<VariableDeclaration> const& var: _vars)
|
|
{
|
|
Json::Value input;
|
|
input["name"] = var->getName();
|
|
input["type"] = var->getType()->toString();
|
|
params.append(input);
|
|
}
|
|
return params;
|
|
};
|
|
|
|
method["name"] = f->getName();
|
|
method["inputs"] = populateParameters(f->getParameters());
|
|
method["outputs"] = populateParameters(f->getReturnParameters());
|
|
methods.append(method);
|
|
}
|
|
return std::unique_ptr<std::string>(new std::string(m_writer.write(methods)));
|
|
}
|
|
|
|
std::unique_ptr<std::string> InterfaceHandler::getUserDocumentation(ContractDefinition const& _contractDef)
|
|
{
|
|
Json::Value doc;
|
|
Json::Value methods(Json::objectValue);
|
|
|
|
for (FunctionDefinition const* f: _contractDef.getInterfaceFunctions())
|
|
{
|
|
Json::Value user;
|
|
auto strPtr = f->getDocumentation();
|
|
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[f->getName()] = user;
|
|
}
|
|
}
|
|
}
|
|
doc["methods"] = methods;
|
|
|
|
return std::unique_ptr<std::string>(new std::string(m_writer.write(doc)));
|
|
}
|
|
|
|
std::unique_ptr<std::string> InterfaceHandler::getDevDocumentation(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.getDocumentation();
|
|
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 (FunctionDefinition const* f: _contractDef.getInterfaceFunctions())
|
|
{
|
|
Json::Value method;
|
|
auto strPtr = f->getDocumentation();
|
|
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);
|
|
for (auto const& pair: m_params)
|
|
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[f->getName()] = method;
|
|
}
|
|
}
|
|
doc["methods"] = methods;
|
|
|
|
return std::unique_ptr<std::string>(new std::string(m_writer.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 std::string::const_iterator skipLineOrEOS(std::string::const_iterator _nlPos,
|
|
std::string::const_iterator _end)
|
|
{
|
|
return (_nlPos == _end) ? _end : ++_nlPos;
|
|
}
|
|
|
|
std::string::const_iterator InterfaceHandler::parseDocTagLine(std::string::const_iterator _pos,
|
|
std::string::const_iterator _end,
|
|
std::string& _tagString,
|
|
DocTagType _tagType)
|
|
{
|
|
auto nlPos = std::find(_pos, _end, '\n');
|
|
std::copy(_pos, nlPos, back_inserter(_tagString));
|
|
m_lastTag = _tagType;
|
|
return skipLineOrEOS(nlPos, _end);
|
|
}
|
|
|
|
std::string::const_iterator InterfaceHandler::parseDocTagParam(std::string::const_iterator _pos,
|
|
std::string::const_iterator _end)
|
|
{
|
|
// find param name
|
|
auto currPos = std::find(_pos, _end, ' ');
|
|
if (currPos == _end)
|
|
BOOST_THROW_EXCEPTION(DocstringParsingError() << errinfo_comment("End of param name not found" + std::string(_pos, _end)));
|
|
|
|
|
|
auto paramName = std::string(_pos, currPos);
|
|
|
|
currPos += 1;
|
|
auto nlPos = std::find(currPos, _end, '\n');
|
|
auto paramDesc = std::string(currPos, nlPos);
|
|
m_params.push_back(std::make_pair(paramName, paramDesc));
|
|
|
|
m_lastTag = DocTagType::PARAM;
|
|
return skipLineOrEOS(nlPos, _end);
|
|
}
|
|
|
|
std::string::const_iterator InterfaceHandler::appendDocTagParam(std::string::const_iterator _pos,
|
|
std::string::const_iterator _end)
|
|
{
|
|
// Should never be called with an empty vector
|
|
if (asserts(!m_params.empty()))
|
|
BOOST_THROW_EXCEPTION(InternalCompilerError() << errinfo_comment("Internal: Tried to append to empty parameter"));
|
|
|
|
auto pair = m_params.back();
|
|
pair.second += " ";
|
|
auto nlPos = std::find(_pos, _end, '\n');
|
|
std::copy(_pos, nlPos, back_inserter(pair.second));
|
|
|
|
m_params.at(m_params.size() - 1) = pair;
|
|
|
|
return skipLineOrEOS(nlPos, _end);
|
|
}
|
|
|
|
std::string::const_iterator InterfaceHandler::parseDocTag(std::string::const_iterator _pos,
|
|
std::string::const_iterator _end,
|
|
std::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);
|
|
else if (_tag == "notice")
|
|
return parseDocTagLine(_pos, _end, m_notice, DocTagType::NOTICE);
|
|
else if (_tag == "return")
|
|
return parseDocTagLine(_pos, _end, m_return, DocTagType::RETURN);
|
|
else if (_tag == "author")
|
|
{
|
|
if (_owner == CommentOwner::CONTRACT)
|
|
return parseDocTagLine(_pos, _end, m_contractAuthor, DocTagType::AUTHOR);
|
|
else if (_owner == CommentOwner::FUNCTION)
|
|
return parseDocTagLine(_pos, _end, m_author, DocTagType::AUTHOR);
|
|
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);
|
|
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);
|
|
}
|
|
|
|
std::string::const_iterator InterfaceHandler::appendDocTag(std::string::const_iterator _pos,
|
|
std::string::const_iterator _end,
|
|
CommentOwner _owner)
|
|
{
|
|
switch (m_lastTag)
|
|
{
|
|
case DocTagType::DEV:
|
|
m_dev += " ";
|
|
return parseDocTagLine(_pos, _end, m_dev, DocTagType::DEV);
|
|
case DocTagType::NOTICE:
|
|
m_notice += " ";
|
|
return parseDocTagLine(_pos, _end, m_notice, DocTagType::NOTICE);
|
|
case DocTagType::RETURN:
|
|
m_return += " ";
|
|
return parseDocTagLine(_pos, _end, m_return, DocTagType::RETURN);
|
|
case DocTagType::AUTHOR:
|
|
if (_owner == CommentOwner::CONTRACT)
|
|
{
|
|
m_contractAuthor += " ";
|
|
return parseDocTagLine(_pos, _end, m_contractAuthor, DocTagType::AUTHOR);
|
|
}
|
|
else if (_owner == CommentOwner::FUNCTION)
|
|
{
|
|
m_author += " ";
|
|
return parseDocTagLine(_pos, _end, m_author, DocTagType::AUTHOR);
|
|
}
|
|
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)
|
|
{
|
|
m_title += " ";
|
|
return parseDocTagLine(_pos, _end, m_title, DocTagType::TITLE);
|
|
}
|
|
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 std::string::const_iterator getFirstSpaceOrNl(std::string::const_iterator _pos,
|
|
std::string::const_iterator _end)
|
|
{
|
|
auto spacePos = std::find(_pos, _end, ' ');
|
|
auto nlPos = std::find(_pos, _end, '\n');
|
|
return (spacePos < nlPos) ? spacePos : nlPos;
|
|
}
|
|
|
|
void InterfaceHandler::parseDocString(std::string const& _string, CommentOwner _owner)
|
|
{
|
|
auto currPos = _string.begin();
|
|
auto end = _string.end();
|
|
|
|
while (currPos != end)
|
|
{
|
|
auto tagPos = std::find(currPos, end, '@');
|
|
auto nlPos = std::find(currPos, end, '\n');
|
|
|
|
if (tagPos != end && tagPos < nlPos)
|
|
{
|
|
// we found a tag
|
|
auto tagNameEndPos = getFirstSpaceOrNl(tagPos, end);
|
|
if (tagNameEndPos == end)
|
|
BOOST_THROW_EXCEPTION(DocstringParsingError() <<
|
|
errinfo_comment("End of tag " + std::string(tagPos, tagNameEndPos) + "not found"));
|
|
|
|
currPos = parseDocTag(tagNameEndPos + 1, end, std::string(tagPos + 1, tagNameEndPos), _owner);
|
|
}
|
|
else if (m_lastTag != DocTagType::NONE) // continuation of the previous tag
|
|
currPos = appendDocTag(currPos + 1, end, _owner);
|
|
else if (currPos != end) // skip the line if a newline was found
|
|
currPos = nlPos + 1;
|
|
}
|
|
}
|
|
|
|
} //solidity NS
|
|
} // dev NS
|