Koans to the Future

Summary:
The first file of Koans. Some simple constructor and `makeFuture` stuff, but this diff is mostly about the framework (ie the `TARGETS` and `main.cpp` and `Koan.h`, and the layout of the Koan files).

Known Issues: I am not nearly enlightened enough to write these in a particularly zen style with lots of inside zen-jokes, so I'm not even trying.

Test Plan:
Work through the koans,
then `fbmake runtests`,
reach enlightenment

Reviewed By: davejwatson@fb.com

Subscribers: cgthayer, exa, folly-diffs@, jsedgwick, yfeldblum, bmatheny, chalfant

FB internal diff: D2082141

Tasks: 6973057

Signature: t1:2082141:1432057657:273708f566154cc54f726b85f05457388357ef4e

folly/futures/exercises/01-Values.cpp

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2015 Facebook, Inc.
+ *
+ * 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
+ *
+ *   http://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 "Koan.h"
+#include <folly/futures/Future.h>
+
+using folly::Future;
+using folly::makeFuture;
+
+#if 0 // compilation cursor
+
+TEST(Values, canonicalForm) {
+  // The canonical way to make a Future from an immediate value is with the
+  // Future constructor.
+  Future<int> answer(__);
+  EXPECT_EQ(42, answer.get());
+}
+
+TEST(Values, typeDeduction) {
+  // If you use makeFuture, the compiler will deduce the type.
+  auto answer = makeFuture(__);
+  EXPECT_EQ(42, answer.get());
+}
+
+TEST(Values, exceptionNeedsType) {
+  // To create a Future holding an exception, you must
+  // use makeFuture with the type
+  std::runtime_error err("Don't Panic");
+  auto question = __(err);
+  // not
+  //auto question = makeFuture(err);
+  EXPECT_THROW(question.get(), std::runtime_error);
+}
+
+TEST(Values, typeConversion) {
+  // Sometimes it's cleaner to give the type and let the compiler do implicit
+  // type conversion
+  __ answer(42);
+  // not
+  //auto answer = makeFuture((double)42);
+  EXPECT_EQ(__, answer.get());
+}
+
+using folly::Try;
+
+TEST(Values, tryInside) {
+  // Futures hold either a Value or Exception. This is accomplished under the
+  // covers with Try
+  Try<int> t = makeFuture(42).__();
+  EXPECT_TRUE(t.hasValue());
+  EXPECT_EQ(42, t.value());
+
+  t = Future<int>(std::runtime_error("Don't Panic")).__();
+  EXPECT_TRUE(t.hasException());
+  EXPECT_THROW(t.value(), std::runtime_error);
+}
+
+#endif

folly/futures/exercises/Koan.h

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2015 Facebook, Inc.
+ *
+ * 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
+ *
+ *   http://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.
+ */
+#pragma once
+#include <folly/Portability.h>
+#include <gtest/gtest.h>
+#include <gflags/gflags.h>

folly/futures/exercises/README.md

@@ -0,0 +1,9 @@
+Working through [Programming Koans][1] can be a fun, lightweight, and fast way to
+learn a new language or pattern with small, focused exercises. Therefore, we
+present Koans for Futures.  Perhaps you will call them "Koans to Be".
+
+Edit the topical files one at a time, moving the "compilation cursor" down one
+exercise at a time, and getting them to pass by filling in the blanks.
+
+[1] http://www.lauradhamilton.com/learn-a-new-programming-language-today-with-koans
+[2] http://catb.org/esr/writings/unix-koans/ten-thousand.html

folly/futures/exercises/main.cpp

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2015 Facebook, Inc.
+ *
+ * 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
+ *
+ *   http://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 "Koan.h"
+
+int main(int argc, char** argv) {
+  ::testing::InitGoogleTest(&argc, argv);
+  ::gflags::ParseCommandLineFlags(&argc, &argv, true);
+  return RUN_ALL_TESTS();
+}