arli 0.8.3 → 0.9.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 4403d1e6ec0453ea707b6a1bca1cf89f47a8e848
4
- data.tar.gz: 8387afcccd21d9c8cc62bd43140e70bbd34eced2
3
+ metadata.gz: de043be09051d5efc23d015a0d25499a88213639
4
+ data.tar.gz: 5847acb4a33cf1962045684aac21ba5662fa9536
5
5
  SHA512:
6
- metadata.gz: 448cc7c706ea9192bc13db514060d319ff7beac6bb749131aaab0a7deead3f3b036cf61cbad8b99a86eeb560d1b2018085cd7efc0c5617d83d0c75d21ee76068
7
- data.tar.gz: b67cd69f59905e5136bb4bd4175e696d929a53563412c7293719b881758145e56a650f28a23419ba112abf4bb8d6cb40820f80fd85969dc03484b08c27d56a91
6
+ metadata.gz: 8cdaf4315432f68158dfbd5a44b664947172fbcfeb2fb49808ac65647158f59176015c44748fdaff92e2e1fa20783eddb844ddd3614e084dbb320d108ce1a77d
7
+ data.tar.gz: 9d4d5826901bca3cd3cf3bb3e077aa491464b42193b2acec91f53ee1b2ac49a0aefeec10a4f66d829f1d60c20905af015088fdcda91a820ccb71db180157002b
data/.gitignore CHANGED
@@ -1,3 +1,4 @@
1
+ cmake/
1
2
  .idea/
2
3
  /.bundle/
3
4
  /.yardoc
@@ -9,11 +10,11 @@
9
10
  /spec/coverage/
10
11
  /tmp/
11
12
  /data
12
- /spec/coverage/
13
13
  /*.enc
14
14
  **/.DS_Store
15
15
  .ruby-version
16
16
  .rspec_status
17
- !/lib/arli/commands/install.rb
18
- !/lib/arli/cli/parser.rb
19
- /spec/fixtures/file*/Arlifile.lock*
17
+ /spec/fixtures/file*/Arlifile.*
18
+ /spec/fixtures/file*/libraries
19
+ .rake_tasks~
20
+
@@ -1,18 +1,26 @@
1
1
  env:
2
2
  global:
3
- - CC_TEST_REPORTER_ID=f8f229bdf1f374a3a9227d3bef6f57b78f88c73a2d4705c9de5852bb484eaaef
3
+ - CC_TEST_REPORTER_ID=f8f229bdf1f374a3a9227d3bef6f57b78f88c73a2d4705c9de5852bb484eaaef
4
4
  sudo: false
5
5
  language: ruby
6
6
  cache: bundler
7
7
  rvm:
8
- - 2.4.1
9
- - 2.3.5
8
+ - 2.4.1
9
+ - 2.3.5
10
10
  before_install: gem install bundler -v 1.15.4
11
11
  before_script:
12
- - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
13
- - chmod +x ./cc-test-reporter
14
- - ./cc-test-reporter before-build
12
+ - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64
13
+ > ./cc-test-reporter
14
+ - chmod +x ./cc-test-reporter
15
+ - "./cc-test-reporter before-build"
15
16
  script:
16
- - bundle exec rspec
17
+ - bundle exec rspec
17
18
  after_script:
18
- - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
19
+ - "./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT"
20
+ notifications:
21
+ webhooks:
22
+ urls:
23
+ - secure: fgpv34jAm3rDNjiWuQtuijE0p9B2bpsCWdoCQ82pDZwktSITmNjanYCoZC0hlEw/kqMBDKRN78HfIIidy8dS664sLz8KyaFXq7RWAFsMP9fn/GMG/r9B+S3YumifQ/Zy+3OGa+0Qz76075q291QfNSPv0Y5QDMoAU5VljIVashC/qJS6DRO+vekDaDKIhi4Dr/+JpHPnjchqS4VaMB8gEIrDpeSYNlhrj1oAI/8GwgqZ8UR4sZGxNpIzUg+XGJSYz5/cAB3P18ENSQvOwaNefJa7qIVNjMD7YwXKmfX9cyr5RHM5sibq/S5fHH/N7pig+aveTquGGVxInJr1IEDiyr2TsFARjPitp9KJSFLHLsA2jm1cZfNW0/d6ii+51HdLPKorHom3fPjb0jkIe1LPa9CrrjnfSrAE9a/w4qpSnDv7OjAzkieepz+VQCtpQGIzQxJcHWaFX32iZ6RQ6pmKc/22E0OZwsNM2FHrB5V1b+rfczl8Ej7/R1wAOtHWkbLbfwZ9Ux2N0N0EKW8r8cOjEbsxmN8FFQubTwl68uqjJLhEtrOUbM28JM/NkX+Ue1KRw+NJAdMFEZQKPb/b/X6s3nwPD4/4yLyUDCGyr8aGpzSBD5uIu5uSJNiWdNDjcnXtJJ6TlGGZqj91r7FckjA8FuSA6S3yA8epMNG3FTUxPVE=
24
+ on_success: always
25
+ on_failure: onchange
26
+ on_start: never
data/README.md CHANGED
@@ -3,88 +3,82 @@
3
3
  [![Maintainability](https://api.codeclimate.com/v1/badges/0812671b4bec27ba89b9/maintainability)](https://codeclimate.com/github/kigster/arli/maintainability)
4
4
  [![Test Coverage](https://api.codeclimate.com/v1/badges/0812671b4bec27ba89b9/test_coverage)](https://codeclimate.com/github/kigster/arli/test_coverage)
5
5
 
6
- **NOTE: This software is currently in BETA. Bugs are possible, and reporting them is encouraged.**
6
+ ### Discussion
7
7
 
8
- # Arli
8
+ Please head over to Gitter to discuss this project.
9
9
 
10
- Arli is an awesomely simple and very easy to use Arduino Library Installer. It allows your Arduino projects to be portable by including a small text file called `Arlifile` that defines your project's Arduino library dependencies. Using either this file, or command line flags, Arli is able to search for libraries, install them locally to a custom location, and do it all consistently and reliably.
10
+ [![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/arduino-cmake-arli/)
11
11
 
12
- That way you can share projects with others and they will be able to automatically download and install the dependent libraries instead of having to do that manually. The project is inspired by [Bundler](http://bundler.io/).
12
+ ___
13
13
 
14
- Here is a screenshot of running `arli bundle` inside a project with the `Arlifile` that defines all of the project's library dependencies. We install into a default libraries folder `~/Documents/Arduino/Libraries`:
14
+ > Arli should work in any Unix environment. If you are on Windows, and need support — please [let us know](https://gitter.im/arduino-cmake-arli/).
15
+ >
16
+ > See also "sister project" [Arli-CMake](https://github.com/kigster/arli-cmake).
15
17
 
16
- ![](docs/arli-in-action.png)
18
+ ___
17
19
 
18
- Note that `-f yaml` specifies the format of the "lock" file (`Arlifile.lock`), which is also copied to `Arlifile.lock.[format]`. So in this case our `Arlifile.lock` will be in YAML format, and will contain all library details obtained from the central database.
20
+ # Arli
19
21
 
20
- ## Overview
22
+ **Arli** is an *awesomely simple and very easy to use Arduino Library Manager*. If you are using Arduino IDE you may be wondering **why is this needed?**
21
23
 
22
- ### How Does It Work?
24
+ * Well, for one, Arli can "bundle" libraries not just from the official Arduino database, but also from individual Github URLs. There are thousands of libraries of high quality, that for one reason or another did not make it into the official database.
23
25
 
24
- In a nutshell, Arli relies on the publicly available database of the vast majority of public Ardiuino libraries. This database is maintained by Arduino themselves, and is a [giant gzipped JSON file](http://downloads.arduino.cc/libraries/library_index.json.gz). Arli automatically downloads and caches the index on a local file system, and then lets you search and install libraries using either a simple name search, or more sophisticated ruby-like syntax that supports searching for ANY attribute as an equal match, or a regular expressions, or even a [Proc](http://ruby-doc.org/core-2.4.2/Proc.html).
26
+ * Arduino still haven't come up with a way to automatically document project's dependencies on a set of libraries. I believe the best you've got is having to list libraries in comments, and then install each manually. With Arli you can automate this entire process.
27
+ * [Not everyone likes using Arduino IDE](https://kig.re/2014/08/02/arduino-ide-alternatives.html). So this tool is, perhaps, aimed more at the professional programmers, wanting to build applications that tend to be on a complex side, and rely on multiple third party libraries. Boards like Teensy have a lot more RAM than Arduino UNO and clones, and so it can support much larger projects with dozens of libraries linked in with the firmware.
28
+ * One of Arli's design goals is to provide a bridge between the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake) project, which provides an alternative build system, and is compatible with numerous IDEs such as [Atom](https://atom.io), [JetBrains CLion](https://www.jetbrains.com/clion/), [Visual Studio Code](https://code.visualstudio.com/), or even [Eclipse](https://eclipse.org).
25
29
 
26
- Sometimes, however, an Arduino library you use may not part of the main database. No problem! Just add the `url:` attribute together with the library name. The URL can either be a Github URL, or a URL to a downloadable ZIP file. Arli will figure out the rest.
30
+ ## Overview
27
31
 
28
- ### Arlifile and `bundle`
32
+ Arli allows your Arduino projects to be portable by including a YAML file called `Arlifile` at the top of your project, that defines your project's Arduino library dependencies.
29
33
 
30
- `Arlifile` is a YAML-formatted file that looks like this below. We list all dependencies using the library names that are provided in the database (you can search for the libraries you need prior to populating this file):
34
+ You can use the command `arli bundle` in the project's root directory to search, download and install all dependent libraries defined in the `Arlifile`. You can specify libraries by name and version, or you can omit the version to install the latest one. You can install libraries to a nested project folder, or a shared custom location where you keep all of your Arduino Libraries, and do it all consistently and reliably over and over again.
31
35
 
36
+ Below is an example of an actual `Arlifile` for a [Wall Clock](https://github.com/kigster/arduino-wallclock) project, which is a gorgeous wall clock equipped with a large and bright 7-Segment LED Display that dims automatically when it's dark in the room. In addition, the clock is equipped with multple sensors, a potentiometer, and a rotatary knob for changing time and brightness. This is not a simple project and it has nine library dependencies:
32
37
 
33
38
  ![](docs/arlifile.png)
34
39
 
35
- The libraries may be specified with a name and url only, in which case no search is performed, and the provided URL is used to install the library. The library `SimpleTimer` above is not in the main database, therefore we provide URL for Arli to use.
36
-
37
- If the URL is not provided, you can specify one of several fields that are searched for a matching library. Remember, in this case Arli must find one and only one library to install, otherwise it will throw an error.
38
-
39
- You can provide the following fields in the Arilfile if you want the library to be installed from the central database:
40
-
41
- * `name` should be the exact match. Use double quotes if the name contains spaces.
42
- * `version` can be used together with the `name` to specify a particular version. Without this field, and if the `name` is provided, the latest version is used.
43
- * `checksum` and `archiveFileName` can be used as they both uniquely identify a library.
44
-
45
- In all of the above cases, Arli will search the standard library database provided by the [Arduino official library database](http://downloads.arduino.cc/libraries/library_index.json.gz) JSON file.
40
+ Next, below is a screenshot of running `arli bundle` inside of that with the above `Arlifile`. We install into the default libraries folder `~/Documents/Arduino/Libraries`:
46
41
 
47
- #### Lock File `Arlifile.lock`
42
+ ![](docs/arli-in-action.png)
48
43
 
49
- The lock file is created every time `arli bundle` runs, and it's always in the same folder that the `Arlifile` itself.
44
+ Let's break down what you see on the above screenshot:
50
45
 
51
- The purpose of this file is to document the resolved libraries installed. There are four formats that are supported:
46
+ * First Arli prints the header, containing Arli version, the command, as well as the destination library path that the libraries are going to get installed to.
47
+ * Next, Arli is looping, and for each library without the `url` field, it performs a search by the library `name` (and optionally its `version`), and then it prints the resulting library's name in blue.
48
+ * The `version` that either was specified in the `Arlifile`, or is the latest for this library is printed next, in green.
49
+ * Then Arli downloads the library sources either using the URL provided, or the URL attribute of the search result. Note, that **Arli always downloads libraries into a temporary folder first, always!**. It then scans the files inside, and determines the *canonical directory name* for the given library based on the most appropriate C/C++ header file. The library is first moved to this new name within the temporary folder, and the resulting directory is finally moved into the library path, while also handling the use-case where the library's canonical folder may already exist in the destination. There are three possible actions in this case that can be taken:
52
50
 
53
- * text
54
- * json
55
- * yaml
56
- * cmake
51
+ * the silent default action is to simply **overwrite the existing library folder**.
52
+ * by using `-e [ abort | backup ]` you can optionally do the following:
53
+ * With the `abort` option, the first time an existing library is encountered, the entire command is halted, and an exception is thrown.
54
+ * With the `backup` option, the old library folder is moved by adding an extension `.arli-backup-<TIMESTAMP>`.
55
+
57
56
 
58
- Each format is sligthly different: YAML and JSON will simply include full library info, while text format includes resolved folder names, versions, and the download URL.
57
+ Note that `-f yaml` specifies the format of the 'lock' file (`Arlifile.<format>`). So in this case our `Arlifile.yaml` will contain all library details obtained from the central database in YAML format.
59
58
 
60
- #### CMake Integration
59
+ ### How Does It Work?
61
60
 
62
- The CMake lock file is meant to be consumed by projects relying on the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake). We are still working on the complete integration, which would hopefully allow the following features:
61
+ In a nutshell, Arli relies on the publicly available database of the vast majority of public Ardiuino libraries. This database is maintained by Arduino themselves, and is a [giant gzipped JSON file](http://downloads.arduino.cc/libraries/library_index.json.gz). Arli automatically downloads and caches the index on a local file system, and then lets you search and install libraries using either a simple name search, or more sophisticated ruby-like syntax that supports searching for ANY attribute as an equal match, or a regular expressions, or even a [Proc](http://ruby-doc.org/core-2.4.2/Proc.html).
63
62
 
64
- * auto-generate Arduino project with library dependencies using cmake
65
- * provide CMake plugin that runs `arli bundle -f cmake`, and reads the `Arlifile.lock.cmake`
66
- * this will auto-generate each Arduino library into it's own static library, and then link your project with them all.
63
+ Sometimes, however, an Arduino library you use may not part of the main database. No problem! Just add the `url:` attribute together with the library name to `Arlifile`. The URL can either be a Github URL, or a URL to a downloadable ZIP file. Arli will figure out the rest.
67
64
 
68
- **CMake Coming Soon!**
65
+ <a name="folder-detection"></a>
69
66
 
67
+ #### Automatic Folder Name Correction
70
68
 
71
- ### Single Library and `install`
69
+ Arli understands that the folder where the library is installed must be named correctly: in other words, **folder name must match the header file inside of the folder** for the library to be found.
72
70
 
73
- You can also install just a single library by using the `install` command, instead of the `bundle`. Install accepts either a `--lib-name` flag (`-n`), or a url `-u`, `--lib-url`, for example:
71
+ When Arli downloads libraries in ZIP format, they are unpacked into folder that are named differently. Arli will then search that folder for the source and header files. The name of the directory is then compared to the files found, and in some cases Arli will automatically **rename the library folder to match the main header file.**.
74
72
 
75
- ```bash
76
- arli install --lib-name 'Adafruit GFX Library'
77
- ```
73
+ > For example, 'Adafruit GFX Library' is the proper name of a corresponding library, and it's ZIP archive will unpack into a folder named `Adafruit_GFX_Library-1.4.3`. Arli will then detect that the header file inside the folder is `Adafruit_GFX.h`. In this case Arli will rename the top-level folder to `Adafruit_GFX`, and make the library valid, and its folder easily found.
78
74
 
79
- ## Gem Installation
75
+ ### Other Commands
80
76
 
81
- Install the `arli` ruby gem as follows:
77
+ Arli provides several additional commands, described in details down below.
82
78
 
83
- ```bash
84
- # if using rbenv, or rvm; otherwise you may need to prefix
85
- # with 'sudo'
86
- $ gem install arli
87
- ```
79
+ * You can [search](#search-command) the offical library using any attribute of the library tested against a string, or a regular expression, or even a Ruby Proc if you know how to write them.
80
+
81
+ * You can also install a single library with [install](#install-command), in which case there is no `Arlifile` or a lock file.
88
82
 
89
83
  ## Usage
90
84
 
@@ -95,6 +89,9 @@ Usage:
95
89
  arli options
96
90
  arli command [ options ]
97
91
 
92
+ -A, --print-attrs prints full list of available library
93
+ attributes that can be used in search strings.
94
+
98
95
  -C, --no-color Disable any color output.
99
96
  -D, --debug Print debugging info.
100
97
  -t, --trace Print exception stack traces.
@@ -110,26 +107,72 @@ Available Commands:
110
107
 
111
108
  See arli command --help for more information on a specific command.
112
109
 
113
- arli (0.8.2) © 2017 Konstantin Gredeskoul, MIT License.
110
+ arli (0.9.0) © 2017 Konstantin Gredeskoul, MIT License.
114
111
  ```
115
112
 
113
+ <a name="command-bundle"></a>
114
+
116
115
  ### Command `bundle`
117
116
 
118
- Use this command to install Arduino libraries.
117
+ Use this command to install Arduino libraries defined in the `Arlifile` yaml file.
118
+
119
+ ![](docs/arlifile.png)
119
120
 
120
- You can specify libraries in the `Arlifile` by providing just the `name:` (and posibly `version`) — the name must match exactly a library in the Arduino standard database. Alternatively, your can pass fields `archiveFileName`, `checksum` — which all uniquely identify a library in the database.
121
+ There are two main categories of libraries you will be installing:
122
+
123
+ 1. One of the officially registered in the [Arduino official library database](http://downloads.arduino.cc/libraries/library_index.json.gz), which is a giant gzipped JSON file. Arli will download and cache this file locally, and use it to find libraries.
124
+
125
+ 2. Using the `:url` field that links to either a remote ZIP file, or a Github Repo.
126
+
127
+ > When using the public database, which at the time of this writing contains 1220 unique libraries, spanning 4019 separate versions. when the remote file's size changes, will Arli automatically detects that by issuing a `HEAD` HTTP request, and after comparing the size to the locally cached version, it might decide to re-download it.
128
+ >
129
+ > Note that this functionality is provided by the "sister" Ruby gem called [`arduino-library`](https://github.com/kigster/arduino-library), which essentially provides most of the underlying library-specific functionality.
130
+
131
+
132
+ #### Installing from the Database
133
+
134
+ You can specify libraries by providing just the `name:` (and posibly `version`) — the name must match exactly a library in the Arduino standard
135
+
136
+ You can provide the following fields in the `Arilfile` if you want the library to be found in the Arduino Library database:
137
+
138
+ * `name` should be the exact match. Use double quotes if the name contains spaces.
139
+ * `version` can be used together with the `name` to specify a particular version. When `name` is provided without `version`, the latest version is used.
140
+ * `checksum` and `archiveFileName` can be used as they both uniquely identify a library.
141
+
142
+ #### Installing From a URL
121
143
 
122
144
  If a library you are using is not in the public database just provide its `name` and the `url` fields. The URL can either be a git URL, or a downloadable ZIP file. Arli will use the `url` field if it's available without trying to search for the library elsewhere.
123
145
 
124
- #### Automatic Folder Name Correction
146
+ ### Generated "lock" file — `Arlifile.<format>`
125
147
 
126
- Arli understands that the folder where the library is installed must be named correctly: in other words, **folder name must match the header file inside of the folder** for the library to be found.
148
+ Whenever `bundle` command succeeds, it will create a "lock" file in the same folder where the `Arlifile` file is located.
127
149
 
128
- When Arli downloads libraries in ZIP format, they are unpacked into folder that are named differently. Arli will then search that folder for the source and header files. The name of the directory is then compared to the files found, and in some cases Arli will automatically **rename the library folder to match the main header file.**.
150
+ The purpose of this file is to list in a machine-parseable way the *fully-resolved* installed library folders.
129
151
 
130
- > For example, 'Adafruit GFX Library' is the proper name of a corresponding library, and it's ZIP archive will unpack into a folder named `Adafruit_GFX_Library-1.4.3`. Arli will then detect that the header file inside the folder is `Adafruit_GFX.h`. In this case Arli will rename the top-level folder to `Adafruit_GFX`, and make the library valid, and its folder easily found.
131
- >
132
- > This is an audacious attempt to make sense of the chaos that is the Arduino Library world.
152
+ There are four lock file formats that are supported, and they can be passed in with the `-f format` eg `--format text` flags to the `bundle` command:
153
+
154
+ * `text`
155
+ * `json`
156
+ * `yaml`
157
+ * `cmake`
158
+
159
+ Each format produces a file `Arlifile.<format>`: YAML and JSON will simply include the complete library info received from the database, while text format includes a *resolved* library folder names, versions, and the download URL — all comma separated, one per line.
160
+
161
+ #### Experimental CMake Integration
162
+
163
+ The CMake format is currently [**work in progress**](https://github.com/kigster/arli-cmake).
164
+
165
+ The main goal is to create a CMake "include" file that can automatically build arli-installed libraries, add their locations to the `include_directories` so that the header files can be found.
166
+
167
+ > **Help Wanted!** Do you know CMake well? Help us design the CMake and arduino-cmake integration.
168
+
169
+ The CMake lock file is meant to be consumed by projects relying on the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake). We are still working on the complete integration, which would hopefully allow the following features:
170
+
171
+ * auto-generate a new Arduino project with the library dependencies using [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake) as the underlying build tool.
172
+
173
+ * Optionally, provide a CMake plugin that runs `arli bundle -f cmake`, and reads the `Arlifile.cmake`. That file will contain CMake code to build each dependent library separately as a static library, and then link it to the firmware in the end.
174
+
175
+ **CMake Coming Soon!**
133
176
 
134
177
  #### An Example
135
178
 
@@ -138,6 +181,8 @@ Here is the `arli bundle` command inside CMake-based project to build a [Wall Cl
138
181
  ```yaml
139
182
  # vi:syntax=yaml
140
183
  ---
184
+ libraries_path: ./libs
185
+ lock_format: cmake
141
186
  dependencies:
142
187
  - name: "Adafruit GFX Library"
143
188
  version: '1.2.0'
@@ -155,20 +200,19 @@ You can see that most libraries are specified by name, except one (SimpleTimer)
155
200
 
156
201
  So let's specify where our libraries live, and run `arli bundle` inside that project. Below is a screenshot of running `arli` inside of the Wall Clock Arduino project:
157
202
 
158
-
159
203
  Below is the complete help for the `bundle` command for reference:
160
204
 
161
-
162
- ```bash
205
+ ```
163
206
  ❯ arli bundle -h
164
207
  Description:
165
208
  Installs all libraries specified in Arlifile
166
209
 
167
- This command reads Arlifile (from the current folder, by default),
168
- and then it installs all dependent libraries specified there, checking if
169
- each already exists, and if not — downloading them, and installing them into
170
- your Arduino Library folder. Both the folder with the Arlifile, as well as the
171
- destination library path folder can be changed with the command line flags.
210
+ This command reads Arlifile (from the current
211
+ folder, by default), and then it installs all dependent libraries
212
+ specified there, checking if each already exists, and if not —
213
+ downloading them, and installing them into your Arduino Library
214
+ folder. Both the folder with the Arlifile, as well as the destination
215
+ library path folder can be changed with the command line flags.
172
216
 
173
217
  Usage:
174
218
  arli bundle [options]
@@ -196,14 +240,11 @@ Options
196
240
  -V, --version Print current version and exit
197
241
  -h, --help prints this help
198
242
 
199
- Examples:
200
- # Install all libs defined in Arlifile:
201
- arli bundle
202
-
203
- # Custom Arlifile location, and destination path:
204
- arli bundle -a ./src -l ./libraries
243
+ arli (0.9.0) © 2017 Konstantin Gredeskoul, MIT License.
205
244
  ```
206
245
 
246
+ <a name="command-install"></a>
247
+
207
248
  ### Command `install`
208
249
 
209
250
  Use this command to install a single library by either a name or URL:
@@ -211,25 +252,26 @@ Use this command to install a single library by either a name or URL:
211
252
  Eg:
212
253
 
213
254
  ```bash
214
- be exe/arli install -n 'Adafruit GFX Library' -l ./libs
215
- be exe/arli install -u 'https://github.com/jfturcot/SimpleTimer' -l ./libs
255
+ ❯ arli install 'Adafruit GFX Library' -l ./libs
256
+ ❯ arli install 'https://github.com/jfturcot/SimpleTimer'
216
257
  ```
217
258
 
218
259
  Complete help is:
219
260
 
220
-
221
261
  ```bash
222
262
  ❯ arli install -h
223
263
  Description:
224
264
  Installs a single library either by searching, or url or local ZIP
225
265
 
226
- This command installs a single library into your library path
227
- using the third argument to the command arli install
228
- which can be a library name, local ZIP file, or a remote URL
229
- (either ZIP or Git Repo)
266
+ This command installs a single library into your library path (which
267
+ can be set with --lib-path flag). Arli interpretes the
268
+ third argument to arli install as either an exact
269
+ library name, or a remote URL (either ZIP or Git Repo). You can use
270
+ search command to first find the right library
271
+ name, and then pass it to the install command.
230
272
 
231
273
  Usage:
232
- arli install [ "library name" | url | local-zip ] [options]
274
+ arli install [ "Exact Library Name" | url ] [options]
233
275
 
234
276
  Options
235
277
  -l, --lib-path PATH Destination: typically your Arduino libraries folder
@@ -248,15 +290,13 @@ Options
248
290
  -h, --help prints this help
249
291
 
250
292
  Examples:
251
- # Install the latest version of this library
252
- arli install "Adafruit GFX Library"
293
+ # Install the latest version of this library locally
294
+ arli install "Adafruit GFX Library" -l ./libraries
253
295
 
254
296
  # Install the library from a Github URL
255
- arli install https://github.com/jfturcot/SimpleTimer
297
+ arli install https://github.com/jfturcot/SimpleTimer```
256
298
 
257
- # Install a local ZIP file
258
- arli install ~/Downloads/DHT-Library.zip
259
- ```
299
+ <a name="command-search"></a>
260
300
 
261
301
  ### Command `search`
262
302
 
@@ -269,58 +309,126 @@ You can search in two ways:
269
309
 
270
310
  `arli search AudioZero` does a simple search by name, and would match any library with 'AudioZero' in the name, such as `AudioZeroUpdated`. This search returns three results sorted by the version number:
271
311
 
272
- ```bash
312
+ ```
273
313
  ❯ arli search AudioZero
274
- AudioZero (1.0.0), by Arduino
275
- AudioZero (1.0.1), by Arduino
276
- AudioZero (1.1.1), by Arduino
277
314
 
278
- Total matches: 3
315
+ --------------------------------------------------------------------------------
316
+ Arli (0.8.4), Command: search
317
+ Library Path: ~/Documents/Arduino/Libraries
318
+ --------------------------------------------------------------------------------
319
+
320
+ AudioZero (1.1.1) ( 3 total versions )
321
+
322
+ ———————————————————————
323
+ Total Versions : 3
324
+ Unique Libraries : 1
325
+ ———————————————————————
279
326
  ```
280
327
 
281
328
  The search argument can also be a ruby-syntaxed expression, that (if you know ruby) is actually `eval`-ed into the method parameters. Here are a few examples:
282
329
 
283
330
  You can also use regular expressions, and set maximum number of results printed by the `-m MAX` flag.
284
331
 
285
- ```bash
286
- ❯ arli search 'name: /adafruit/i' -m 0
287
- Adafruit ADS1X15 (1.0.0), by Adafruit
288
- Adafruit ADXL345 (1.0.0), by Adafruit
289
- Adafruit AM2315 (1.0.0), by Adafruit
290
- Adafruit AM2315 (1.0.1), by Adafruit
291
- .....
292
- WEMOS Matrix Compatible With Adafruit GFX Library (1.0.0), by Thomas O Fredericks
293
- WEMOS Matrix Compatible With Adafruit GFX Library (1.1.0), by Thomas O Fredericks
294
- Adafruit SGP30 Sensor (1.0.0), by Adafruit
295
-
296
- Total matches: 352
297
332
  ```
333
+ ❯ arli search 'name: /adafruit/i'
334
+
335
+ --------------------------------------------------------------------------------
336
+ Arli (0.8.4), Command: search
337
+ Library Path: ~/Documents/Arduino/Libraries
338
+ --------------------------------------------------------------------------------
339
+
340
+ Adafruit ADS1X15 (1.0.0) ( 1 total versions )
341
+ Adafruit ADXL345 (1.0.0) ( 1 total versions )
342
+ Adafruit AHRS (1.1.3) ( 5 total versions )
343
+ Adafruit AM2315 (1.0.1) ( 2 total versions )
344
+ Adafruit AMG88xx Library (1.0.0) ( 1 total versions )
345
+ ......
346
+ dafruit WS2801 Library (1.0.0) ( 1 total versions )
347
+ Adafruit microbit Library (1.0.0) ( 1 total versions )
348
+ Adafruit nRF8001 (1.1.1) ( 2 total versions )
349
+ Adafruit seesaw Library (1.0.1) ( 2 total versions )
350
+ Adafruit_VL53L0X (1.0.2) ( 2 total versions )
351
+ Adafruit_VL6180X (1.0.2) ( 2 total versions )
352
+ Adafruit_mp3 (1.0.1) ( 2 total versions )
353
+ WEMOS Matrix Compatible With Adafruit GFX (1.2.0) ( 3 total versions )
354
+ ———————————————————————
355
+ Total Versions : 355
356
+ Unique Libraries : 116
357
+ ———————————————————————
358
+ ```
359
+
360
+ Finally, you can change the output format of the search, by passing `-f <format>`, where `format` can be `short` (the default), `long`, `json`, or `yaml`.
298
361
 
299
- With `-m 0` flag, we disabled the default search limit of 100, and got all of the libraries that have the word "adafruit" in their name. We could have used `version:`, or `author`, or `website`, or even `url` and `archiveFileName` fields. For complete description of available library attributes, please see the official definition of the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file.
362
+ For example, here is a how long format looks like:
363
+
364
+ ```
365
+ ❯ arli search 'name: /adafruit/i' -f long
366
+
367
+ --------------------------------------------------------------------------------
368
+ Arli (0.8.4), Command: search
369
+ Library Path: ~/Documents/Arduino/Libraries
370
+ --------------------------------------------------------------------------------
371
+ _______________________________________________________________
372
+ Name: Adafruit ADS1X15
373
+ Versions: 1.0.0,
374
+ Author(s): Adafruit
375
+ Website: https://github.com/adafruit/Adafruit_ADS1X15
376
+ Sentence: Driver for TI's ADS1015: 12-bit Differential or
377
+ Single-Ended ADC with PGA and Comparator
378
+ _______________________________________________________________
379
+ Name: Adafruit ADXL345
380
+ Versions: 1.0.0,
381
+ Author(s): Adafruit
382
+ Website: https://github.com/adafruit/Adafruit_ADXL345
383
+ Sentence: Unified driver for the ADXL345 Accelerometer
384
+ _______________________________________________________________
385
+ Name: Adafruit AHRS
386
+ Versions: 1.1.3, 1.1.2, 1.1.0, 1.0.2, 1.0.0
387
+ Author(s): Adafruit
388
+ Website: https://github.com/adafruit/Adafruit_AHRS
389
+ Sentence: AHRS (Altitude and Heading Reference System) for Adafruit's
390
+ 9DOF and 10DOF breakouts
391
+ _______________________________________________________________
392
+ ```
393
+
394
+
395
+ With `-m LIMIT` flag you can limit number of results. But in our cas above we printed all libraries that had the word "adafruit" (case insensitively) in their official name. We could have used `version:`, or `author`, or `website`, or even `url` and `archiveFileName` fields. For complete description of available library attributes, please see the official definition of the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file.
300
396
 
301
397
  A detailed description of the complete search functionality is documented in the library that provides it — [arduino-library](https://github.com/kigster/arduino-library#using-search). Arli uses `arduino-library` gem behind the scenes to search, and lookup libraries.
302
398
 
303
399
  Below is the help screen for the search command:
304
400
 
305
- ```bash
401
+ ```
306
402
  ❯ arli search -h
307
403
  Description:
308
404
  Search standard Arduino Library Database with over 4K entries
309
405
 
310
- This command provides both the simple name-based search interface,
311
- and the most sophisticated field-by-field search using a downloaded,
312
- and locally cached Public Arduino Database JSON file, maintained
313
- by Arduino and the Community. If you know of another database,
314
- that's what the --database flag is for.
406
+ This command provides both the simple name-based search interface, and
407
+ the most sophisticated attribute-specific search using a downloaded,
408
+ and locally cached Public Arduino Database JSON file, maintained by
409
+ the Arduino Community. If you know of another database, that's what
410
+ the --database flag is for. Note that you can print the
411
+ list of available attributes by running arli with
412
+ --print-attrs flag.
315
413
 
316
414
  Usage:
317
- arli search [ name | search-expression ] [options]
415
+ arli search [ -A | search-expression ] [options]
318
416
 
319
417
  Options
320
418
  -d, --database URL a JSON(.gz) file path or a URL of the library database.
321
419
  Defaults to the Arduino-maintained database.
322
- -m, --max NUMBER if provided, limits the result set to this number
323
- Set to 0 to disable. Default is 100.
420
+
421
+ -m, --max NUMBER if provided, limits the result set using the
422
+ total number of the unique library name matches.
423
+ Default is 0, which means no limit.
424
+
425
+ -f, --format FMT Optional format of the search results.
426
+ The default is short. Available
427
+ formats: with_versions, long, short, json, yaml
428
+
429
+ -A, --print-attrs prints full list of available library
430
+ attributes that can be used in search strings.
431
+
324
432
  -C, --no-color Disable any color output.
325
433
  -D, --debug Print debugging info.
326
434
  -t, --trace Print exception stack traces.
@@ -330,20 +438,23 @@ Options
330
438
  -h, --help prints this help
331
439
 
332
440
  Examples:
333
- # Search using the regular expression containing the name:
334
- arli search AudioZero
441
+ # Finds any library with name matching a given string, case insensitively
442
+ arli search audiozero
443
+
444
+ # If the first character is "/", then the argument is assumed to be regex
445
+ arli search /AudioZero$/
335
446
 
336
- # Same exact search as above, but using ruby hash syntax:
337
- arli search 'name: /AudioZero/'
447
+ # If the first character is "=", then the rest is assumed to be exact name
448
+ arli search =Time
338
449
 
339
- # Lets get a particular version of the library
340
- arli search 'name: "AudioZero", version: "1.0,2"'
450
+ # Lets get a particular version of the library using another attribute
451
+ arli search 'name: "AudioZero", version: "1.0.2"'
341
452
 
342
- # Search using case insensitive name search, and :
343
- arli search 'name: /adafruit/i'
453
+ # Search using case insensitive search for the author
454
+ arli search 'author: /adafruit/i'
344
455
 
345
- # Finally, search for the exact name match:
346
- arli search '^Time$'
456
+ # Finally, search for regex match for "WiFi" in a sentence or a paragraph
457
+ arli search 'sentence: /wifi/i, paragraph: /wifi/i'
347
458
  ```
348
459
 
349
460