mac-wifi 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2bce9a95ee880536f6e3672191ed7d343b1eafcf
-  data.tar.gz: 10aeeddeb2bc4bf946a65d9709b2306ea8567ed9
+SHA256:
+  metadata.gz: 033044a27585d2cb3a3e4920879921e77d91b661021c054118ff273c24386df0
+  data.tar.gz: 23cf93fcfb0dfef2130347c84fd53f78cc84a1a4b5cd54a7e0d864704aa60027
 SHA512:
-  metadata.gz: 04224a7842e14437d0de854e6bc9566901893c547b73e4ca581b159d92816bf789d3235919b8593fdf74b32e9cfebfe7c14f7974498a268117eafeb37a0eb785
-  data.tar.gz: 5b8db8d42cb1b0284dc61d0557030ffa49f2bc3987f8272ccef93fa23d40be2553346635a9f996941a7fa2f2f19f351687c0fb2855203f6f2c8da5a5493c07b3
+  metadata.gz: ff355af46081bf8377ad2347a6052f9387fe8ae0940c25e74da67bfc654f8c1cfe866a7e19ae8d1628ab108e7250f5b7f51a8bd3222129abcf32db6de0ccdfed
+  data.tar.gz: f2a4e67ebba29752fa85caf06f81fdc633c54af2bde9ccea34df4e5fa13e913bf9b6dadab7f1b7b2d47d81ba65e4097e881b5b740b1008918ba417d1a6cac8a6

data/README.md

@@ -1,20 +1,24 @@
 # mac-wifi
 
-The `mac-wifi` script installed by this gem (or otherwise copied) enables the query and management of wifi configuration and environment on a Mac.
-The code encapsulates the Mac OS specific logic in a minimal class to more easily add support for other operating systems,
+To install this software, run:
+
+`gem install mac-wifi`
+
+or, you may need to precede that command with `sudo`:
+
+`sudo gem install mac-wifi`
+
+The `mac-wifi` script installed by this gem enables the query and management 
+of wifi configuration and environment on a Mac.
+The code encapsulates the Mac OS specific logic in a minimal class 
+to more easily add support for other operating systems,
 but as of now, only Mac OS is supported. (Feel free to add an OS!)
 
-It can be run in single-command or interactive mode. Interactive mode uses the [pry](https://github.com/pry/pry) gem,
+It can be run in single-command or interactive mode. 
+Interactive mode uses the [pry](https://github.com/pry/pry) gem,
 providing an interface familiar to Rubyists and other 
 [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) users.
 
-It is not necessary to download this repo or even install this gem; the `bin/mac-wifi` 
-script file is all you need to run the application. There are many ways to install it
-in this way; one way is by changing into the directory
-where you would like to save the script, and running:
-
-`curl -o mac-wifi https://raw.githubusercontent.com/keithrbennett/macwifi/master/exe/mac-wifi && chmod +x mac-wifi`
-
 
 ### Usage
 
@@ -24,7 +28,7 @@ output at the time of this writing:
 ```
 $ mac-wifi h
 
-Command Line Switches:                    [mac-wifi version 2.0.0]
+Command Line Switches:                    [mac-wifi version 2.1.0]
 
 -o[i,j,p,y]               - outputs data in inspect, JSON, puts, or YAML format when not in shell mode
 -s                        - run in shell mode
@@ -47,17 +51,17 @@ pa[ssword] network-name   - password for preferred network-name
 pr[ef_nets]               - preferred (not necessarily available) networks
 q[uit]                    - exits this program (interactive shell mode only) (see also 'x')
 r[m_pref_nets] network-name - removes network-name from the preferred networks list
-                            (can provide multiple names separated by spaces)
+                          (can provide multiple names separated by spaces)
 s[hell]                   - opens an interactive pry shell (command line only)
 t[ill]                    - returns when the desired Internet connection state is true. Options:
-                            1) 'on'/:on, 'off'/:off, 'conn'/:conn, or 'disc'/:disc
-                            2) wait interval, in seconds (optional, defaults to 0.5 seconds)
+                          1) 'on'/:on, 'off'/:off, 'conn'/:conn, or 'disc'/:disc
+                          2) wait interval, in seconds (optional, defaults to 0.5 seconds)
 w[ifion]                  - is the wifi on?
 x[it]                     - exits this program (interactive shell mode only) (see also 'q')
 
 When in interactive shell mode:
-    * use quotes for string parameters such as method names.
-    * for pry commands, use prefix `%`.
+  * use quotes for string parameters such as method names.
+  * for pry commands, use prefix `%`.
 ```
 
 Internally, it uses several Mac command line utilities. This is not ideal,
@@ -79,16 +83,17 @@ You may need to precede this command with `sudo `, especially if you are using t
 version of Ruby that comes packaged with MacOS.
 
 
-### JSON and YAML Output
+### JSON, YAML, and Other Output Formats
 
-You can specify that output in _noninteractive_ mode be in JSON or YAML formats
-by specifying `-j` or `-y` on the command line, respectively.
+You can specify that output in _noninteractive_ mode be in a certain format.
+Currently, JSON, YAML, inspect, and puts formats are supported.
+See the help for which command line switches to use.
 
 
 ### Seeing the Underlying OS Commands and Output
 
 If you would like to see the Mac OS commands and their output, 
-you can do so by specifying "-v" on the command line.
+you can do so by specifying "-v" (for _verbose) on the command line.
 
 You may notice that some commands are executed more than once. This is to simplify the application logic
 and eliminate the need for the complexity of balancing the speed that a cache offers and the risk
@@ -120,15 +125,16 @@ mac-wifi till conn && \
 say -v Kyoko "Connected to my network."
 ```
 
-(The `say` command supports all kinds of accents that are fun to play around with.
+(The Mac OS `say` command supports all kinds of accents that are fun to play around with.
 You can get a list of all of them by running `say -v "?"`)
 
+
 ### Using the Shell
 
-**If the program immediately exits when you try to run the shell, try upgrading `pry` and `pry-byebug`.
-This can be done by running `gem install pry; gem install pry-byebug`.**
+_If the program immediately exits when you try to run the shell, try upgrading `pry` and `pry-byebug`.
+This can be done by running `gem install pry; gem install pry-byebug`._
 
-The shell, invoked with the `s` command on the command line, provides an interactive
+The shell, invoked with the `-s` switch on the command line, provides an interactive
 session. It can be useful when:
 
 * you want to issue multiple commands
@@ -136,7 +142,7 @@ session. It can be useful when:
 * you want the data in a format not provided by this application
 * you want to incorporate these commands into other Ruby code interactively
 * you want to combine the results of commands with other OS commands 
-  (you can shell out to run other command line programs by preceding the command with a period (`.`).
+  (you can shell out to run other command line programs by preceding the command with a period (`.`))   .
 
 
 ### Using Variables in the Shell
@@ -185,20 +191,20 @@ the result may be mysterious.  For example, if I were write the wifi information
 to a file, this would work:
 
 ```
-[1] pry(#<MacWifiView>)> File.write('x.txt', info)
+[1] pry(#<MacWifiView>)> File.write('x', info)
 => 431
 ```
 
-However, if I forget to quote the filename:
+However, if I forget to quote the filename, the program exits:
 
 ```
-[2] pry(#<MacWifiView>)> File.write(x.txt, info)
+[2] pry(#<MacWifiView>)> File.write(x, info)
 ➜  mac-wifi git:(master) ✗  
 ```
 
-What happened? `x.txt` was assumed by Ruby to be a method name.
-`method_missing` was called, and since `x.txt` starts with `x`,
-the exit method was called, exiting the program.
+What happened? `x` was assumed by Ruby to be a method name.
+`method_missing` was called, and since `x` is the exit
+command, the program exited.
 
 Bottom line is, be careful to quote your strings, and you're probably better off using 
 constants or instance variables if you want to create variables in your shell. 
@@ -223,8 +229,10 @@ mac-wifi t on && say "Internet connected" # Play audible message when Internet b
 #### Interactive Shell Commands
 
 When in shell mode, commands generally return the target object (e.g. the array of
-available networks) rather than outputting a nicely formatted string. This may result
-in the shell outputting that returned value in an ugly way.
+available networks) rather than outputting a nicely formatted string. 
+This is intentional, so that you can compose expressions and in general
+have maximum flexibility. The result may be that `pry` displays 
+that returned value in an ugly way.
 
 If you don't need the return value but just want to display the value nicely,
 you can use the `fancy_puts` method to output it nicely. An alias `fp` has been
@@ -239,17 +247,34 @@ provided for your convenience. You're welcome!  For example:
 ]
 ```
 
-If you want to surpress output altogether (e.g. if you are using the value in an
-expression and don't need to print it out, you can simply append `;nil` to the expression
-and that will be value output to the console. For example:
+For best display results, be sure `awesome_print` is `gem install`ed.
+The program will silently use a not-as-nice formatter without it.
+(This silence is intentional, so that users who don't want to install
+`awesome-print` will not be bothered.)
+
+If you want to suppress output altogether (e.g. if you are using the value in an
+expression and don't need to see it displayed,
+you can simply append `;nil` to the expression
+and `nil` will be value output to the console. For example:
 
 ```
 [10] pry(#<MacWifi::CommandLineInterface>)> available_networks = avail_nets; nil
 => nil
-[11] pry(#<MacWifi::CommandLineInterface>)> avail_nets.size
-=> 32
 ```
 
+#### Using the Models Without the Command Line Interface
+
+The code has been structured so that you can call the models
+from your own Ruby code, bypassing the command line interface.
+Here is an example of how to do that:
+
+```ruby
+require 'mac-wifi'
+model = MacWifi::MacOsModel.new
+puts model.available_network_names.to_yaml # etc...
+```
+
+
 **More Examples**
 
 (For brevity, semicolons are used here to put multiple commands on one line, 
@@ -296,27 +321,9 @@ Connected!
 ```
 
 
-### Distribution, or Why All The Code is in One Humongous File
-
-This code would be neater and easier to read if each class were in a file of its own.
-The reason everything is in one file is to simplify distribution for some users.
-Although installation as a gem is simple, being able to download a single file may work better when:
+### Dependent Gems
 
-* the user wants to install the script once, rather than once per Ruby version and/or gemset.
-* the user needs or wants to specify the exact location of the script (e.g. `~/bin`),
-and/or does not want it buried in the gem directory tree (e.g. `/Users/kbennett/.rvm/gems/ruby-2.4.0/bin/mac-wifi`).
-* the user is not familiar with Ruby and does not want to use the `gem` command
-* the user is concerned about security and would prefer to install a single file to a known location
-rather than run the gem installation
-* installing gems is controlled by the user's organization, and getting authorization is not practical
-* installing gems requires root access, and the user does not have root access
-
-That said, installation as a gem is highly recommended, since:
-
-* this will greatly simplify acquiring future fixes and enhancements
-* if the user wants to use the shell mode, they will need to `gem install pry` anyway
-
-Currently, the only gems used by the program are:
+Currently, the only gems used directly by the program are:
 
 * `pry`, to provide the interactive shell
 * `awesome_print` (optional), to more nicely format output in non-interactive mode
@@ -324,6 +331,7 @@ Currently, the only gems used by the program are:
 So the user can avoid installing gems altogether as long as they don't need to use the interactive shell,
 and as long as they are comfortable with the less pretty output.
 
+
 ### Password Lookup Oddity
 
 You may find it odd (I did, anyway) that even if you issue the password command 
@@ -352,4 +360,4 @@ MIT License (see LICENSE.txt)
 
 I am available for consulting, development, tutoring, training, troubleshooting, etc.
 
-You can contact me via GMail, Twitter, and Github as _keithrbennett_.
+You can contact me via GMail, Twitter, Github, and LinkedIn, as _keithrbennett_.

data/RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+## v2.1.0
+
+* Support for the single script file install has been dropped. It was requiring too much complexity,
+and was problematic with Ruby implementations lacking GEM_HOME / GEM_PATH environment variables.
+* Code was broken out of the single script file into class files, plus a `version.rb`
+and `mac-wifi.rb` file.
+
+
 ## v2.0.0
 
 * Support output formats in batch mode: JSON, YAML, puts, and inspect modes.