Merge remote-tracking branch 'plugin/HostOS/f/monorepo' into f/monorepo-stage2

doc/plugin/HostOS.md

@@ -0,0 +1,96 @@
+# Kaleidoscope-HostOS
+
+The `HostOS` extension is not all that useful in itself, rather, it is a
+building block other plugins and extensions can use to not repeat the same
+guesswork and logic.
+
+The goal is to have a single place that remembers the host OS, whether set by
+the end-user in a Sketch, or via a macro, or some other way. This information
+can then be reused by other plugins.
+
+See the [Unicode][plugin:unicode] extension for an example about how to use
+`HostOS` in practice.
+
+ [plugin:unicode]: Unicode.md
+
+## Using the extension
+
+The extension provides a `HostOS` singleton object.
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-HostOS.h>
+
+void someFunction(void) {
+  if (HostOS.os() == kaleidoscope::hostos::LINUX) {
+    // do something linux-y
+  }
+  if (HostOS.os() == kaleidoscope::hostos::OSX) {
+    // do something OSX-y
+  }
+}
+
+KALEIDOSCOPE_INIT_PLUGINS(HostOS)
+
+void setup(void) {
+  Kaleidoscope.setup ();
+}
+```
+
+## Extension methods
+
+The extension provides the following methods on the `HostOS` singleton:
+
+### `.os()`
+
+> Returns the stored type of the Host OS.
+
+### `.os(type)`
+
+> Sets the type of the host OS, overriding any previous value. The type is then
+> stored in EEPROM for persistence.
+
+## Host OS Values
+
+The OS type (i.e. the return type of `.os()` and the arguments to `.os(type)`) will be one of the following:
+
+   - `kaleidoscope::hostos::LINUX`
+   - `kaleidoscope::hostos::OSX`
+   - `kaleidoscope::hostos::WINDOWS`
+   - `kaleidoscope::hostos::OTHER`
+
+## Focus commands
+
+The plugin provides the `FocusHostOSCommand` object, which, when enabled,
+provides the `hostos.type` Focus command.
+
+### `hostos.type [type]`
+
+> Without argument, returns the current OS type set (a numeric value).
+>
+> With an argument, it sets the OS type.
+>
+> This command can be used from the host to reliably set the OS type within the firmware.
+
+## Dependencies
+
+* [Kaleidoscope-EEPROM-Settings](EEPROM-Settings.md)
+
+## Further reading
+
+Starting from the [example][plugin:example] is the recommended way of getting
+started with the extension.
+
+ [plugin:example]: ../../examples/HostOS/HostOS.ino
+
+## Upgrading
+
+Prior versions of `HostOS` used to include a way to auto-detect the host
+operating system. This code was brittle, unreliable, and rather big too. For
+these reasons, this functionality was removed. The `autoDetect()` method is now
+a no-op, and is deprecated. The `Kaleidoscope/HostOS-select.h` header is
+similarly obsolete, and has even been removed (for unrelated reasons). The
+`autoDetect()` method will be removed by 2019-01-14.
+
+Furthermore, `HostOS` now depends on `Kaleidoscope-EEPROM-Settings`, that plugin
+should be initialized first.

examples/HostOS/HostOS.ino

@@ -0,0 +1,56 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-HostOS -- Host OS detection and tracking for Kaleidoscope
+ * Copyright (C) 2016, 2017, 2018  Keyboard.io, Inc
+ *
+ * This program 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, version 3.
+ *
+ * This program 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
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-HostOS.h>
+
+// *INDENT-OFF*
+const Key keymaps[][ROWS][COLS] PROGMEM = {
+  [0] = KEYMAP_STACKED
+  (Key_NoKey,    Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
+   Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
+   Key_PageUp,   Key_A, Key_S, Key_D, Key_F, Key_G,
+   Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
+
+   Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
+   Key_skip,
+
+   Key_skip,  Key_6, Key_7, Key_8,     Key_9,      Key_0,         Key_skip,
+   Key_Enter, Key_Y, Key_U, Key_I,     Key_O,      Key_P,         Key_Equals,
+              Key_H, Key_J, Key_K,     Key_L,      Key_Semicolon, Key_Quote,
+   Key_skip,  Key_N, Key_M, Key_Comma, Key_Period, Key_Slash,     Key_Minus,
+
+   Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
+   Key_skip),
+};
+// *INDENT-ON*
+
+KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, HostOS);
+
+void setup() {
+  Serial.begin(9600);
+
+  Kaleidoscope.setup();
+
+  Serial.print("Host OS id is: ");
+  Serial.println(HostOS.os(), DEC);
+}
+
+void loop() {
+  Kaleidoscope.loop();
+}

src/Kaleidoscope-HostOS.h

@@ -0,0 +1,21 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-HostOS -- Host OS detection and tracking for Kaleidoscope
+ * Copyright (C) 2016, 2017, 2018  Keyboard.io, Inc
+ *
+ * This program 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, version 3.
+ *
+ * This program 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
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <kaleidoscope/plugin/HostOS.h>
+#include <kaleidoscope/plugin/HostOS-Focus.h>

src/kaleidoscope/plugin/HostOS-Focus.cpp

@@ -0,0 +1,46 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-HostOS -- Host OS detection and tracking for Kaleidoscope
+ * Copyright (C) 2016, 2017, 2018  Keyboard.io, Inc
+ *
+ * This program 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, version 3.
+ *
+ * This program 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
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <Kaleidoscope-HostOS.h>
+#include <Kaleidoscope-FocusSerial.h>
+
+namespace kaleidoscope {
+namespace plugin {
+
+EventHandlerResult FocusHostOSCommand::onFocusEvent(const char *command) {
+  const char *cmd = PSTR("hostos.type");
+
+  if (::Focus.handleHelp(command, cmd))
+    return EventHandlerResult::OK;
+  if (strcmp_P(command, cmd) != 0)
+    return EventHandlerResult::OK;
+
+  if (Serial.peek() == '\n') {
+    Serial.println(::HostOS.os());
+  } else {
+    uint8_t new_os = Serial.parseInt();
+    ::HostOS.os((hostos::Type) new_os);
+  }
+
+  Serial.read();
+  return EventHandlerResult::EVENT_CONSUMED;
+}
+
+}
+}
+
+kaleidoscope::plugin::FocusHostOSCommand FocusHostOSCommand;

src/kaleidoscope/plugin/HostOS-Focus.h

@@ -0,0 +1,33 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-HostOS -- Host OS detection and tracking for Kaleidoscope
+ * Copyright (C) 2016, 2017, 2018  Keyboard.io, Inc
+ *
+ * This program 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, version 3.
+ *
+ * This program 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
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <Kaleidoscope.h>
+
+namespace kaleidoscope {
+namespace plugin {
+
+class FocusHostOSCommand : public kaleidoscope::Plugin {
+ public:
+  FocusHostOSCommand() {}
+  EventHandlerResult onFocusEvent(const char *command);
+};
+}
+}
+
+extern kaleidoscope::plugin::FocusHostOSCommand FocusHostOSCommand;

src/kaleidoscope/plugin/HostOS.cpp

@@ -0,0 +1,51 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-HostOS -- Host OS detection and tracking for Kaleidoscope
+ * Copyright (C) 2016, 2017, 2018  Keyboard.io, Inc
+ *
+ * This program 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, version 3.
+ *
+ * This program 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
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <kaleidoscope/plugin/HostOS.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+
+#include <EEPROM.h>
+
+namespace kaleidoscope {
+namespace plugin {
+
+EventHandlerResult HostOS::onSetup(void) {
+  if (is_configured_)
+    return EventHandlerResult::OK;
+
+  eeprom_slice_ = ::EEPROMSettings.requestSlice(sizeof(os_));
+
+  is_configured_ = true;
+
+  if (os_ != hostos::UNKNOWN) {
+    return EventHandlerResult::OK;
+  }
+
+  os_ = (hostos::Type)EEPROM.read(eeprom_slice_);
+
+  return EventHandlerResult::OK;
+}
+
+void HostOS::os(hostos::Type new_os) {
+  os_ = new_os;
+  EEPROM.update(eeprom_slice_, os_);
+}
+
+}
+}
+
+kaleidoscope::plugin::HostOS HostOS;

src/kaleidoscope/plugin/HostOS.h

@@ -0,0 +1,66 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-HostOS -- Host OS detection and tracking for Kaleidoscope
+ * Copyright (C) 2016, 2017, 2018  Keyboard.io, Inc
+ *
+ * This program 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, version 3.
+ *
+ * This program 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
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <Kaleidoscope.h>
+
+namespace kaleidoscope {
+namespace plugin {
+namespace hostos {
+
+typedef enum {
+  LINUX,
+  OSX,
+  WINDOWS,
+  OTHER,
+
+  UNKNOWN = 0xff,
+  AUTO = UNKNOWN
+} Type;
+
+}
+
+#define _DEPRECATED_MESSAGE_AUTODETECT                                  \
+  "The auto-detect mechanism of HostOS was removed, because it was\n"   \
+  "too unreliable. As such, the HostOS.autoDetect() method does\n"      \
+  "nothing anymore. Please consider other ways of changing the\n"       \
+  "HostOS type."
+
+class HostOS : public kaleidoscope::Plugin {
+ public:
+  HostOS() {}
+  EventHandlerResult onSetup();
+
+  hostos::Type os(void) {
+    return os_;
+  }
+  void os(hostos::Type new_os);
+
+  void autoDetect() DEPRECATED(AUTODETECT) {}
+
+ private:
+  hostos::Type os_;
+  uint16_t eeprom_slice_;
+  bool is_configured_ = false;
+};
+}
+
+namespace hostos = plugin::hostos;
+}
+
+extern kaleidoscope::plugin::HostOS HostOS;