[libgpiod][PATCH 0/4] dedicated examples

[Kent Gibson <warthog618@xxxxxxxxx>]

This series forms the basis of a proposal to rework the libgpiod
examples.

IMHO, the examples have a number of issues including:
 - no C examples other than the tools - which have become too complicated
   to be fit for that purpose.
 - bindings examples focus on simplifications of the tools rather than
   demonstrating typical use cases.
 - being more complex than necessary to demonstrate a particular use case.
 - naming that does not help new users identify the example that
   demonstrates a particular use case.

To address these issues I propose adding a set of dedicated examples,
each of which demonstrates one primary use case with as little
additional fat as possible.  Each example should be named after the use
case it demonstrates.  Each examples should be implemented for all
supported languages, to provide examples for users considering
language choice and for developers to compare the APIs and identify
areas for improvement.

The examples are explicitly intended to answer "how do I use libgpiod to
do xxx" questions, with as few distractions as possible.

The examples may demonstrate ancillary features, as long as that is
relevant to the primary use case. e.g. the watch_line_value examples
set the line bias and debounce.

The examples should hard code input parameters, not pull them from the
command line or environment, as that is distracting and frequently more
complicated than the example itself.

The examples should be standalone - they should not share code.  Large
chunks of shared code are an indicator that libgpiod probably needs to
provide additional functionality to simplify use cases.

The examples are not intended to be distributed in binary form, but
could be incorporated into the documentation.

The set of examples provided is a starter set that answer the following
questions:
 - how do you get the value of a line?
 - how do you set the value of a line?
 - how do you watch for edge events on a line?
 - how do you watch for edge events asynchronously (e.g. using poll())?

I didn't add the latter in Rust as that should be done using one of the
many available async reactors and I didn't want to pick one or pull in
any dependencies.

I expect that this proposal may be contraversial, and that is one of the
reasons I've kept the starter set small.

Cheers,
Kent.

Kent Gibson (4):
  core: examples: add dedicated examples
  bindings: cxx: examples: add dedicated examples
  bindings: python: examples: add dedicated examples
  bindings: rust: examples: add dedicated examples

 Makefile.am                                   |   6 +
 bindings/cxx/examples/.gitignore              |   4 +
 bindings/cxx/examples/Makefile.am             |  14 +-
 .../cxx/examples/async_watch_line_value.cpp   |  78 ++++++++++
 bindings/cxx/examples/get_line_value.cpp      |  29 ++++
 bindings/cxx/examples/toggle_line_value.cpp   |  45 ++++++
 bindings/cxx/examples/watch_line_value.cpp    |  62 ++++++++
 .../python/examples/async_watch_line_value.py |  47 ++++++
 bindings/python/examples/get_line_value.py    |  26 ++++
 bindings/python/examples/toggle_line_value.py |  47 ++++++
 bindings/python/examples/watch_line_value.py  |  42 ++++++
 .../rust/libgpiod/examples/get_line_value.rs  |  28 ++++
 .../libgpiod/examples/toggle_line_value.rs    |  43 ++++++
 .../libgpiod/examples/watch_line_value.rs     |  50 +++++++
 configure.ac                                  |   1 +
 examples/.gitignore                           |   7 +
 examples/Makefile.am                          |  17 +++
 examples/async_watch_line_value.c             | 136 ++++++++++++++++++
 examples/get_line_value.c                     |  97 +++++++++++++
 examples/toggle_line_value.c                  | 106 ++++++++++++++
 examples/watch_line_value.c                   | 127 ++++++++++++++++
 21 files changed, 1011 insertions(+), 1 deletion(-)
 create mode 100644 bindings/cxx/examples/async_watch_line_value.cpp
 create mode 100644 bindings/cxx/examples/get_line_value.cpp
 create mode 100644 bindings/cxx/examples/toggle_line_value.cpp
 create mode 100644 bindings/cxx/examples/watch_line_value.cpp
 create mode 100755 bindings/python/examples/async_watch_line_value.py
 create mode 100755 bindings/python/examples/get_line_value.py
 create mode 100755 bindings/python/examples/toggle_line_value.py
 create mode 100755 bindings/python/examples/watch_line_value.py
 create mode 100644 bindings/rust/libgpiod/examples/get_line_value.rs
 create mode 100644 bindings/rust/libgpiod/examples/toggle_line_value.rs
 create mode 100644 bindings/rust/libgpiod/examples/watch_line_value.rs
 create mode 100644 examples/.gitignore
 create mode 100644 examples/Makefile.am
 create mode 100644 examples/async_watch_line_value.c
 create mode 100644 examples/get_line_value.c
 create mode 100644 examples/toggle_line_value.c
 create mode 100644 examples/watch_line_value.c

-- 
2.40.1