[Courgette] Refactor: Add CourgetteFlow; improve courgette_tool.cc help text.

courgette/courgette_flow.h

Index: courgette/courgette_flow.h
diff --git a/courgette/courgette_flow.h b/courgette/courgette_flow.h
new file mode 100644
index 0000000000000000000000000000000000000000..c943a1717e7284f22679c7770f91d58348bfe989
--- /dev/null
+++ b/courgette/courgette_flow.h
@@ -0,0 +1,128 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef COURGETTE_COURGETTE_FLOW_H_
+#define COURGETTE_COURGETTE_FLOW_H_
+
+#include <memory>
+#include <string>
+
+#include "base/macros.h"
+#include "courgette/courgette.h"
+#include "courgette/region.h"
+#include "courgette/streams.h"
+
+namespace courgette {
+
+class AssemblyProgram;
+class EncodedProgram;
+
+// An adaptor for Region as BasicBuffer.
+class RegionBuffer : public BasicBuffer {
+ public:
+  explicit RegionBuffer(const Region& region) : region_(region) {}
+
+  // BasicBuffer:
+  const uint8_t* data() const override { return region_.start(); }
+  size_t length() const override { return region_.length(); }
+
+ private:
+  Region region_;
+
+  DISALLOW_COPY_AND_ASSIGN(RegionBuffer);
+};
+
+// CourgetteFlow stores Courgette data arranged into groups, and exposes
+// "commands" that operate on them. On the first occurrence of an error, the
+// Courgette error code is recorded, error messages are generated and stored,
+// and all subsequent commands become no-op. This allows callers to concisely
+// specify high-level logic with minimal code for error handling.
+class CourgetteFlow {
+ public:
+  // A group of Courgette data, for a single executable. Takes negligible space
+  // when unused.
+  struct Data {
+    Data();
+    ~Data();
+
+    std::unique_ptr<AssemblyProgram> program;
+    std::unique_ptr<EncodedProgram> encoded;
+    SinkStreamSet sinks;
+    SourceStreamSet sources;
+  };
+
+  // Group enumeration into |data_*_| fields.
+  enum Group { ONLY, OLD, NEW };

[chrisha, 2017/04/24 18:15:50]

Could use comments? What is "ONLY"?

[huangs, 2017/04/24 20:08:14]

Done.

+
+  CourgetteFlow();
+  ~CourgetteFlow();
+
+  static const char* name(Group group);
+  Data* data(Group group);  // Allows caller to modify.
+  bool ok();
+  bool failed();
+  Status status();
+  const std::string& message();
+
+  // Commands  that perform no-op on error. This allows caller to concisely

[chrisha, 2017/04/24 18:15:50]

remove extra space

[huangs, 2017/04/24 20:08:14]

Done.

+  // specify high-level logic, and perform a single error check at the end. Care
+  // must be taken w.r.t. error handling if |data()| is harvested between
+  // commands.
+
+  void ReadSourceStreamSetFromBuffer(Group group, const BasicBuffer& buffer);

[chrisha, 2017/04/24 18:15:50]

In general, all of these functions could use comments describing the logic.

[huangs, 2017/04/24 20:08:14]

Done.

+
+  void ReadAssemblyProgramFromBuffer(Group group,
+                                     const BasicBuffer& buffer,
+                                     bool annotate);
+
+  // If |opt_sources| is unspecified then |data(which)->sources| is used.

[chrisha, 2017/04/24 18:15:50]

|which|? Do you mean |group|?

[huangs, 2017/04/24 20:08:14]

Done.

+  void ReadEncodedProgramFromSourceStreamSet(
+      Group group,
+      SourceStreamSet* opt_sources = nullptr);
+
+  void CreateEncodedProgramFromAssemblyProgram(Group group);
+
+  void WriteSinkStreamFromSinkStreamSet(Group group, SinkStream* sink);
+
+  // If |opt_sinks| is unspecified then |data(which)->sinks| is used.
+  void WriteSinkStreamSetFromEncodedProgram(Group group,
+                                            SinkStreamSet* opt_sinks = nullptr);
+
+  void WriteExecutableFromEncodedProgram(Group group, SinkStream* sink);
+
+  void AdjustNewAssemblyProgramToMatchOld();
+
+  // Destructor commands to reduce memory usage.
+
+  void DestroyAssemblyProgram(Group group);
+
+  void DestroyEncodedProgram(Group group);
+
+ private:
+  // Utilities to process return values from Courgette functions, and assign
+  // |status_| and |message_|. Usage:
+  //   if (!check(some_couregtte_function(param1, ...)))

[chrisha, 2017/04/24 18:15:50]

courgette*

[huangs, 2017/04/24 20:08:14]

Done.

+  //     setMessage("format string %s...", value1, ...);
+
+  // Reassigns |status_|, and returns true if |C_OK|.
+  bool check(Status new_status);
+
+  // check() alternative for functions that return true on succes. On failure
+  // assigns |status_| to |failure_mode|.
+  bool check(bool success, Status failure_mode);
+
+  void setMessage(const char* format, ...);
+
+  Status status_ = C_OK;
+  std::string message_;
+  Data data_only_;
+  Data data_old_;
+  Data data_new_;
+
+  DISALLOW_COPY_AND_ASSIGN(CourgetteFlow);
+};
+
+}  // namespace courgette
+
+#endif  // COURGETTE_COURGETTE_FLOW_H_