mac-wifi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5763b7c0bc11d558c50e82e2e7fd52ba6bd5e3cb
+  data.tar.gz: 29878b297569049bff109647d9583ad6afad5a65
+SHA512:
+  metadata.gz: 5c70472f1d31785cae9a124ef5641f1157eb63549267c97773f120e4ce033588faad198bfded7f56ddb8e2eb8fbbeaae0d1ed31e20ddceaf5d0c7bd00140f8a6
+  data.tar.gz: 32007be9ff30e8fd38996ba433386a29ee11193c868d1b37afb1bc534e11c93173c9658a116bbc66d95692a26809b8864d7a78f1e8f1d28426e3c393ba223e9b

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea/
+

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in mac-wifi-2.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2017 Keith Bennett
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,261 @@
+# mac-wifi
+
+This script enables the query and management of wifi configuration and environment on a Mac.
+
+It can be run in single-command or interactive mode. Interactive mode uses the `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; this script file is all you need to run the application.
+
+### Usage
+
+Available commands can be seen by using the `h` (or `help`) option. Here is its
+output at the time of this writing:
+
+```
+➜  mac-wifi git:(master) ✗   ./mac-wifi h
+
+Available commands are:
+
+ci                      - connected to Internet (not just wifi on)?
+co[nnect] network-name  - turns wifi on, connects to network-name
+cy[cle]                 - turns wifi off, then on, preserving network selection
+d[isconnect]            - disconnects from current network, does not turn off wifi
+h[elp]                  - prints this help
+i[nfo]                  - prints wifi-related information
+lsp[referred]           - lists preferred (not necessarily available) networks
+lsa[vailable]           - lists available networks
+n[etwork_name]          - name (SSID) of currently connected network
+on                      - turns wifi on
+of[f]                   - turns wifi off
+pa[ssword] network-name - shows password for preferred network-name
+q[uit]                  - exits this program (interactive shell mode only)
+r[m] network-name       - removes network-name from the preferred networks list
+s[hell]                 - opens an interactive pry shell (command line only)
+t[ill]                  - (experimental!) returns when the desired Internet connection state is true. Options:
+                          'on'/:on or 'off'/:off
+                          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)
+
+When in interactive shell mode:
+    * 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,
+I would have preferred OS system calls, but the current approach enabled me to develop
+this script quickly and simply.
+
+### Pretty Output
+
+For nicely formatted output of the `info` command in non-interactive mode,
+the `awesome_print` gem is used if it is installed;
+otherwise, the somewhat less awesome pretty print (`pp`) is used.  Therefore,
+installation of the `awesome_print` gem is recommended. 
+This is accomplished by the following command:
+
+`gem install awesome_print`
+
+
+### 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 setting the
+environment variable MAC_WIFI_OPTS to include `-v` (for _verbose_).
+This can be done in the following ways:
+
+```
+export MAC_WIFI_OPTS=-v
+./mac-wifi i
+```
+
+```
+MAC_WIFI_OPTS=-v  ./mac-wifi i
+```
+
+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
+of stale data.
+
+
+### Troubleshooting
+
+If you try to run the shell, the script will require the `pry` gem, so that will need to be installed.
+`pry` in turn requires access to a `readline` library. If you encounter an error relating to finding a
+`readline` library, this can be fixed by installing the `pry-coolline` gem: `gem install pry-coolline`.
+If you are using the Ruby packaged with Mac OS, or for some other reason require root access to install
+gems, you will need to precede those commands with `sudo`:
+
+```
+sudo gem install pry
+sudo gem install pry-coolline
+```
+
+
+### Using the Shell
+
+The shell, invoked with the `s` command on the command line, provides an interactive
+session. It can be useful when:
+
+* you want to issue multiple commands
+* you want to combine commands
+* 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 (`.`).
+
+### Using Variables in the Shell
+
+There are a couple of things (that may be surprising) to keep in mind
+when using the shell. They relate to the fact that local variables
+and method calls use the same notation in Ruby (use of parentheses
+in a method call is optional):
+
+1) In Ruby, when both a method and a local variable have the same name,
+the local variable will override the method name. Therefore, local variables
+may override this app's commands.  For example:
+
+```
+[1] pry(#<MacWifiView>)> n  # network_name command
+=> ".@ AIS SUPER WiFi"
+[2] pry(#<MacWifiView>)> n = 123  # override it with a local variable
+=> 123
+[3] pry(#<MacWifiView>)> n  # 'n' no longer calls the method
+=> 123
+[4] pry(#<MacWifiView>)> ne  # but any other name starting with 'ne' will still call the method
+=> ".@ AIS SUPER WiFi"
+[5] pry(#<MacWifiView>)> network_name
+=> ".@ AIS SUPER WiFi"
+[6] pry(#<MacWifiView>)> ne_xzy123
+=> ".@ AIS SUPER WiFi"
+``` 
+
+If you don't want to deal with this, you could use global variables, instance variables,
+or constants, which will _not_ hide the methods:
+
+```
+[7] pry(#<MacWifiView>)> N = 123
+[8] pry(#<MacWifiView>)> @n = 456
+[9] pry(#<MacWifiView>)> $n = 789
+[10] pry(#<MacWifiView>)> puts n, N, @n, $n
+.@ AIS SUPER WiFi
+123
+456
+789
+=> nil
+```
+
+2) If you accidentally refer to a nonexistent variable or method name,
+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)
+=> 431
+```
+
+However, if I forget to quote the filename:
+
+```
+[2] pry(#<MacWifiView>)> File.write(x.txt, 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.
+
+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. 
+
+
+
+### Examples
+
+#### Single Command Invocations
+
+```
+mac-wifi i            # prints out wifi info
+mac-wifi lsa          # prints available networks
+mac-wifi lsp          # prints preferred networks
+mac-wifi cy           # cycles the wifi off and on
+mac-wifi co a-network a-password # connects to a network requiring a password
+mac-wifi co a-network            # connects to a network _not_ requiring a password
+mac-wifi t on && say "Internet connected" # Play audible message when Internet becomes connected
+```
+
+#### Interactive Shell Commands
+
+(For brevity, semicolons are used here to put multiple commands on one line, 
+but these commands could also each be specified on a line of its own.)
+
+```
+# Print out wifi info:
+i
+
+# Cycle (off/on) the network then connect to the specified network not requiring a password
+> cycle; connect 'my-network'
+
+# Cycle (off/on) the network, then connect to the same network not requiring a password
+> @name = network_name; cycle; connect @name
+
+# Cycle (off/on) the network then connect to the specified network using the specified password
+> cycle; connect 'my-network', 'my-password'
+
+> @i = i; puts "You are connected on port #{@i[:port]} to #{@i[:network]} on IP address #{@i[:ip_address]}."
+You are connected on port en0 to .@ AIS SUPER WiFi on IP address 172.27.145.225.
+
+> puts "There are #{lsp.size} preferred networks."
+There are 341 preferred networks.
+
+# Delete all preferred networks whose names begin with "TOTTGUEST":
+> lsp.grep(/^TOTTGUEST/).each { |n| puts "Deleting preferred network #{n}."; rm(n) }
+
+# Define a method to wait for the Internet connection to be active.
+# (This functionality is included in the `till` command.)
+# Call it, then output celebration message:
+[17] pry(#<MacWifiView>)> def wait_for_internet; loop do; break if ci; sleep 0.5; end; end
+[18] pry(#<MacWifiView>)> wait_for_internet; puts "Connected!"
+Connected!
+
+# Same, but using a lambda instead of a method so we can use a variable name
+# and not need to worry about method name collision:
+@wait_for_internet = -> { loop do; break if ci; sleep 0.5; end }
+@wait_for_internet.() ; puts "Connected!"
+Connected!
+```
+
+### Cautions
+
+If the wifi networking changes from on to off while `till(:off)` is waiting,
+the program will hang indefinitely. I am currently looking into this problem.
+It also happens outside of this program; you can reproduce it by running `curl`,
+preferably on a longer running request, then turning off your wifi. This is pretty
+serious, and I'm considering removing the `:off` option from the `till` command.
+
+
+
+### Password Lookup Oddity
+
+You may find it odd (I did, anyway) that even if you issue the password command 
+(`mac_wifi pa a-network-name`) using sudo, you will still be prompted 
+with a graphical dialog for both a user id and password. This is no doubt
+for better security, but it's unfortunate in that it makes it impossible to fully automate this task.
+
+In particular, it would be nice for the `cycle` command to be able to reconnect to the original
+network after turning the network on. This is not possible where that network required a password.
+If you don't mind storing the network password in plain text somewhere, then you could easily
+automate it (e.g. `mac-wifi cycle && mac-wifi connect a-network a-password`).
+
+
+### License
+
+MIT License (see LICENSE.txt)
+
+### Shameless Ad
+
+I am available for consulting, development, tutoring, training, troubleshooting, etc.
+
+You can contact me via GMail, Twitter, and Github as _keithrbennett_.

data/bin/mac-wifi

@@ -0,0 +1,771 @@
+#!/usr/bin/env ruby
+
+# This script brings together several useful wifi-related functions.
+#
+# It is a bit of a kludge in that it calls Mac OS commands and uses
+# the text output for its data. At some point I would like to replace
+# that with system calls. Currently this script can break if Apple
+# decides to modify the name, options, behavior, and/or format of its utilities.
+#
+# What would be *really* nice, would be for Apple to retrofit all
+# system commands to optionally output JSON and/or YAML. Some offer XML, but that
+# is not convenient to use.
+#
+# Mac OS commands currently used are: airport, ipconfig, networksetup, security.
+#
+# Author: keithrbennett (on Github, GMail, Twitter)
+# I am available for Ruby development, troubleshooting, training, tutoring, etc.
+#
+# License: MIT License
+
+
+
+require 'shellwords'
+require 'tempfile'
+
+module MacWifi
+
+# This version must be kept in sync with the version in the gemspec file.
+VERSION = '0.0.1'
+
+class Model
+
+  AIRPORT_CMD = '/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport'
+
+
+  def initialize(verbose = false)
+    @verbose_mode = verbose
+  end
+
+
+  def connected_to_internet_curl_unused?
+
+    connected = false
+
+    begin
+      run_os_command('curl --silent --head http://www.google.com/')
+      connected = true
+    rescue OsCommandError => e
+      if e.exitstatus == 6
+        connected = false
+      else
+        raise
+      end
+    end
+    connected
+  end
+
+
+  # This method returns whether or not there is a working Internet connection.
+  # Because of a Mac issue which causes a request to hang if the network is turned
+  # off during its lifetime, we give it only 5 seconds per try,
+  # and limit the number of tries to 3.
+  def connected_to_internet?
+
+    tempfile = Tempfile.open('mac-wifi-')
+
+    begin
+      start_status_script = -> do
+        script = "curl --silent --head http://www.google.com/ > /dev/null ; echo $? > #{tempfile.path} &"
+        pid = Process.spawn(script)
+        Process.detach(pid)
+        pid
+      end
+
+      process_is_running = ->(pid) do
+        script = %Q{ps -p #{pid} > /dev/null; echo $?}
+        output = `#{script}`.chomp
+        output == "0"
+      end
+
+      get_connected_state_from_curl = -> do
+        tempfile.close
+        File.read(tempfile.path).chomp == '0'
+      end
+
+      # Do one run, iterating during the timeout period to see if the command has completed
+      do_one_run = -> do
+        end_time = Time.now + 3
+        pid = start_status_script.()
+        while Time.now < end_time
+          if process_is_running.(pid)
+            sleep 0.5
+          else
+            return get_connected_state_from_curl.()
+          end
+        end
+        Process.kill('KILL', pid)
+        :hung
+      end
+
+      3.times do
+        connected = do_one_run.()
+        return connected if connected != :hung
+      end
+
+      raise "Could not determine Internet status."
+
+    ensure
+      tempfile.unlink
+    end
+
+  end
+
+  # This implementation often hangs when wifi is turned off while curl is active
+  # def connected_to_internet?
+  #   script = "curl --silent --head http://www.google.com/ > /dev/null ; echo $?"
+  #   result = `#{script}`.chomp
+  #   puts result
+  #   result == '0'
+  # end
+
+
+  # This is determined by whether or not a line like the following appears in the output of `netstat -nr`:
+  # 0/1                10.137.0.41        UGSc           15        0   utun1
+  def vpn_running?
+    run_os_command('netstat -nr').split("\n").grep(/^0\/1.*utun1/).any?
+  end
+
+
+  # Identifies the (first) wireless network hardware port in the system, e.g. en0 or en1
+  def wifi_hardware_port
+    @wifi_hardware_port ||= begin
+      lines = run_os_command("networksetup -listallhardwareports").split("\n")
+      # Produces something like this:
+      # Hardware Port: Wi-Fi
+      # Device: en0
+      # Ethernet Address: ac:bc:32:b9:a9:9d
+      #
+      # Hardware Port: Bluetooth PAN
+      # Device: en3
+      # Ethernet Address: ac:bc:32:b9:a9:9e
+      wifi_port_line_num = (0...lines.size).detect do |index|
+        /: Wi-Fi$/.match(lines[index])
+      end
+      if wifi_port_line_num.nil?
+        raise %Q{Wifi port (e.g. "en0") not found in output of: networksetup -listallhardwareports}
+      else
+        lines[wifi_port_line_num + 1].split(': ').last
+      end
+    end
+  end
+
+
+  # Returns data pertaining to available wireless networks.
+  # For some reason, this often returns no results, so I've put the operation in a loop.
+  def available_network_info
+    return nil unless wifi_on? # no need to try
+    command = "#{AIRPORT_CMD} -s"
+    max_attempts = 50
+    max_attempts.times do
+      output = run_os_command(command)
+      if output.size > 0
+        return output.split("\n")
+      end
+    end
+    raise "Unable to get available network information after #{max_attempts} attempts."
+  end
+
+
+  # Returns data pertaining to "preferred" networks, many/most of which will probably not be available.
+  def preferred_networks
+    lines = run_os_command("networksetup -listpreferredwirelessnetworks #{wifi_hardware_port}").split("\n")
+    # Produces something like this, unsorted, and with leading tabs:
+    # Preferred networks on en0:
+    #         LibraryWiFi
+    #         @thePAD/Magma
+
+    lines.delete_at(0)                         # remove title line
+    lines.map! { |line| line.gsub("\t", '') }  # remove leading tabs
+    lines.sort! { |s1, s2| s1.casecmp(s2) }    # sort alphabetically, case insensitively
+    lines
+  end
+
+
+  # Returns true if wifi is on, else false.
+  def wifi_on?
+    lines = run_os_command("#{AIRPORT_CMD} -I").split("\n")
+    ! lines.grep("AirPort: Off").any?
+  end
+
+
+  # Turns wifi on.
+  def wifi_on
+    return if wifi_on?
+    run_os_command("networksetup -setairportpower #{wifi_hardware_port} on")
+    wifi_on? ? nil : raise("Wifi could not be enabled.")
+  end
+
+
+  # Turns wifi off.
+  def wifi_off
+    return unless wifi_on?
+    run_os_command("networksetup -setairportpower #{wifi_hardware_port} off")
+    wifi_on? ? raise("Wifi could not be disabled.") : nil
+  end
+
+
+  # Turns wifi off and then on, reconnecting to the originally connecting network.
+  def cycle_network
+    # TODO: Make this network name saving and restoring conditional on it not having a password.
+    # If the disabled code below is enabled, an error will be raised if a password is required,
+    # even though it is stored.
+    # network_name = current_network
+    wifi_off
+    wifi_on
+    # connect(network_name) if network_name
+  end
+
+
+  def connected_network_name
+    wifi_info['SSID']
+  end
+
+
+  def connected_to?(network_name)
+    network_name == connected_network_name
+  end
+
+
+  # Connects to the passed network name, optionally with password.
+  # Turns wifi on first, in case it was turned off.
+  def connect(network_name, password = nil)
+    if network_name.nil? || network_name.empty?
+      raise "A network name is required but was not provided."
+    end
+    wifi_on
+    command = "networksetup -setairportnetwork #{wifi_hardware_port} " + "#{Shellwords.shellescape(network_name)}"
+    if password
+      command << ' ' << Shellwords.shellescape(password)
+    end
+    run_os_command(command)
+
+    # Verify that the network is now connected:
+    actual_network_name = connected_network_name
+    unless actual_network_name == network_name
+      message = %Q{Expected to connect to "#{network_name}" but }
+      if actual_network_name
+        message << %Q{connected to "#{connected_network_name}" instead.}
+      else
+        message << "unable to connect to any network. Did you "
+      end
+      message << (password ? "provide the correct password?" : "need to provide a password?")
+      raise message
+    end
+    nil
+  end
+
+
+  # @return:
+  #   If the network is in the preferred networks list
+  #     If a password is associated w/this network, return the password
+  #     If not, return nil
+  #   else
+  #     raise an error
+  def preferred_network_password(preferred_network_name)
+    if preferred_networks.include?(preferred_network_name)
+      command = %Q{security find-generic-password -D "AirPort network password" -a "#{preferred_network_name}" -w 2>&1}
+      begin
+        return run_os_command(command).chomp
+      rescue OsCommandError => error
+        if error.exitstatus == 44 # network has no password stored
+          nil
+        else
+          raise
+        end
+      end
+    else
+      raise "Network #{preferred_network_name} not in preferred networks list."
+    end
+  end
+
+
+  # Returns the IP address assigned to the wifi port, or nil if none.
+  def ip_address
+    begin
+      run_os_command("ipconfig getifaddr #{wifi_hardware_port}").chomp
+    rescue OsCommandError => error
+      if error.exitstatus == 1
+        nil
+      else
+        raise
+      end
+    end
+  end
+
+
+  # Removes the specified network(s) from the preferred network list.
+  # @param network_names names of networks to remove; may be empty or contain nonexistent networks
+  # @return names of the networks that were removed (excludes non-preexisting networks)
+  def remove_preferred_networks(*network_names)
+    networks_to_remove = network_names & preferred_networks # exclude any nonexistent networks
+    networks_to_remove.each do |name|
+      run_os_command("sudo networksetup -removepreferredwirelessnetwork " +
+                         "#{wifi_hardware_port} #{Shellwords.shellescape(name)}")
+    end
+    networks_to_remove
+  end
+
+
+  # Returns the network currently connected to, or nil if none.
+  def current_network
+    lines = run_os_command("#{AIRPORT_CMD} -I").split("\n")
+    ssid_lines = lines.grep(/ SSID:/)
+    ssid_lines.empty? ? nil : ssid_lines.first.split('SSID: ').last.strip
+  end
+
+
+  # Disconnects from the currently connected network. Does not turn off wifi.
+  def disconnect
+    run_os_command("sudo #{AIRPORT_CMD} -z")
+    nil
+  end
+
+
+  # Returns some useful wifi-related information.
+  def wifi_info
+
+    info = {
+        wifi_on:     wifi_on?,
+        internet_on: connected_to_internet?,
+        vpn_on:      vpn_running?,
+        port:        wifi_hardware_port,
+        network:     current_network,
+        ip_address:  ip_address,
+        timestamp:   Time.now,
+    }
+    more_output = run_os_command(AIRPORT_CMD + " -I")
+    more_info   = colon_output_to_hash(more_output)
+    info.merge!(more_info)
+    info.delete('AirPort') # will be here if off, but info is already in wifi_on key
+    info
+  end
+
+
+  # Waits for the Internet connection to be in the desired state.
+  # @param status must be in [:conn, :disc, :off, :on]; waits for that state
+  # @param wait_interval_in_secs sleeps this interval between retries
+  #
+  # NOTE!: This is experimental and sometimes hangs.
+  def till(status, wait_interval_in_secs = nil)
+
+    wait_interval_in_secs ||= 0.5
+
+    exit_when = case status
+      when :conn
+        -> { connected_to_internet? }
+      when :disc
+        -> { ! connected_to_internet? }
+      when :on
+        -> { wifi_on? }
+      when :off
+        -> { ! wifi_on? }
+      else
+        raise ArgumentError.new("Option must be one of [:conn, :disc, :off, :on]. Was: #{status.inspect}")
+    end
+
+    loop do
+      return if exit_when.()
+      sleep(wait_interval_in_secs)
+    end
+  end
+
+
+  class OsCommandError < RuntimeError
+            attr_reader :exitstatus, :command, :text
+
+            def initialize(exitstatus, command, text)
+              @exitstatus = exitstatus
+              @command = command
+              @text = text
+            end
+          end
+
+
+  def run_os_command(command)
+    output = `#{command} 2>&1` # join stderr with stdout
+    if $?.exitstatus != 0
+      raise OsCommandError.new($?.exitstatus, command, output)
+    end
+    if @verbose_mode
+      puts "\n\n#{'-' * 79}\nCommand: #{command}\n\nOutput:\n#{output}#{'-' * 79}\n\n"
+    end
+    output
+  end
+  private :run_os_command
+
+
+  # Parses output like the text below into a hash:
+  # SSID: Pattara211
+  # MCS: 5
+  # channel: 7
+  def colon_output_to_hash(output)
+    lines = output.split("\n")
+    lines.each_with_object({}) do |line, new_hash|
+      key, value = line.split(': ')
+      key = key.strip
+      value.strip! if value
+      new_hash[key] = value
+    end
+  end
+  private :colon_output_to_hash
+end
+
+
+class CommandLineInterface
+
+  attr_reader :model
+
+  # Help text to be used when requested by 'h' command, in case of unrecognized or nonexistent command, etc.
+  HELP_TEXT = "
+mac-wifi version #{VERSION} -- Available commands are:
+
+ci                      - connected to Internet (not just wifi on)?
+co[nnect] network-name  - turns wifi on, connects to network-name
+cy[cle]                 - turns wifi off, then on, preserving network selection
+d[isconnect]            - disconnects from current network, does not turn off wifi
+h[elp]                  - prints this help
+i[nfo]                  - prints wifi-related information
+lsp[referred]           - lists preferred (not necessarily available) networks
+lsa[vailable]           - lists available networks
+n[etwork_name]          - name (SSID) of currently connected network
+on                      - turns wifi on
+of[f]                   - turns wifi off
+pa[ssword] network-name - shows password for preferred network-name
+q[uit]                  - exits this program (interactive shell mode only)
+r[m] network-name       - removes network-name from the preferred networks list
+s[hell]                 - opens an interactive pry shell (command line only)
+t[ill]                  - (experimental!) returns when the desired Internet connection state is true. Options:
+                          'on'/:on or 'off'/:off
+                          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)
+
+When in interactive shell mode:
+    * use quotes for string parameters such as method names.
+    * for pry commands, use prefix `%`.
+
+"
+
+
+  def initialize
+    @model = Model.new(verbose_mode)
+    @interactive_mode = false # will be true if/when user selects shell option on command line
+  end
+
+
+  class Command < Struct.new(:regex, :action); end
+
+
+  class BadCommandError < RuntimeError
+    def initialize(error_message)
+      super
+    end
+  end
+
+
+  def verbose_mode
+    /-v/.match(ENV['MAC_WIFI_OPTS'])
+  end
+
+
+  def print_help
+    puts HELP_TEXT
+  end
+
+
+  # We'd like to use awesome_print if it is available, but not require it.
+  # So, we try to require it, but if that fails, we fall back to using pp (pretty print).
+  # Returns true if awesome_print is available (after requiring it), else false after requiring 'pp'.
+  def awesome_print_available?
+    if @awesome_print_available.nil?  # first time here
+      begin
+        require 'awesome_print'
+        @awesome_print_available = true
+      rescue LoadError
+        require 'pp'
+        @awesome_print_available = false
+      end
+    end
+
+    @awesome_print_available
+  end
+
+
+  def fancy_puts(object)
+    awesome_print_available? ? ap(object) : pp(object)
+  end
+
+
+  # Asserts that a command has been passed on the command line.
+  def validate_command_line
+    if ARGV.empty?
+      puts "Syntax is: #{__FILE__} command [options]"
+      print_help
+      exit(-1)
+    end
+  end
+
+
+  # Pry will output the content of the method from which it was called.
+  # This small method exists solely to reduce the amount of pry's output
+  # that is not needed here.
+  def run_pry
+    binding.pry
+  end
+
+
+  # Runs a pry session in the context of this object.
+  # Commands and options specified on the command line can also be specified in the shell.
+  def run_shell
+    if @interactive_mode
+      puts "Already in shell."
+      return
+    end
+
+    @interactive_mode = true
+
+    begin
+      require 'pry'
+    rescue LoadError
+      puts "The 'pry' gem, required for running the shell, was not found. Please `gem install pry`."
+      exit(-1)
+    end
+
+    print_help
+
+    # Enable the line below if you have any problems with pry configuration being loaded
+    # that is messing up this runtime use of pry:
+    # Pry.config.should_load_rc = false
+
+    # Strangely, this is the only thing I have found that successfully suppresses the
+    # code context output, which is not useful here. Anyway, this will differentiate
+    # a pry command from a DSL command, which _is_ useful here.
+    Pry.config.command_prefix = '%'
+
+    run_pry
+  end
+
+
+  def output_network_password(network_name, password)
+    output =  %Q{Preferred network "#{network_name}" }
+    output << (password ? %Q{stored password is: "#{password}".} : "has no stored password.")
+    puts output
+    password
+  end
+
+
+  # For use by the shell; when typing a command and options, it is passed to process_command_line
+  def method_missing(method_name, *options)
+    method_valid = !! find_command_action(method_name.to_s)
+    if method_valid
+      process_command_line(method_name, options)
+    else
+      puts(%Q{"#{method_name}" is not a valid command or option. If you intend for this to be a string literal, use quotes.})
+    end
+  end
+
+
+  # Processes the command (ARGV[0]) and any relevant options (ARGV[1..-1]).
+  #
+  # CAUTION! In interactive mode, any strings entered (e.g. a network name) MUST
+  # be in a form that Ruby will recognize as a string, i.e. single or double quotes,
+  # %q, %Q, etc. Otherwise Ruby will assume it's a method name and pass it to
+  # method_missing!
+  def process_command_line(command, options)
+    action = find_command_action(command)
+    if action
+      action.(*options)
+    else
+      print_help
+      raise BadCommandError.new(
+          "Unrecognized command. Command was #{action} and options were #{options.inspect}.")
+    end
+  end
+
+
+  def quit
+    if @interactive_mode
+      exit(0)
+    else
+      puts "This command can only be run in shell mode."
+    end
+  end
+
+
+  def cmd_ci
+    connected = model.connected_to_internet?
+    puts "Connected to Internet: #{connected}" unless @interactive_mode
+    connected
+  end
+
+
+  def cmd_co(network, password = nil)
+    model.connect(network, password)
+  end
+
+
+  def cmd_cy
+    model.cycle_network
+  end
+
+
+  def cmd_d
+    model.disconnect
+  end
+
+
+  def cmd_h
+    print_help
+  end
+
+
+  def cmd_i
+    info = model.wifi_info
+    fancy_puts(info) unless @interactive_mode
+    info
+  end
+
+
+  def cmd_lsa
+    info = model.available_network_info
+    puts info unless @interactive_mode
+    info
+  end
+
+
+  def cmd_lsp
+    networks = model.preferred_networks
+    puts networks unless @interactive_mode
+    networks
+  end
+
+
+  def cmd_n
+    name = model.connected_network_name
+    unless @interactive_mode
+      puts "Network (SSID) name: #{name ? name : '[none]'}"
+    end
+    name
+  end
+
+
+  def cmd_of
+    model.wifi_off
+  end
+
+
+  def cmd_on
+    model.wifi_on
+  end
+
+
+  def cmd_pa(network)
+    password = model.preferred_network_password(network)
+    output_network_password(network, password) unless @interactive_mode
+    password
+  end
+
+
+  def cmd_q
+    quit
+  end
+
+
+  def cmd_r(*options)
+    model.remove_preferred_networks(*options)
+  end
+
+
+  def cmd_s
+    run_shell
+  end
+
+
+  def cmd_t(*options)
+    target_status = options[0].to_sym
+    wait_interval_in_secs = (options[1] ? Float(options[1]) : nil)
+    model.till(target_status, wait_interval_in_secs)
+  end
+
+
+  def cmd_w
+    on = model.wifi_on?
+    puts "Wifi on?: #{on}" unless @interactive_mode
+    on
+  end
+
+
+  def cmd_x
+    quit
+  end
+
+
+  def commands
+    @commands_ ||= [
+        Command.new(/^ci/,  -> (*_options) { cmd_ci            }),
+        Command.new(/^co/,  -> (*options)  { cmd_co(*options)  }),
+        Command.new(/^cy/,  -> (*_options) { cmd_cy            }),
+        Command.new(/^d/,   -> (*_options) { cmd_d             }),
+        Command.new(/^h/,   -> (*_options) { cmd_h             }),
+        Command.new(/^i/,   -> (*_options) { cmd_i             }),
+        Command.new(/^lsa/, -> (*_options) { cmd_lsa           }),
+        Command.new(/^lsp/, -> (*_options) { cmd_lsp           }),
+        Command.new(/^n/,   -> (*_options) { cmd_n             }),
+        Command.new(/^of/,  -> (*_options) { cmd_of            }),
+        Command.new(/^on/,  -> (*_options) { cmd_on            }),
+        Command.new(/^pa/,  -> (*options)  { cmd_pa(*options)  }),
+        Command.new(/^q/,   -> (*_options) { cmd_q             }),
+        Command.new(/^r/,   -> (*options)  { cmd_r(*options)   }),
+        Command.new(/^s/,   -> (*_options) { cmd_s             }),
+        Command.new(/^t/,   -> (*options)  { cmd_t(*options)   }),
+        Command.new(/^w/,   -> (*_options) { cmd_w             }),
+        Command.new(/^x/,   -> (*_options) { cmd_x             })
+    ]
+  end
+
+
+  def find_command_action(command_string)
+    result = commands.detect { |cmd| cmd.regex.match(command_string) }
+    result ? result.action : nil
+  end
+
+
+  def call
+    validate_command_line
+    begin
+      process_command_line(ARGV[0], ARGV[1..-1])
+    rescue BadCommandError => error
+      separator_line = "#{'!' * 79}\n"
+      puts separator_line + "Bad command: #{ARGV[0]}\n" + separator_line + "\n"
+      exit(-1)
+    end
+  end
+
+end
+
+end
+
+
+# @return true if this file is being run as a script, else false
+#
+# This file could be called as a script in either of these two ways:
+#
+# 1) by loading this file directly, or
+# 2) by running as a gem executable's binstub, in (relatively) '../../../bin'
+
+def running_as_script?
+  return true if __FILE__ == $0
+  return false if File.basename(__FILE__) != File.basename($0)
+
+  binstub_spec = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', '..', 'bin', File.basename(__FILE__)))
+  $0 == binstub_spec
+end
+
+
+# If this file is being called as a script, run it.
+# Else, it may be loaded to use the model in a different way.
+if running_as_script?
+  MacWifi::CommandLineInterface.new.call
+end
+

data/mac-wifi.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+VERSION = '0.0.1'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mac-wifi"
+  spec.version       = VERSION
+  spec.authors       = ["Keith Bennett"]
+  spec.email         = ["keithrbennett@gmail.com"]
+  spec.description   = %q{A command line interface for managing wifi on a Mac.}
+  spec.summary       = %q{Mac wifi utility}
+  spec.homepage      = "https://github.com/keithrbennett/mac-wifi"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/) - ['teaching_outline.md']
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  # spec.add_development_dependency "bundler", "~> 1.3"
+  # spec.add_development_dependency "rake", '~> 10.1'
+  # spec.add_development_dependency "rspec", '~> 3.0'
+
+end
+

data/spec/mac-wifi_spec.rb

@@ -0,0 +1,114 @@
+# The functionality of this software is very difficult to test,
+# sinece it relies on external conditions that cannot be faked.
+# These tests merely run the commands and assert that no
+# error has occurred; they don't make any attempt to verify the data.
+# Many of them are run once with the wifi on, and once when it's off.
+
+
+load File.join(File.dirname(__FILE__), '..', 'bin', 'mac-wifi')
+
+module MacWifi
+
+describe Model do
+
+
+  subject { Model.new }
+
+  context 'turning wifi on and off' do
+    it 'can turn wifi on' do
+      subject.wifi_off
+      expect(subject.wifi_on?).to eq(false)
+      subject.wifi_on
+      expect(subject.wifi_on?).to eq(true)
+    end
+
+    it 'can turn wifi off' do
+      subject.wifi_on
+      expect(subject.wifi_on?).to eq(true)
+      subject.wifi_off
+      expect(subject.wifi_on?).to eq(false)
+    end
+
+    it 'can cycle network' do
+      subject.wifi_on
+      subject.cycle_network
+      expect(subject.wifi_on?).to eq(true)
+    end
+
+    it 'can list available networks' do
+      subject.wifi_on
+      subject.available_network_info
+    end
+  end
+
+
+  shared_examples_for 'testing to see commands complete without error' do |wifi_starts_on|
+
+    it 'can determine if connected to Internet' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      # We cannot assert that we're connected to the Internet even
+      # if the wifi is on, because we're probably not connected to a network.
+      subject.connected_to_internet?
+    end
+
+    it 'can get wifi port' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      subject.wifi_hardware_port
+    end
+
+    it 'can list info' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      subject.wifi_info
+    end
+
+    it 'can list preferred networks' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      subject.preferred_networks
+    end
+
+    it 'can see if wifi is on' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      subject.wifi_on?
+    end
+
+    it 'can query the connected network name' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      name = subject.connected_network_name
+      unless subject.wifi_on?
+        expect(name).to eq(nil)
+      end
+    end
+
+    # it 'can attempt to connect to a network' do
+    # pending 'cannot reliably expect any given network to be available'
+    # end
+
+    # it 'can determine the IP address on the network' do
+    #   pending 'How to reliably reproduce connection to a network?'
+    # end
+
+    it 'can determine the current network' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      network = subject.current_network
+      unless subject.wifi_on?
+        expect(network).to eq(nil)
+      end
+    end
+
+    it 'can call disconnect twice consecutively' do
+      wifi_starts_on ? subject.wifi_on : subject.wifi_off
+      subject.disconnect
+      subject.disconnect
+    end
+  end
+
+  context 'wifi starts on' do # without a context block the way that rspec expands the examples causes the parameters to overwrite each other
+    include_examples 'testing to see commands complete without error', true
+  end
+
+  context 'wifi starts off' do # without a context block the way that rspec expands the examples causes the parameters to overwrite each other
+    include_examples 'testing to see commands complete without error', false
+  end
+end
+
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: mac-wifi
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Keith Bennett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-17 00:00:00.000000000 Z
+dependencies: []
+description: A command line interface for managing wifi on a Mac.
+email:
+- keithrbennett@gmail.com
+executables:
+- mac-wifi
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- bin/mac-wifi
+- mac-wifi.gemspec
+- spec/mac-wifi_spec.rb
+homepage: https://github.com/keithrbennett/mac-wifi
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Mac wifi utility
+test_files:
+- spec/mac-wifi_spec.rb