Merge remote-tracking branch 'ethereum/develop' into sol_import

Conflicts:
	libsolidity/CompilerStack.cpp
	libsolidity/CompilerStack.h
	solc/main.cpp

7 files changed, 445 insertions, 42 deletions

diff --git a/AST.h b/AST.h
index 2b532d76..d2fb15a4 100644
--- a/AST.h
+++ b/AST.h
@@ -238,7 +238,7 @@ public:
 	Block& getBody() { return *m_body; }
 	/// @return A shared pointer of an ASTString.
 	/// Can contain a nullptr in which case indicates absence of documentation
-	ASTPointer<ASTString> const& getDocumentation() { return m_documentation; }
+	ASTPointer<ASTString> const& getDocumentation() const { return m_documentation; }
 
 	void addLocalVariable(VariableDeclaration const& _localVariable) { m_localVariables.push_back(&_localVariable); }
 	std::vector<VariableDeclaration const*> const& getLocalVariables() const { return m_localVariables; }
diff --git a/CMakeLists.txt b/CMakeLists.txt
index ea2ef4b7..b5147ced 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -16,6 +16,10 @@ endif()
 include_directories(..)
 
 target_link_libraries(${EXECUTABLE} evmcore devcore)
+# TODO: Temporary until PR 532 https://github.com/ethereum/cpp-ethereum/pull/532
+# gets accepted. Then we can simply add jsoncpp as a dependency and not the
+# whole of JSONRPC as we are doing right here
+target_link_libraries(${EXECUTABLE} ${JSONRPC_LS})
 
 install( TARGETS ${EXECUTABLE} ARCHIVE DESTINATION lib LIBRARY DESTINATION lib )
 install( FILES ${HEADERS} DESTINATION include/${EXECUTABLE} )
diff --git a/CompilerStack.cpp b/CompilerStack.cpp
index 198ded09..62172384 100644
--- a/CompilerStack.cpp
+++ b/CompilerStack.cpp
@@ -27,6 +27,7 @@
 #include <libsolidity/NameAndTypeResolver.h>
 #include <libsolidity/Compiler.h>
 #include <libsolidity/CompilerStack.h>
+#include <libsolidity/InterfaceHandler.h>
 
 using namespace std;
 
@@ -127,45 +128,34 @@ void CompilerStack::streamAssembly(ostream& _outStream, string const& _contractN
 
 string const& CompilerStack::getInterface(std::string const& _contractName)
 {
+	return getJsonDocumentation(_contractName, ABI_INTERFACE);
+}
+
+std::string const& CompilerStack::getJsonDocumentation(std::string const& _contractName, enum DocumentationType _type)
+{
+	if (!m_parseSuccessful)
+		BOOST_THROW_EXCEPTION(CompilerError() << errinfo_comment("Parsing was not successful."));
+
 	Contract& contract = getContract(_contractName);
-	if (contract.interface.empty())
+
+	std::unique_ptr<string>* doc;
+	switch (_type)
 	{
-		stringstream interface;
-		interface << '[';
-		vector<FunctionDefinition const*> exportedFunctions = contract.contract->getInterfaceFunctions();
-		unsigned functionsCount = exportedFunctions.size();
-		for (FunctionDefinition const* f: exportedFunctions)
-		{
-			auto streamVariables = [&](vector<ASTPointer<VariableDeclaration>> const& _vars)
-			{
-				unsigned varCount = _vars.size();
-				for (ASTPointer<VariableDeclaration> const& var: _vars)
-				{
-					interface << "{"
-							  << "\"name\":" << escaped(var->getName(), false) << ","
-							  << "\"type\":" << escaped(var->getType()->toString(), false)
-							  << "}";
-					if (--varCount > 0)
-						interface << ",";
-				}
-			};
-
-			interface << '{'
-					  << "\"name\":" << escaped(f->getName(), false) << ","
-					  << "\"inputs\":[";
-			streamVariables(f->getParameters());
-			interface << "],"
-					  << "\"outputs\":[";
-			streamVariables(f->getReturnParameters());
-			interface << "]"
-					  << "}";
-			if (--functionsCount > 0)
-				interface << ",";
-		}
-		interface << ']';
-		contract.interface = interface.str();
+	case NATSPEC_USER:
+		doc = &contract.userDocumentation;
+		break;
+	case NATSPEC_DEV:
+		doc = &contract.devDocumentation;
+		break;
+	case ABI_INTERFACE:
+		doc = &contract.interface;
+		break;
+	default:
+		BOOST_THROW_EXCEPTION(InternalCompilerError() << errinfo_comment("Illegal documentation type."));
 	}
-	return contract.interface;
+	if (!*doc)
+		*doc = contract.interfaceHandler->getDocumentation(*contract.contract, _type);
+	return *(*doc);
 }
 
 Scanner const& CompilerStack::getScanner(string const& _sourceName)
@@ -193,7 +183,6 @@ void CompilerStack::reset(bool _keepSources)
 	else
 		m_sources.clear();
 	m_globalContext.reset();
-	m_compiler.reset();
 	m_sourceOrder.clear();
 	m_contracts.clear();
 }
@@ -247,5 +236,8 @@ CompilerStack::Source& CompilerStack::getSource(string const& _sourceName)
 		BOOST_THROW_EXCEPTION(CompilerError() << errinfo_comment("Given source file not found."));
 	return it->second;
 }
+
+CompilerStack::Contract::Contract(): interfaceHandler(make_shared<InterfaceHandler>()) {}
+
 }
 }
diff --git a/CompilerStack.h b/CompilerStack.h
index a5b8ec41..34178841 100644
--- a/CompilerStack.h
+++ b/CompilerStack.h
@@ -33,10 +33,18 @@ namespace solidity {
 
 // forward declarations
 class Scanner;
+class ContractDefinition;
 class SourceUnit;
 class Compiler;
 class GlobalContext;
-class ContractDefinition;
+class InterfaceHandler;
+
+enum DocumentationType: unsigned short
+{
+	NATSPEC_USER = 1,
+	NATSPEC_DEV,
+	ABI_INTERFACE
+};
 
 /**
  * Easy to use and self-contained Solidity compiler with as few header dependencies as possible.
@@ -47,6 +55,7 @@ class CompilerStack: boost::noncopyable
 {
 public:
 	CompilerStack(): m_parseSuccessful(false) {}
+
 	/// Adds a source object (e.g. file) to the parser. After this, parse has to be called again.
 	void addSource(std::string const& _name, std::string const& _content);
 	void setSource(std::string const& _sourceCode);
@@ -71,6 +80,11 @@ public:
 	/// Returns a string representing the contract interface in JSON.
 	/// Prerequisite: Successful call to parse or compile.
 	std::string const& getInterface(std::string const& _contractName = "");
+	/// Returns a string representing the contract's documentation in JSON.
+	/// Prerequisite: Successful call to parse or compile.
+	/// @param type The type of the documentation to get.
+	/// Can be one of 3 types defined at @c DocumentationType
+	std::string const& getJsonDocumentation(std::string const& _contractName, enum DocumentationType _type);
 
 	/// Returns the previously used scanner, useful for counting lines during error reporting.
 	Scanner const& getScanner(std::string const& _sourceName = "");
@@ -94,10 +108,15 @@ private:
 
 	struct Contract
 	{
-		ContractDefinition const* contract;
-		std::string interface;
+		ContractDefinition* contract;
 		std::shared_ptr<Compiler> compiler;
 		bytes bytecode;
+		std::shared_ptr<InterfaceHandler> interfaceHandler;
+		std::unique_ptr<std::string> interface;
+		std::unique_ptr<std::string> userDocumentation;
+		std::unique_ptr<std::string> devDocumentation;
+
+		Contract();
 	};
 
 	void reset(bool _keepSources = false);
@@ -109,7 +128,6 @@ private:
 	bool m_parseSuccessful;
 	std::map<std::string, Source> m_sources;
 	std::shared_ptr<GlobalContext> m_globalContext;
-	std::shared_ptr<Compiler> m_compiler;
 	std::vector<Source const*> m_sourceOrder;
 	std::map<std::string, Contract> m_contracts;
 };
diff --git a/Exceptions.h b/Exceptions.h
index ffd8a72d..14f91977 100644
--- a/Exceptions.h
+++ b/Exceptions.h
@@ -36,6 +36,7 @@ struct TypeError: virtual Exception {};
 struct DeclarationError: virtual Exception {};
 struct CompilerError: virtual Exception {};
 struct InternalCompilerError: virtual Exception {};
+struct DocstringParsingError: virtual Exception {};
 
 typedef boost::error_info<struct tag_sourceLocation, Location> errinfo_sourceLocation;
 
diff --git a/InterfaceHandler.cpp b/InterfaceHandler.cpp
new file mode 100644
index 00000000..95e8c58a
--- /dev/null
+++ b/InterfaceHandler.cpp
@@ -0,0 +1,278 @@
+
+#include <libsolidity/InterfaceHandler.h>
+#include <libsolidity/AST.h>
+#include <libsolidity/CompilerStack.h>
+
+namespace dev
+{
+namespace solidity
+{
+
+/* -- public -- */
+
+InterfaceHandler::InterfaceHandler()
+{
+	m_lastTag = DOCTAG_NONE;
+}
+
+std::unique_ptr<std::string> InterfaceHandler::getDocumentation(ContractDefinition& _contractDef,
+																enum DocumentationType _type)
+{
+	switch(_type)
+	{
+	case NATSPEC_USER:
+		return getUserDocumentation(_contractDef);
+	case NATSPEC_DEV:
+		return getDevDocumentation(_contractDef);
+	case ABI_INTERFACE:
+		return getABIInterface(_contractDef);
+	}
+
+	BOOST_THROW_EXCEPTION(InternalCompilerError() << errinfo_comment("Unknown documentation type"));
+	return nullptr;
+}
+
+std::unique_ptr<std::string> InterfaceHandler::getABIInterface(ContractDefinition& _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& _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);
+			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& _contractDef)
+{
+	// LTODO: Somewhere in this function warnings for mismatch of param names
+	// should be thrown
+	Json::Value doc;
+	Json::Value methods(Json::objectValue);
+
+	for (FunctionDefinition const* f: _contractDef.getInterfaceFunctions())
+	{
+		Json::Value method;
+		auto strPtr = f->getDocumentation();
+		if (strPtr)
+		{
+			resetDev();
+			parseDocString(*strPtr);
+
+			if (!m_dev.empty())
+				method["details"] = Json::Value(m_dev);
+			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_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,
+															  enum 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 = DOCTAG_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)
+{
+	// LTODO: need to check for @(start of a tag) between here and the end of line
+	//      for all cases
+	if (m_lastTag == DOCTAG_NONE || _tag != "")
+	{
+		if (_tag == "dev")
+			return parseDocTagLine(_pos, _end, m_dev, DOCTAG_DEV);
+		else if (_tag == "notice")
+			return parseDocTagLine(_pos, _end, m_notice, DOCTAG_NOTICE);
+		else if (_tag == "return")
+			return parseDocTagLine(_pos, _end, m_return, DOCTAG_RETURN);
+		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);
+}
+
+std::string::const_iterator InterfaceHandler::appendDocTag(std::string::const_iterator _pos,
+														   std::string::const_iterator _end)
+{
+	switch (m_lastTag)
+	{
+		case DOCTAG_DEV:
+			m_dev += " ";
+			return parseDocTagLine(_pos, _end, m_dev, DOCTAG_DEV);
+		case DOCTAG_NOTICE:
+			m_notice += " ";
+			return parseDocTagLine(_pos, _end, m_notice, DOCTAG_NOTICE);
+		case DOCTAG_RETURN:
+			m_return += " ";
+			return parseDocTagLine(_pos, _end, m_return, DOCTAG_RETURN);
+		case DOCTAG_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)
+{
+	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));
+		}
+		else if (m_lastTag != DOCTAG_NONE) // continuation of the previous tag
+			currPos = appendDocTag(currPos + 1, end);
+		else if (currPos != end) // skip the line if a newline was found
+			currPos = nlPos + 1;
+	}
+}
+
+} //solidity NS
+} // dev NS
diff --git a/InterfaceHandler.h b/InterfaceHandler.h
new file mode 100644
index 00000000..0eae3aaf
--- /dev/null
+++ b/InterfaceHandler.h
@@ -0,0 +1,110 @@
+/*
+	This file is part of cpp-ethereum.
+
+	cpp-ethereum is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 3 of the License, or
+	(at your option) any later version.
+
+	cpp-ethereum is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with cpp-ethereum.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @author Lefteris <lefteris@ethdev.com>
+ * @date 2014
+ * Takes the parsed AST and produces the Natspec
+ * documentation and the ABI interface
+ * https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format
+ *
+ * Can generally deal with JSON files
+ */
+
+#pragma once
+
+#include <string>
+#include <memory>
+#include <jsonrpc/json/json.h>
+
+namespace dev
+{
+namespace solidity
+{
+
+// Forward declarations
+class ContractDefinition;
+enum DocumentationType: unsigned short;
+
+enum DocTagType
+{
+	DOCTAG_NONE = 0,
+	DOCTAG_DEV,
+	DOCTAG_NOTICE,
+	DOCTAG_PARAM,
+	DOCTAG_RETURN
+};
+
+class InterfaceHandler
+{
+public:
+	InterfaceHandler();
+
+	/// Get the given type of documentation
+	/// @param _contractDef The contract definition
+	/// @param _type        The type of the documentation. Can be one of the
+	///                     types provided by @c DocumentationType
+	/// @return             A unique pointer contained string with the json
+	///                     representation of provided type
+	std::unique_ptr<std::string> getDocumentation(ContractDefinition& _contractDef,
+												  enum DocumentationType _type);
+	/// Get the ABI Interface of the contract
+	/// @param _contractDef The contract definition
+	/// @return             A unique pointer contained string with the json
+	///                     representation of the contract's ABI Interface
+	std::unique_ptr<std::string> getABIInterface(ContractDefinition& _contractDef);
+	/// Get the User documentation of the contract
+	/// @param _contractDef The contract definition
+	/// @return             A unique pointer contained string with the json
+	///                     representation of the contract's user documentation
+	std::unique_ptr<std::string> getUserDocumentation(ContractDefinition& _contractDef);
+	/// Get the Developer's documentation of the contract
+	/// @param _contractDef The contract definition
+	/// @return             A unique pointer contained string with the json
+	///                     representation of the contract's developer documentation
+	std::unique_ptr<std::string> getDevDocumentation(ContractDefinition& _contractDef);
+
+private:
+	void resetUser();
+	void resetDev();
+
+	std::string::const_iterator parseDocTagLine(std::string::const_iterator _pos,
+												std::string::const_iterator _end,
+												std::string& _tagString,
+												enum DocTagType _tagType);
+	std::string::const_iterator parseDocTagParam(std::string::const_iterator _pos,
+												 std::string::const_iterator _end);
+	std::string::const_iterator appendDocTagParam(std::string::const_iterator _pos,
+												  std::string::const_iterator _end);
+	void parseDocString(std::string const& _string);
+	std::string::const_iterator appendDocTag(std::string::const_iterator _pos,
+											 std::string::const_iterator _end);
+	std::string::const_iterator parseDocTag(std::string::const_iterator _pos,
+											std::string::const_iterator _end,
+											std::string const& _tag);
+
+	Json::StyledWriter m_writer;
+
+	// internal state
+	enum DocTagType m_lastTag;
+	std::string m_notice;
+	std::string m_dev;
+	std::string m_return;
+	std::vector<std::pair<std::string, std::string>> m_params;
+};
+
+} //solidity NS
+} // dev NS