[gnome-builder] doc: add save-buffer mutation example

[Christian Hergert <chergert src gnome org>]

commit fd827501ec9e34855d9e06eb004aca547cae3022
Author: Christian Hergert <chergert redhat com>
Date:   Fri Aug 4 17:04:38 2017 -0700

    doc: add save-buffer mutation example

 doc/examples/format_on_save.py |   66 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 66 insertions(+), 0 deletions(-)
---
diff --git a/doc/examples/format_on_save.py b/doc/examples/format_on_save.py
new file mode 100644
index 0000000..02f570a
--- /dev/null
+++ b/doc/examples/format_on_save.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+
+from gi.repository import GObject
+from gi.repository import Gio
+from gi.repository import Ide
+
+_NEEDS_BUILD_RUNTIME = False
+
+class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+    handler = None
+
+    def do_load(self, workbench):
+        context = workbench.get_context()
+        bufmgr = context.get_buffer_manager()
+        self.handler = bufmgr.connect('save-buffer', self.on_save_buffer)
+
+    def do_unload(self, workbench):
+        context = workbench.get_context()
+        bufmgr = context.get_buffer_manager()
+        bufmgr.disconnect(self.handler)
+
+    def on_save_buffer(self, bufmgr, buffer):
+        # Ignore everything if this isn't C code.
+        # The language identifier comes from gtksourceview *.lang files
+        lang = buffer.get_language()
+        if lang is None or lang.get_id() not in ('c', 'chdr'):
+            return
+
+        # If you need to run the program in the build environment, you might
+        # need to do something like:
+        if _NEEDS_BUILD_RUNTIME:
+            context = buffer.get_context()
+            runtime = context.get_build_manager().get_pipeline().get_runtime()
+            launcher = runtime.create_launcher()
+        else:
+            launcher = Ide.SubprocessLauncher.new(0)
+
+        # Make sure we get stdin/stdout for communication
+        launcher.set_flags(Gio.SubprocessFlags.STDIN_PIPE |
+                           Gio.SubprocessFlags.STDOUT_PIPE)
+
+        # Setup our cmdline arguments
+        launcher.push_argv('indent')
+
+        # If your target program is installed on the host (and not bundled
+        # or found in the build environment runtime) you might need to set
+        # this so the program runs on the physical host, breaking out of
+        # the sandbox (yes, we can do that).
+        launcher.set_run_on_host(True)
+
+        # Launch the process
+        subprocess = launcher.spawn()
+
+        # Pipe the buffer contents to the indent process.
+        # communicate_utf8() will raise if it fails.
+        begin, end = buffer.get_bounds()
+        text = buffer.get_text(begin, end, True)
+        ret, stdout, stderr = subprocess.communicate_utf8(text, None)
+
+        # Now write the new contents back
+        buffer.set_text(stdout, len(stdout))
+
+        # TODO: You might want to save the location of the insertion
+        #       cursor and restore it after replacing the contents.
+        #       Otherwise, the cursor will jump to the end of the file.
+