Merge pull request microsoft#165 from wravery/clientgen

Generate clients to go with cppgraphqlgen services

Author: wravery

CMakeLists.txt

@@ -84,6 +84,8 @@ else()
   set(GRAPHQL_UPDATE_SAMPLES OFF CACHE BOOL "Disable regenerating samples." FORCE)
 endif()
 
+option(GRAPHQL_BUILD_CLIENTGEN "Build the clientgen tool." ON)
+
 option(GRAPHQL_UPDATE_VERSION "Regenerate graphqlservice/internal/Version.h and all of the version info rc files for Windows." ON)
 
 add_subdirectory(cmake)

README.md

@@ -23,6 +23,15 @@ service, you can use the same GraphQL client code to access your native data sou
 service online. You might even be able to share some more of that code between a progressive web
 app and your native/hybrid app.
 
+If what you're after is a way to consume a GraphQL service from C++, as of
+[v3.6.0](https://github.com/microsoft/cppgraphqlgen/releases/tag/v3.6.0) this project also includes
+a `graphqlclient` library and a `clientgen` utility to generate types matching a GraphQL request
+document, its variables, and all of the serialization code you need to talk to a `graphqlservice`
+implementation. If you want to consume another service, you will need access to the schema definition
+(rather than the Introspection query results), and you will need be able to send requests along with
+any variables to the service and parse its responses into a `graphql::response::Value` (e.g. with the
+`graphqljson` library) in your code.
+
 # Getting Started
 
 ## Related projects
@@ -116,6 +125,41 @@ adds a runtime dependency on a Boost DLL. The `schemagen` tool won't run without
 the install of Boost, vcpkg also takes care of installing the dependencies next to `schemagen.exe` when building the
 Windows and UWP shared library targets (the platform triplets which don't end in `-static`).
 
+### clientgen
+
+The `clientgen` utility is based on `schemagen` and shares the same external dependencies. The command line arguments
+are almost the same, except it takes an extra file for the request document and there is no equivalent to `--no-stubs` or
+`--separate-files`:
+```
+Usage:  clientgen [options] <schema file> <request file> <output filename prefix> <output namespace>
+Command line options:
+  --version              Print the version number
+  -? [ --help ]          Print the command line options
+  -v [ --verbose ]       Verbose output including generated header names as
+                         well as sources
+  -s [ --schema ] arg    Schema definition file path
+  -r [ --request ] arg   Request document file path
+  -o [ --operation ] arg Operation name if the request document contains more
+                         than one
+  -p [ --prefix ] arg    Prefix to use for the generated C++ filenames
+  -n [ --namespace ] arg C++ sub-namespace for the generated types
+  --source-dir arg       Target path for the <prefix>Client.cpp source file
+  --header-dir arg       Target path for the <prefix>Client.h header file
+  --no-introspection     Do not expect support for Introspection
+```
+
+This utility should output one header and one source file for each request document. A request document may contain
+more than one operation, in which case you must specify the `--operation` (or `-o`) parameter to indicate which one
+should be used to generate the files. If you want to generate client code for more than one operation in the same
+document, you will need to run `clientgen` more than once and specify another operation name each time.
+
+The generated code depends on the `graphqlclient` library for serialization of built-in types. If you link the generated
+code, you'll also need to link `graphqlclient`, `graphqlpeg` for the pre-parsed, pre-validated request AST, and
+`graphqlresponse` for the `graphql::response::Value` implementation.
+
+Sample output for `clientgen` is in the [samples/client](samples/client) directory, and each sample is consumed by
+a unit test in [test/ClientTests.cpp](test/ClientTests.cpp).
+
 ### tests (`GRAPHQL_BUILD_TESTS=ON`)
 
 - Unit testing: [Google Test](https://github.com/google/googletest) for the unit testing framework. If you don't want to

cmake/ClientGen.rc.in

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#include <winver.h>
+
+#define CLIENTGEN_RC_VERSION     @CLIENTGEN_RC_VERSION@
+#define CLIENTGEN_RC_VERSION_STR "@CLIENTGEN_RC_VERSION_STR@"
+
+#ifndef DEBUG
+#define VER_DEBUG   0
+#else
+#define VER_DEBUG   VS_FF_DEBUG
+#endif
+
+VS_VERSION_INFO	VERSIONINFO
+FILEVERSION     CLIENTGEN_RC_VERSION
+PRODUCTVERSION  CLIENTGEN_RC_VERSION
+FILEFLAGSMASK   VS_FFI_FILEFLAGSMASK
+FILEFLAGS       VER_DEBUG
+FILEOS          VOS__WINDOWS32
+FILETYPE        VFT_APP
+FILESUBTYPE     VFT2_UNKNOWN
+BEGIN
+    BLOCK "StringFileInfo"
+    BEGIN
+        BLOCK "040904B0"
+        BEGIN
+            VALUE "CompanyName",        "Microsoft Corporation"
+            VALUE "FileDescription",    "Code generator for https://github.com/microsoft/cppgraphqlgen"
+            VALUE "FileVersion",        CLIENTGEN_RC_VERSION_STR
+            VALUE "InternalName",       "clientgen"
+            VALUE "LegalCopyright",     "Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License."
+            VALUE "OriginalFilename",   "clientgen.exe"
+            VALUE "ProductName",        "CppGraphQLGen"
+            VALUE "ProductVersion",     CLIENTGEN_RC_VERSION_STR
+        END
+    END
+
+    BLOCK "VarFileInfo"
+    BEGIN
+        VALUE "Translation", 0x409, 1200
+    END
+END

cmake/version.txt

@@ -1 +1 @@
-3.5.0
+3.6.0

doc/json.md

@@ -23,7 +23,7 @@ JSONRESPONSE_EXPORT std::string toJSON(Value&& response);
 
 JSONRESPONSE_EXPORT Value parseJSON(const std::string& json);
 
-} /* namespace graphql::response */
+} // namespace graphql::response
 ```
 
 You will also need to update the [CMakeLists.txt](../src/CMakeLists.txt) file

doc/parsing.md

@@ -17,8 +17,8 @@ you have another use for a GraphQL parser you could probably make a few small
 tweaks to include additional information in the rules or in the resulting AST.
 You could also use the grammar without the AST module if you want to handle
 the parsing callbacks another way. The grammar itself is defined in
-[GraphQLGrammar.h](../include/graphqlservice/GraphQLGrammar.h), and the AST
-selector callbacks are all defined in [GraphQLTree.cpp](../src/GraphQLTree.cpp).
+[Grammar.h](../include/graphqlservice/internal/Grammar.h), and the AST
+selector callbacks are all defined in [SyntaxTree.cpp](../src/SyntaxTree.cpp).
 The grammar handles both the schema definition syntax which is used in
 `schemagen`, and the query/mutation/subscription operation syntax used in
 `Request::resolve` and `Request::subscribe`.

include/ClientGenerator.h

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#pragma once
+
+#ifndef CLIENTGENERATOR_H
+#define CLIENTGENERATOR_H
+
+#include "RequestLoader.h"
+#include "SchemaLoader.h"
+
+namespace graphql::generator::client {
+
+struct GeneratorPaths
+{
+	const std::string headerPath;
+	const std::string sourcePath;
+};
+
+struct GeneratorOptions
+{
+	const std::optional<GeneratorPaths> paths;
+	const bool verbose = false;
+};
+
+class Generator
+{
+public:
+	// Initialize the generator with the introspection client or a custom GraphQL client.
+	explicit Generator(
+		SchemaOptions&& schemaOptions, RequestOptions&& requestOptions, GeneratorOptions&& options);
+
+	// Run the generator and return a list of filenames that were output.
+	std::vector<std::string> Build() const noexcept;
+
+private:
+	std::string getHeaderDir() const noexcept;
+	std::string getSourceDir() const noexcept;
+	std::string getHeaderPath() const noexcept;
+	std::string getSourcePath() const noexcept;
+	const std::string& getClientNamespace() const noexcept;
+	const std::string& getRequestNamespace() const noexcept;
+	const std::string& getFullNamespace() const noexcept;
+	std::string getResponseFieldCppType(
+		const ResponseField& responseField, std::string_view currentScope = {}) const noexcept;
+
+	bool outputHeader() const noexcept;
+	void outputRequestComment(std::ostream& headerFile) const noexcept;
+	void outputGetRequestDeclaration(std::ostream& headerFile) const noexcept;
+	bool outputResponseFieldType(std::ostream& headerFile, const ResponseField& responseField,
+		size_t indent = 0) const noexcept;
+
+	bool outputSource() const noexcept;
+	void outputGetRequestImplementation(std::ostream& sourceFile) const noexcept;
+	bool outputModifiedResponseImplementation(std::ostream& sourceFile,
+		const std::string& outerScope, const ResponseField& responseField) const noexcept;
+	static std::string getTypeModifierList(const TypeModifierStack& modifiers) noexcept;
+
+	const SchemaLoader _schemaLoader;
+	const RequestLoader _requestLoader;
+	const GeneratorOptions _options;
+	const std::string _headerDir;
+	const std::string _sourceDir;
+	const std::string _headerPath;
+	const std::string _sourcePath;
+};
+
+} // namespace graphql::generator::client
+
+#endif // CLIENTGENERATOR_H

include/GeneratorLoader.h

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#pragma once
+
+#ifndef GENERATORLOADER_H
+#define GENERATORLOADER_H
+
+#include "graphqlservice/GraphQLService.h"
+
+namespace graphql::generator {
+
+// Types that we understand and use to generate the skeleton of a service.
+enum class SchemaType
+{
+	Scalar,
+	Enum,
+	Input,
+	Union,
+	Interface,
+	Object,
+	Operation,
+};
+
+using SchemaTypeMap = std::map<std::string_view, SchemaType>;
+
+// Any type can also have a list and/or non-nullable wrapper, and those can be nested.
+// Since it's easier to express nullability than non-nullability in C++, we'll invert
+// the presence of NonNull modifiers.
+using TypeModifierStack = std::vector<service::TypeModifier>;
+
+// Recursively visit a Type node until we reach a NamedType and we've
+// taken stock of all of the modifier wrappers.
+class TypeVisitor
+{
+public:
+	std::pair<std::string_view, TypeModifierStack> getType();
+
+	void visit(const peg::ast_node& typeName);
+
+private:
+	void visitNamedType(const peg::ast_node& namedType);
+	void visitListType(const peg::ast_node& listType);
+	void visitNonNullType(const peg::ast_node& nonNullType);
+
+	std::string_view _type;
+	TypeModifierStack _modifiers;
+	bool _nonNull = false;
+};
+
+// Recursively visit a Value node representing the default value on an input field
+// and build a JSON representation of the hardcoded value.
+class DefaultValueVisitor
+{
+public:
+	response::Value getValue();
+
+	void visit(const peg::ast_node& value);
+
+private:
+	void visitIntValue(const peg::ast_node& intValue);
+	void visitFloatValue(const peg::ast_node& floatValue);
+	void visitStringValue(const peg::ast_node& stringValue);
+	void visitBooleanValue(const peg::ast_node& booleanValue);
+	void visitNullValue(const peg::ast_node& nullValue);
+	void visitEnumValue(const peg::ast_node& enumValue);
+	void visitListValue(const peg::ast_node& listValue);
+	void visitObjectValue(const peg::ast_node& objectValue);
+
+	response::Value _value;
+};
+
+} // namespace graphql::generator
+
+#endif // GENERATORLOADER_H

include/GeneratorUtil.h

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#pragma once
+
+#ifndef GENERATORUTIL_H
+#define GENERATORUTIL_H
+
+#include <iostream>
+#include <string>
+#include <string_view>
+
+namespace graphql::generator {
+
+// RAII object to help with emitting matching include guard begin and end statements
+class IncludeGuardScope
+{
+public:
+	explicit IncludeGuardScope(std::ostream& outputFile, std::string_view headerFileName) noexcept;
+	~IncludeGuardScope() noexcept;
+
+private:
+	std::ostream& _outputFile;
+	std::string _includeGuardName;
+};
+
+// RAII object to help with emitting matching namespace begin and end statements
+class NamespaceScope
+{
+public:
+	explicit NamespaceScope(
+		std::ostream& outputFile, std::string_view cppNamespace, bool deferred = false) noexcept;
+	NamespaceScope(NamespaceScope&& other) noexcept;
+	~NamespaceScope() noexcept;
+
+	bool enter() noexcept;
+	bool exit() noexcept;
+
+private:
+	bool _inside = false;
+	std::ostream& _outputFile;
+	std::string_view _cppNamespace;
+};
+
+// Keep track of whether we want to add a blank separator line once some additional content is about
+// to be output.
+class PendingBlankLine
+{
+public:
+	explicit PendingBlankLine(std::ostream& outputFile) noexcept;
+
+	void add() noexcept;
+	bool reset() noexcept;
+
+private:
+	bool _pending = true;
+	std::ostream& _outputFile;
+};
+
+} // namespace graphql::generator
+
+#endif // GENERATORUTIL_H