feat(generator): generate simple samples for *Client

generator/CMakeLists.txt

@@ -57,6 +57,8 @@ add_library(
     internal/retry_traits_generator.h
     internal/round_robin_decorator_generator.cc
     internal/round_robin_decorator_generator.h
+    internal/sample_generator.cc
+    internal/sample_generator.h
     internal/scaffold_generator.cc
     internal/scaffold_generator.h
     internal/service_code_generator.cc

generator/generator_test.cc

@@ -141,7 +141,7 @@ TEST_F(GeneratorTest, BadCommandLineArgs) {
 }
 
 TEST_F(GeneratorTest, GenerateServicesSuccess) {
-  int constexpr kNumMockOutputStreams = 22;
+  int constexpr kNumMockOutputStreams = 23;
   std::vector<std::unique_ptr<generator_testing::MockZeroCopyOutputStream>>
       mock_outputs(kNumMockOutputStreams);
   for (auto& output : mock_outputs) {

generator/google_cloud_cpp_generator.bzl

@@ -35,6 +35,7 @@ google_cloud_cpp_generator_hdrs = [
     "internal/printer.h",
     "internal/retry_traits_generator.h",
     "internal/round_robin_decorator_generator.h",
+    "internal/sample_generator.h",
     "internal/scaffold_generator.h",
     "internal/service_code_generator.h",
     "internal/stub_factory_generator.h",
@@ -58,6 +59,7 @@ google_cloud_cpp_generator_srcs = [
     "internal/predicate_utils.cc",
     "internal/retry_traits_generator.cc",
     "internal/round_robin_decorator_generator.cc",
+    "internal/sample_generator.cc",
     "internal/scaffold_generator.cc",
     "internal/service_code_generator.cc",
     "internal/stub_factory_generator.cc",

generator/integration_tests/golden/samples/golden_kitchen_sink_client_samples.cc

@@ -0,0 +1,59 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Generated by the Codegen C++ plugin.
+// If you make any local changes, they will be lost.
+// source: generator/integration_tests/test.proto
+
+#include "generator/integration_tests/golden/golden_kitchen_sink_client.h"
+#include "google/cloud/common_options.h"
+#include "google/cloud/testing_util/example_driver.h"
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace {
+
+void SetClientEndpoint(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-endpoint"};
+  }
+  //! [set-client-endpoint]
+  // This configuration is common with Private Google Access:
+  //     https://cloud.google.com/vpc/docs/private-google-access
+  auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
+      "private.googleapis.com");
+  auto client = google::cloud::golden::GoldenKitchenSinkClient(
+      google::cloud::golden::MakeGoldenKitchenSinkConnection(options));
+  // Use the `client` object as usual
+  //! [set-client-endpoint]
+}
+
+// main-dox-marker: GoldenKitchenSinkClient
+void AutoRun(std::vector<std::string> const& argv) {
+  if (!argv.empty()) throw google::cloud::testing_util::Usage{"auto"};
+
+  std::cout << "\nRunning SetClientEndpoint() example" << std::endl;
+  SetClientEndpoint({});
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
+  google::cloud::testing_util::Example example({
+      {"set-client-endpoint", SetClientEndpoint},
+      {"auto", AutoRun},
+  });
+  return example.Run(argc, argv);
+}

generator/integration_tests/golden/samples/golden_kitchen_sink_samples.cc

@@ -0,0 +1,59 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Generated by the Codegen C++ plugin.
+// If you make any local changes, they will be lost.
+// source: generator/integration_tests/test.proto
+
+#include "generator/integration_tests/golden/golden_kitchen_sink_client.h"
+#include "google/cloud/common_options.h"
+#include "google/cloud/testing_util/example_driver.h"
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace {
+
+void SetClientEndpoint(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-endpoint"};
+  }
+  //! [set-client-endpoint]
+  // For illustration purposes, set the endpoint to the default value. In real
+  // applications you would use a different value, such as a
+  // `private.googleapis.com` for VPC-SC, or maybe a regional endpoint.
+  auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
+      "goldenkitchensink.googleapis.com");
+  auto client = google::cloud::golden::GoldenKitchenSinkClient(
+    google::cloud::golden::MakeGoldenKitchenSinkConnection(options));
+  // Use the `client` object as usual
+  //! [set-client-endpoint]
+}
+
+void AutoRun(std::vector<std::string> const& argv) {
+  if (!argv.empty()) throw google::cloud::testing_util::Usage{"auto"};
+
+  std::cout << "\nRunning SetClientEndpoint() example" << std::endl;
+  SetClientEndpoint({});
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
+  google::cloud::testing_util::Example example({
+      {"set-client-endpoint", SetClientEndpoint},
+      {"auto", AutoRun},
+  });
+  return example.Run(argc, argv);
+}

generator/integration_tests/golden/samples/golden_thing_admin_client_samples.cc

@@ -0,0 +1,59 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Generated by the Codegen C++ plugin.
+// If you make any local changes, they will be lost.
+// source: generator/integration_tests/test.proto
+
+#include "generator/integration_tests/golden/golden_thing_admin_client.h"
+#include "google/cloud/common_options.h"
+#include "google/cloud/testing_util/example_driver.h"
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace {
+
+void SetClientEndpoint(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-endpoint"};
+  }
+  //! [set-client-endpoint]
+  // This configuration is common with Private Google Access:
+  //     https://cloud.google.com/vpc/docs/private-google-access
+  auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
+      "private.googleapis.com");
+  auto client = google::cloud::golden::GoldenThingAdminClient(
+      google::cloud::golden::MakeGoldenThingAdminConnection(options));
+  // Use the `client` object as usual
+  //! [set-client-endpoint]
+}
+
+// main-dox-marker: GoldenThingAdminClient
+void AutoRun(std::vector<std::string> const& argv) {
+  if (!argv.empty()) throw google::cloud::testing_util::Usage{"auto"};
+
+  std::cout << "\nRunning SetClientEndpoint() example" << std::endl;
+  SetClientEndpoint({});
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
+  google::cloud::testing_util::Example example({
+      {"set-client-endpoint", SetClientEndpoint},
+      {"auto", AutoRun},
+  });
+  return example.Run(argc, argv);
+}

generator/integration_tests/golden/samples/golden_thing_admin_samples.cc

@@ -0,0 +1,59 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Generated by the Codegen C++ plugin.
+// If you make any local changes, they will be lost.
+// source: generator/integration_tests/test.proto
+
+#include "generator/integration_tests/golden/golden_thing_admin_client.h"
+#include "google/cloud/common_options.h"
+#include "google/cloud/testing_util/example_driver.h"
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace {
+
+void SetClientEndpoint(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-endpoint"};
+  }
+  //! [set-client-endpoint]
+  // For illustration purposes, set the endpoint to the default value. In real
+  // applications you would use a different value, such as a
+  // `private.googleapis.com` for VPC-SC, or maybe a regional endpoint.
+  auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
+      "test.googleapis.com");
+  auto client = google::cloud::golden::GoldenThingAdminClient(
+    google::cloud::golden::MakeGoldenThingAdminConnection(options));
+  // Use the `client` object as usual
+  //! [set-client-endpoint]
+}
+
+void AutoRun(std::vector<std::string> const& argv) {
+  if (!argv.empty()) throw google::cloud::testing_util::Usage{"auto"};
+
+  std::cout << "\nRunning SetClientEndpoint() example" << std::endl;
+  SetClientEndpoint({});
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
+  google::cloud::testing_util::Example example({
+      {"set-client-endpoint", SetClientEndpoint},
+      {"auto", AutoRun},
+  });
+  return example.Run(argc, argv);
+}

generator/internal/descriptor_utils.cc

@@ -34,6 +34,7 @@
 #include "generator/internal/predicate_utils.h"
 #include "generator/internal/retry_traits_generator.h"
 #include "generator/internal/round_robin_decorator_generator.h"
+#include "generator/internal/sample_generator.h"
 #include "generator/internal/stub_factory_generator.h"
 #include "generator/internal/stub_generator.h"
 #include <google/api/routing.pb.h>
@@ -696,6 +697,11 @@ VarsDictionary CreateServiceVars(
   vars["client_header_path"] =
       absl::StrCat(vars["product_path"],
                    ServiceNameToFilePath(descriptor.name()), "_client.h");
+
+  vars["client_samples_cc_path"] = absl::StrCat(
+      vars["product_path"], "samples/",
+      ServiceNameToFilePath(descriptor.name()), "_client_samples.cc");
+
   vars["connection_class_name"] = absl::StrCat(descriptor.name(), "Connection");
   vars["connection_cc_path"] =
       absl::StrCat(vars["product_path"],
@@ -872,6 +878,8 @@ std::vector<std::unique_ptr<GeneratorInterface>> MakeGenerators(
   if (omit_client == service_vars.end() || omit_client->second != "true") {
     code_generators.push_back(absl::make_unique<ClientGenerator>(
         service, service_vars, method_vars, context));
+    code_generators.push_back(absl::make_unique<SampleGenerator>(
+        service, service_vars, method_vars, context));
   }
   auto const omit_connection = service_vars.find("omit_connection");
   if (omit_connection == service_vars.end() ||

generator/internal/sample_generator.cc

@@ -0,0 +1,90 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "generator/internal/sample_generator.h"
+
+namespace google {
+namespace cloud {
+namespace generator_internal {
+
+SampleGenerator::SampleGenerator(
+    google::protobuf::ServiceDescriptor const* service_descriptor,
+    VarsDictionary service_vars,
+    std::map<std::string, VarsDictionary> service_method_vars,
+    google::protobuf::compiler::GeneratorContext* context)
+    : ServiceCodeGenerator("client_samples_cc_path", service_descriptor,
+                           std::move(service_vars),
+                           std::move(service_method_vars), context) {}
+
+Status SampleGenerator::GenerateCc() { return {}; }
+
+Status SampleGenerator::GenerateHeader() {
+  HeaderPrint(CopyrightLicenseFileHeader());
+  HeaderPrint(R"""(
+// Generated by the Codegen C++ plugin.
+// If you make any local changes, they will be lost.
+// source: $proto_file_name$
+
+)""");
+
+  HeaderLocalIncludes({
+      vars("client_header_path"),
+      "google/cloud/common_options.h",
+      "google/cloud/testing_util/example_driver.h",
+  });
+  HeaderSystemIncludes({"iostream", "string", "vector"});
+
+  HeaderPrint(R"""(
+namespace {
+
+void SetClientEndpoint(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-endpoint"};
+  }
+  //! [set-client-endpoint]
+  // This configuration is common with Private Google Access:
+  //     https://cloud.google.com/vpc/docs/private-google-access
+  auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
+      "private.googleapis.com");
+  auto client = google::cloud::$product_namespace$::$client_class_name$(
+      google::cloud::$product_namespace$::Make$connection_class_name$(options));
+  // Use the `client` object as usual
+  //! [set-client-endpoint]
+}
+
+// main-dox-marker: $client_class_name$
+void AutoRun(std::vector<std::string> const& argv) {
+  if (!argv.empty()) throw google::cloud::testing_util::Usage{"auto"};
+
+  std::cout << "\nRunning SetClientEndpoint() example" << std::endl;
+  SetClientEndpoint({});
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
+  google::cloud::testing_util::Example example({
+      {"set-client-endpoint", SetClientEndpoint},
+      {"auto", AutoRun},
+  });
+  return example.Run(argc, argv);
+}
+)""");
+
+  return {};
+}
+
+}  // namespace generator_internal
+}  // namespace cloud
+}  // namespace google