Added 'lib examples' command

[cmaglie]

Still missing tests. I don't know if the current UX is correct, at the moment we have:

$ arduino-cli lib examples Wire
Examples for library Wire (arduino-beta:mbed@1.2.1)

Examples for library Wire (MightyCore:avr@2.0.5)
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/SFRRanger_reader
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/digital_potentiometer
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/i2c_scanner
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/master_reader
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/master_writer
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/slave_receiver
  - /home/megabug/.arduino15/packages/MightyCore/hardware/avr/2.0.5/libraries/Wire/examples/slave_sender

Examples for library Wire (esp32:esp32@1.0.4)

Examples for library Wire (adafruit:samd@1.6.0)
  - /home/megabug/.arduino15/packages/adafruit/hardware/samd/1.6.0/libraries/Wire/examples/SFRRanger_reader
  - /home/megabug/.arduino15/packages/adafruit/hardware/samd/1.6.0/libraries/Wire/examples/digital_potentiometer
  - /home/megabug/.arduino15/packages/adafruit/hardware/samd/1.6.0/libraries/Wire/examples/master_reader
  - /home/megabug/.arduino15/packages/adafruit/hardware/samd/1.6.0/libraries/Wire/examples/master_writer
  - /home/megabug/.arduino15/packages/adafruit/hardware/samd/1.6.0/libraries/Wire/examples/slave_receiver
  - /home/megabug/.arduino15/packages/adafruit/hardware/samd/1.6.0/libraries/Wire/examples/slave_sender

Examples for library Wire (esp8266:esp8266@2.7.2)
  - /home/megabug/.arduino15/packages/esp8266/hardware/esp8266/2.7.2/libraries/Wire/examples/master_reader
  - /home/megabug/.arduino15/packages/esp8266/hardware/esp8266/2.7.2/libraries/Wire/examples/master_writer
  - /home/megabug/.arduino15/packages/esp8266/hardware/esp8266/2.7.2/libraries/Wire/examples/slave_receiver
  - /home/megabug/.arduino15/packages/esp8266/hardware/esp8266/2.7.2/libraries/Wire/examples/slave_sender

Examples for library Wire (arduino:mbed@1.9.8)

Examples for library Wire (arduino:avr@1.8.3)
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/SFRRanger_reader
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/digital_potentiometer
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/i2c_scanner
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/master_reader
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/master_writer
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/slave_receiver
  - /home/megabug/.arduino15/packages/arduino/hardware/avr/1.8.3/libraries/Wire/examples/slave_sender

this command will show the examples for all the instances of Wire installed.

The json version:

arduino-cli lib examples Audio --format=json

will output the same metadata as lib list with an added example field` on top of the json structure:

$ ./arduino-cli lib examples Audio --format=json
[
  {
    "library": {
      "name": "Audio",
      "author": "Arduino",
      "maintainer": "Arduino \u003cinfo@arduino.cc\u003e",
      "sentence": "Allows playing audio files from an SD card. For Arduino DUE only.",
      "paragraph": "With this library you can use the Arduino Due DAC outputs to play audio files.\u003cbr /\u003eThe audio files must be in the raw .wav format.",
      "website": "http://www.arduino.cc/en/Reference/Audio",
      "category": "Signal Input/Output",
      "architectures": [
        "sam"
      ],
      "install_dir": "/home/megabug/Workspace/sketchbook-cores-beta/libraries/Audio",
      "source_dir": "/home/megabug/Workspace/sketchbook-cores-beta/libraries/Audio/src",
      "real_name": "Audio",
      "version": "1.0.5",
      "license": "Unspecified",
      "location": 1,
      "layout": 1,
      "examples": [
        "/home/megabug/Workspace/sketchbook-cores-beta/libraries/Audio/examples/SimpleAudioPlayer"
      ]
    },
    "examples": [
      "/home/megabug/Workspace/sketchbook-cores-beta/libraries/Audio/examples/SimpleAudioPlayer"
    ]
  }
}

this will help to figure out at which library the examples belongs if we have multilple libraries spread across platforms (like the Wire example above) since all the metadata is there, but still we can easily filter only the examples if required:

$ ./arduino-cli lib examples Audio --format=json | jq -r .[].examples
[
  "/home/megabug/Workspace/sketchbook-cores-beta/libraries/Audio/examples/SimpleAudioPlayer"
]

[rsora]

A provocative thought 😺: what about having a lib details -n <lib name>?

[cmaglie]

ok, pushed another iteration, now I've added an --fqbn BOARD_FQBN that allows to filter libraries for a specific board (i.e. exclude libraries that comes from platforms different from the board's platform).

• arduino-cli lib examples will list examples for all installled libraries in all platforms
• arduino-cli lib examples --fqbn arduino:avr:uno will list examples for all libraries for a specific board
• arduino-cli lib examples Wire will list examples for the Wire library in all platforms
• arduino-cli lib examples Wire --fqbn arduino:avr:uno will list examples for the Wire library for a specific board

as a bonus we can apply the same filters to the lib list command:

• arduino-cli lib list ArduinoBLE will show only informations about ArduinoBLE
• arduino-cli lib list Wire --all will show only informations about Wire in all platforms
• arduino-cli lib list Wire --fqbn arduino:avr:uno --all will show only informations about Wire in arduino:avr platform

BTW lib examples does not have a --all flag (like in lib list) because in lib examples it's always enabled by default.
The rationale for this is that when you look for the examples you want to target a single library, so you specify the name via command line, but the library can be also part of a platform: adding a --all will just get in the way without any real benefit in this case.

[kittaakos]

As a verification, I am going to integrate the new APIs into the Pro IDE.

[kittaakos]

Please consider moving the examples from Library to LibraryRelease.

For me, a Library is the unique identifier (with its name) and it has 1..* LibraryReleases.

A Library can have, for example, two releases, 1.0.0 and 1.1.0.

The 1.0.0 version can have two examples:

[
  '/path/to/example/A',
  '/path/to/example/B'
]

And the latest, 1.1.0 LibraryRelease version can have an update, so it has comes with three examples:

[
  '/path/to/example/A',
  '/path/to/example/B',
  '/path/to/example/NewFeatureFrom_1_1_0',
]

Possible related: #928

[kittaakos]

+1 for merging this PR as-is; we can handle #928 later together with the currently unnecessary instance.