The cl-wol.cli Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-wol.cli Reference Manual

This is the cl-wol.cli Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:18:21 2022 GMT+0.

Table of Contents


1 Introduction

* cl-wol

=cl-wol= is a Common Lisp system and CLI application, which can power
on remote systems using [[https://en.wikipedia.org/wiki/Wake-on-LAN][Wake on LAN (WoL)]].

* Requirements

- [[https://www.quicklisp.org/beta/][Quicklisp]]

* Installation

=cl-wol= is not yet in Quicklisp, so in order to install it you will need to
clone the repo and add it to your [[https://www.quicklisp.org/beta/faq.html][Quicklisp local-projects]].

#+begin_src shell
  cd ~/quicklisp/local-projects
  git clone https://github.com/dnaeon/cl-wol.git
#+end_src

If you are installing the CLI application, you will also need a recent
version of [[https://github.com/dnaeon/clingon][clingon]], as the one found in Quicklisp is not yet updated
to the latest release.

* Systems

=cl-wol= provides the following systems.

The =cl-wol.core= system provides the core functionallity for powering
on remote systems using [[https://en.wikipedia.org/wiki/Wake-on-LAN][Wake on LAN (WoL)]] by broadcasting a magic
packet to a destination port and address.

The =cl-wol.test= system provides the test suite of =cl-wol.core=.

The =cl-wol.cli= system provides a command-line interface application,
built on top of =cl-wol.core=, which comes with support for looking up
hosts and their MAC addresses from a local SQLite database.

* Usage

The following formats of MAC addresses are supported by =cl-wol=.

- As a string in =AA:BB:CC:DD:EE:FF= format
- As a string in =AA-BB-CC-DD-EE-FF= format
- As a =(simple-array (unsigned-byte 8) (6))= vector

** API

The following section describes how to use the =cl-wol.core= system.

First, start your Lisp REPL and load the system.

#+begin_src lisp
  CL-USER> (ql:quickload :cl-wol.core)
  To load "cl-wol.core":
    Load 1 ASDF system:
      cl-wol.core
  ; Loading "cl-wol.core"

  (:CL-WOL.CORE)
#+end_src

In order to wake a remote system identified by a given MAC address we
first need to create a new instance of =CL-WOL.CORE:MAGIC-PACKET=.

#+begin_src lisp
  CL-USER> (defparameter *magic-packet*
             (cl-wol.core:make-magic-packet "aa:bb:cc:dd:ee:ff"))
  *MAGIC-PACKET*
#+end_src

The =CL-WOL.CORE:MAKE-MAGIC-PACKET= function accepts an optional
second argument, which represents a =SecureOn= password. The format of
the =SecureOn= password is the same as the one for MAC addresses. For
example, if you need to create a magic packet with =SecureOn= password
appended to the payload you can evaluate the following expression.

#+begin_src lisp
  CL-USER> (defparameter *magic-packet*
             (cl-wol.core:make-magic-packet "aa:bb:cc:dd:ee:ff" "00-00-00-00-00-00"))
  *MAGIC-PACKET*
#+end_src

Another way to create a magic packet is by providing a =(simple-array
(unsigned-byte 8) (6)= vector to =CL-WOL.CORE:MAKE-MAGIC-PACKET=. You
can also use the =CL-WOL.CORE:MAKE-OCTET-VECTOR= function to create a
new octet vector. For example.

#+begin_src lisp
  CL-USER> (defparameter *magic-packet*
             (cl-wol.core:make-magic-packet (cl-wol.core:make-octet-vector #(1 2 3 4 5 6))))
  *MAGIC-PACKET*
#+end_src

Now that we have a magic packet we can broadcast it to a given port
and address. In order to do that we will use the =CL-WOL.CORE:WAKE=
generic function. The following example broadcasts the magic packet
to =255.255.255.255= on port =7=.

#+begin_src lisp
  CL-USER> (cl-wol.core:wake *magic-packet* "255.255.255.255" 7)
  T
#+end_src

** CLI

[[./images/wol-demo.gif]]

You can build the CLI application of =cl-wol= by executing the
following command.

#+begin_src shell
  make cli
#+end_src

The default Lisp implementation is SBCL, so if you are using a
different implementation simply pass the =LISP= environment variable
before invoking the =cli= target. This command builds the CLI
application using Clozure Common Lisp for example.

#+begin_src shell
  LISP=ccl make cli
#+end_src

Once the app is built you can find the executable in the =bin=
directory of the =cl-wol.cli= system, which you can later install
somewhere in your =PATH=, e.g.

#+begin_src shell
  sudo install ./bin/wol /usr/local/bin
#+end_src

You can also generate Zsh completions for the CLI application by
executing the =wol zsh-completions= sub-command, e.g.

#+begin_src shell
  wol zsh-completions > ~/.zsh-completions/_wol
#+end_src

You can wake up remote systems by using the =wol wake=
sub-command. Multiple MAC addresses can be specified on the
command-line as separate arguments, e.g.

#+begin_src shell
  $ wol wake 00:01:02:03:04:05 aa:bb:cc:dd:ee:ff
  Waking up 00:01:02:03:04:05 ...
  Waking up aa:bb:cc:dd:ee:ff ...
#+end_src

Instead of remembering MAC addresses by heart the =cl-wol= CLI
application supports storing MAC addresses in a local SQLite database,
which can be looked up by the various sub-commands.

First, we need to initialize a new database file using the =wol
init-db= sub-command.

#+begin_src shell
  $ wol init-db --database wol.db
    [14:25:36] cl-migratum.core core.lisp (apply-pending) -
    Found 1 pending migration(s) to be applied
    [14:25:36] cl-migratum.core core.lisp (apply-and-register) -
    Applying migration 20211222183337 - add_hosts_table
#+end_src

Once the database is initialized you can add hosts to it. For example:

#+begin_src shell
  wol add-host --database wol.db --address aa:bb:cc:dd:ee:ff --name box-01
  wol add-host --database wol.db --address 01:02:03:04:05:06 --name box-02
#+end_src

Listing the hosts from the database is done via the =wol list-hosts=
sub-command.

#+begin_src shell
  $ wol list-hosts --database wol.db
  +----+--------+-------------------+---------------------+
  | ID | NAME   | ADDR              | CREATED AT          |
  +----+--------+-------------------+---------------------+
  |  1 | box-01 | aa:bb:cc:dd:ee:ff | 2021-12-26 14:27:19 |
  |  2 | box-02 | 01:02:03:04:05:06 | 2021-12-26 14:27:30 |
  +----+--------+-------------------+---------------------+
#+end_src

You can now wake up hosts by referring to their names. In order to do
that use the =--database= and =--name= options of the =wol wake=
sub-command. The =--name= option can be repeated multiple times in
order to refer to different hosts, e.g.

#+begin_src shell
  $ wol wake --database wol.db --name box-01 --name box-02
  Waking up 01:02:03:04:05:06 ...
  Waking up aa:bb:cc:dd:ee:ff ...
#+end_src

Deleting hosts from the database is done via the =wol delete-host=
sub-command, e.g.

#+begin_src shell
  wol delete-host --database wol.db box-01 box-02
#+end_src

* Tests

Tests are provided as part of the =:cl-wol.test= system.

In order to run the tests you can evaluate the following expressions
from your Lisp REPL.

#+begin_src lisp
  CL-USER> (ql:quickload :cl-wol.test)
  CL-USER> (asdf:test-system :cl-wol.test)
#+end_src

Or you can run the tests using the =test= target instead, e.g.

#+begin_src shell
  make test
#+end_src

Here's how to run the tests against SBCL, CCL and ECL for example.

#+begin_src shell
  for lisp in sbcl ccl ecl; do
      echo "Running tests using ${lisp} ..."
      LISP=${lisp} make test > ${lisp}-tests.out
  done
#+end_src

* Docker Images

You can build and run a Docker image of the CLI application by
executing the following commands.

#+begin_src shell
  docker build -t cl-wol.cli:latest -f Dockerfile .
#+end_src

A separate image can be built for running the test suite of =cl-wol=.

#+begin_src shell
  docker build -t cl-wol.test:latest -f Dockerfile.tests .
  docker run --rm cl-wol.test:latest
#+end_src

* Contributing

=cl-wol= is hosted on [[https://github.com/dnaeon/cl-wol][Github]]. Please contribute by reporting issues,
suggesting features or by sending patches using pull requests.

* License

This project is Open Source and licensed under the [[http://opensource.org/licenses/BSD-2-Clause][BSD License]].

* Authors

- Marin Atanasov Nikolov 


2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 cl-wol.cli

CLI built on top of the cl-wol.core system

Long Name

cl-wol.cli

Maintainer

Marin Atanasov Nikolov <dnaeon@gmail.com>

Author

Marin Atanasov Nikolov <dnaeon@gmail.com>

Home Page

https://github.com/dnaeon/cl-wol

Source Control

https://github.com/dnaeon/cl-wol

Bug Tracker

https://github.com/dnaeon/cl-wol

License

BSD 2-Clause

Long Description

* cl-wol

=cl-wol= is a Common Lisp system and CLI application, which can power
on remote systems using [[https://en.wikipedia.org/wiki/Wake-on-LAN][Wake on LAN (WoL)]].

* Requirements

- [[https://www.quicklisp.org/beta/][Quicklisp]]

* Installation

=cl-wol= is not yet in Quicklisp, so in order to install it you will need to
clone the repo and add it to your [[https://www.quicklisp.org/beta/faq.html][Quicklisp local-projects]].

#+begin_src shell
cd ~/quicklisp/local-projects
git clone https://github.com/dnaeon/cl-wol.git
#+end_src

If you are installing the CLI application, you will also need a recent
version of [[https://github.com/dnaeon/clingon][clingon]], as the one found in Quicklisp is not yet updated to the latest release.

* Systems

=cl-wol= provides the following systems.

The =cl-wol.core= system provides the core functionallity for powering
on remote systems using [[https://en.wikipedia.org/wiki/Wake-on-LAN][Wake on LAN (WoL)]] by broadcasting a magic packet to a destination port and address.

The =cl-wol.test= system provides the test suite of =cl-wol.core=.

The =cl-wol.cli= system provides a command-line interface application,
built on top of =cl-wol.core=, which comes with support for looking up
hosts and their MAC addresses from a local SQLite database.

* Usage

The following formats of MAC addresses are supported by =cl-wol=.

- As a string in =AA:BB:CC:DD:EE:FF= format
- As a string in =AA-BB-CC-DD-EE-FF= format
- As a =(simple-array (unsigned-byte 8) (6))= vector

** API

The following section describes how to use the =cl-wol.core= system.

First, start your Lisp REPL and load the system.

#+begin_src lisp
CL-USER> (ql:quickload :cl-wol.core)
To load "cl-wol.core":
Load 1 ASDF system:
cl-wol.core
; Loading "cl-wol.core"

(:CL-WOL.CORE)
#+end_src

In order to wake a remote system identified by a given MAC address we
first need to create a new instance of =CL-WOL.CORE:MAGIC-PACKET=.

#+begin_src lisp
CL-USER> (defparameter *magic-packet*
(cl-wol.core:make-magic-packet "aa:bb:cc:dd:ee:ff"))
*MAGIC-PACKET*
#+end_src

The =CL-WOL.CORE:MAKE-MAGIC-PACKET= function accepts an optional
second argument, which represents a =SecureOn= password. The format of
the =SecureOn= password is the same as the one for MAC addresses. For
example, if you need to create a magic packet with =SecureOn= password
appended to the payload you can evaluate the following expression.

#+begin_src lisp
CL-USER> (defparameter *magic-packet*
(cl-wol.core:make-magic-packet "aa:bb:cc:dd:ee:ff" "00-00-00-00-00-00"))
*MAGIC-PACKET*
#+end_src

Another way to create a magic packet is by providing a =(simple-array
(unsigned-byte 8) (6)= vector to =CL-WOL.CORE:MAKE-MAGIC-PACKET=. You
can also use the =CL-WOL.CORE:MAKE-OCTET-VECTOR= function to create a
new octet vector. For example.

#+begin_src lisp
CL-USER> (defparameter *magic-packet*
(cl-wol.core:make-magic-packet (cl-wol.core:make-octet-vector #(1 2 3 4 5 6)))) *MAGIC-PACKET*
#+end_src

Now that we have a magic packet we can broadcast it to a given port
and address. In order to do that we will use the =CL-WOL.CORE:WAKE=
generic function. The following example broadcasts the magic packet
to =255.255.255.255= on port =7=.

#+begin_src lisp
CL-USER> (cl-wol.core:wake *magic-packet* "255.255.255.255" 7)
T
#+end_src

** CLI

[[./images/wol-demo.gif]]

You can build the CLI application of =cl-wol= by executing the
following command.

#+begin_src shell
make cli
#+end_src

The default Lisp implementation is SBCL, so if you are using a
different implementation simply pass the =LISP= environment variable
before invoking the =cli= target. This command builds the CLI
application using Clozure Common Lisp for example.

#+begin_src shell
LISP=ccl make cli
#+end_src

Once the app is built you can find the executable in the =bin=
directory of the =cl-wol.cli= system, which you can later install
somewhere in your =PATH=, e.g.

#+begin_src shell
sudo install ./bin/wol /usr/local/bin
#+end_src

You can also generate Zsh completions for the CLI application by
executing the =wol zsh-completions= sub-command, e.g.

#+begin_src shell
wol zsh-completions > ~/.zsh-completions/_wol
#+end_src

You can wake up remote systems by using the =wol wake=
sub-command. Multiple MAC addresses can be specified on the
command-line as separate arguments, e.g.

#+begin_src shell
$ wol wake 00:01:02:03:04:05 aa:bb:cc:dd:ee:ff
Waking up 00:01:02:03:04:05 ...
Waking up aa:bb:cc:dd:ee:ff ...
#+end_src

Instead of remembering MAC addresses by heart the =cl-wol= CLI
application supports storing MAC addresses in a local SQLite database,
which can be looked up by the various sub-commands.

First, we need to initialize a new database file using the =wol
init-db= sub-command.

#+begin_src shell
$ wol init-db –database wol.db
<INFO> [14:25:36] cl-migratum.core core.lisp (apply-pending) -
Found 1 pending migration(s) to be applied
<INFO> [14:25:36] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20211222183337 - add_hosts_table
#+end_src

Once the database is initialized you can add hosts to it. For example:

#+begin_src shell
wol add-host –database wol.db –address aa:bb:cc:dd:ee:ff –name box-01
wol add-host –database wol.db –address 01:02:03:04:05:06 –name box-02
#+end_src

Listing the hosts from the database is done via the =wol list-hosts=
sub-command.

#+begin_src shell
$ wol list-hosts –database wol.db
+—-+——–+——————-+———————+
| ID | NAME | ADDR | CREATED AT | +—-+——–+——————-+———————+
| 1 | box-01 | aa:bb:cc:dd:ee:ff | 2021-12-26 14:27:19 |
| 2 | box-02 | 01:02:03:04:05:06 | 2021-12-26 14:27:30 | +—-+——–+——————-+———————+
#+end_src

You can now wake up hosts by referring to their names. In order to do
that use the =–database= and =–name= options of the =wol wake=
sub-command. The =–name= option can be repeated multiple times in
order to refer to different hosts, e.g.

#+begin_src shell
$ wol wake –database wol.db –name box-01 –name box-02
Waking up 01:02:03:04:05:06 ...
Waking up aa:bb:cc:dd:ee:ff ...
#+end_src

Deleting hosts from the database is done via the =wol delete-host=
sub-command, e.g.

#+begin_src shell
wol delete-host –database wol.db box-01 box-02
#+end_src

* Tests

Tests are provided as part of the =:cl-wol.test= system.

In order to run the tests you can evaluate the following expressions
from your Lisp REPL.

#+begin_src lisp
CL-USER> (ql:quickload :cl-wol.test)
CL-USER> (asdf:test-system :cl-wol.test)
#+end_src

Or you can run the tests using the =test= target instead, e.g.

#+begin_src shell
make test
#+end_src

Here’s how to run the tests against SBCL, CCL and ECL for example.

#+begin_src shell
for lisp in sbcl ccl ecl; do
echo "Running tests using ${lisp} ..."
LISP=${lisp} make test > ${lisp}-tests.out
done
#+end_src

* Docker Images

You can build and run a Docker image of the CLI application by
executing the following commands.

#+begin_src shell
docker build -t cl-wol.cli:latest -f Dockerfile .
#+end_src

A separate image can be built for running the test suite of =cl-wol=.

#+begin_src shell
docker build -t cl-wol.test:latest -f Dockerfile.tests .
docker run –rm cl-wol.test:latest
#+end_src

* Contributing

=cl-wol= is hosted on [[https://github.com/dnaeon/cl-wol][Github]]. Please contribute by reporting issues, suggesting features or by sending patches using pull requests.

* License

This project is Open Source and licensed under the [[http://opensource.org/licenses/BSD-2-Clause][BSD License]].

* Authors

- Marin Atanasov Nikolov <dnaeon@gmail.com>

Version

0.1.0

Dependencies
  • cl-wol.core (system).
  • clingon (system).
  • cl-migratum (system).
  • cl-migratum.driver.dbi (system).
  • cl-migratum.provider.local-path (system).
  • cl-ascii-table (system).
Source

cl-wol.cli.asd.

Child Components

Previous: , Up: Systems   [Contents][Index]

2.2 cl-wol.core

Core Wake On Lan (WoL) Common Lisp System

Long Name

cl-wol.core

Maintainer

Marin Atanasov Nikolov <dnaeon@gmail.com>

Author

Marin Atanasov Nikolov <dnaeon@gmail.com>

Home Page

https://github.com/dnaeon/cl-wol

Source Control

https://github.com/dnaeon/cl-wol

Bug Tracker

https://github.com/dnaeon/cl-wol

License

BSD 2-Clause

Long Description

* cl-wol

=cl-wol= is a Common Lisp system and CLI application, which can power
on remote systems using [[https://en.wikipedia.org/wiki/Wake-on-LAN][Wake on LAN (WoL)]].

* Requirements

- [[https://www.quicklisp.org/beta/][Quicklisp]]

* Installation

=cl-wol= is not yet in Quicklisp, so in order to install it you will need to
clone the repo and add it to your [[https://www.quicklisp.org/beta/faq.html][Quicklisp local-projects]].

#+begin_src shell
cd ~/quicklisp/local-projects
git clone https://github.com/dnaeon/cl-wol.git
#+end_src

If you are installing the CLI application, you will also need a recent
version of [[https://github.com/dnaeon/clingon][clingon]], as the one found in Quicklisp is not yet updated to the latest release.

* Systems

=cl-wol= provides the following systems.

The =cl-wol.core= system provides the core functionallity for powering
on remote systems using [[https://en.wikipedia.org/wiki/Wake-on-LAN][Wake on LAN (WoL)]] by broadcasting a magic packet to a destination port and address.

The =cl-wol.test= system provides the test suite of =cl-wol.core=.

The =cl-wol.cli= system provides a command-line interface application,
built on top of =cl-wol.core=, which comes with support for looking up
hosts and their MAC addresses from a local SQLite database.

* Usage

The following formats of MAC addresses are supported by =cl-wol=.

- As a string in =AA:BB:CC:DD:EE:FF= format
- As a string in =AA-BB-CC-DD-EE-FF= format
- As a =(simple-array (unsigned-byte 8) (6))= vector

** API

The following section describes how to use the =cl-wol.core= system.

First, start your Lisp REPL and load the system.

#+begin_src lisp
CL-USER> (ql:quickload :cl-wol.core)
To load "cl-wol.core":
Load 1 ASDF system:
cl-wol.core
; Loading "cl-wol.core"

(:CL-WOL.CORE)
#+end_src

In order to wake a remote system identified by a given MAC address we
first need to create a new instance of =CL-WOL.CORE:MAGIC-PACKET=.

#+begin_src lisp
CL-USER> (defparameter *magic-packet*
(cl-wol.core:make-magic-packet "aa:bb:cc:dd:ee:ff"))
*MAGIC-PACKET*
#+end_src

The =CL-WOL.CORE:MAKE-MAGIC-PACKET= function accepts an optional
second argument, which represents a =SecureOn= password. The format of
the =SecureOn= password is the same as the one for MAC addresses. For
example, if you need to create a magic packet with =SecureOn= password
appended to the payload you can evaluate the following expression.

#+begin_src lisp
CL-USER> (defparameter *magic-packet*
(cl-wol.core:make-magic-packet "aa:bb:cc:dd:ee:ff" "00-00-00-00-00-00"))
*MAGIC-PACKET*
#+end_src

Another way to create a magic packet is by providing a =(simple-array
(unsigned-byte 8) (6)= vector to =CL-WOL.CORE:MAKE-MAGIC-PACKET=. You
can also use the =CL-WOL.CORE:MAKE-OCTET-VECTOR= function to create a
new octet vector. For example.

#+begin_src lisp
CL-USER> (defparameter *magic-packet*
(cl-wol.core:make-magic-packet (cl-wol.core:make-octet-vector #(1 2 3 4 5 6)))) *MAGIC-PACKET*
#+end_src

Now that we have a magic packet we can broadcast it to a given port
and address. In order to do that we will use the =CL-WOL.CORE:WAKE=
generic function. The following example broadcasts the magic packet
to =255.255.255.255= on port =7=.

#+begin_src lisp
CL-USER> (cl-wol.core:wake *magic-packet* "255.255.255.255" 7)
T
#+end_src

** CLI

[[./images/wol-demo.gif]]

You can build the CLI application of =cl-wol= by executing the
following command.

#+begin_src shell
make cli
#+end_src

The default Lisp implementation is SBCL, so if you are using a
different implementation simply pass the =LISP= environment variable
before invoking the =cli= target. This command builds the CLI
application using Clozure Common Lisp for example.

#+begin_src shell
LISP=ccl make cli
#+end_src

Once the app is built you can find the executable in the =bin=
directory of the =cl-wol.cli= system, which you can later install
somewhere in your =PATH=, e.g.

#+begin_src shell
sudo install ./bin/wol /usr/local/bin
#+end_src

You can also generate Zsh completions for the CLI application by
executing the =wol zsh-completions= sub-command, e.g.

#+begin_src shell
wol zsh-completions > ~/.zsh-completions/_wol
#+end_src

You can wake up remote systems by using the =wol wake=
sub-command. Multiple MAC addresses can be specified on the
command-line as separate arguments, e.g.

#+begin_src shell
$ wol wake 00:01:02:03:04:05 aa:bb:cc:dd:ee:ff
Waking up 00:01:02:03:04:05 ...
Waking up aa:bb:cc:dd:ee:ff ...
#+end_src

Instead of remembering MAC addresses by heart the =cl-wol= CLI
application supports storing MAC addresses in a local SQLite database,
which can be looked up by the various sub-commands.

First, we need to initialize a new database file using the =wol
init-db= sub-command.

#+begin_src shell
$ wol init-db –database wol.db
<INFO> [14:25:36] cl-migratum.core core.lisp (apply-pending) -
Found 1 pending migration(s) to be applied
<INFO> [14:25:36] cl-migratum.core core.lisp (apply-and-register) -
Applying migration 20211222183337 - add_hosts_table
#+end_src

Once the database is initialized you can add hosts to it. For example:

#+begin_src shell
wol add-host –database wol.db –address aa:bb:cc:dd:ee:ff –name box-01
wol add-host –database wol.db –address 01:02:03:04:05:06 –name box-02
#+end_src

Listing the hosts from the database is done via the =wol list-hosts=
sub-command.

#+begin_src shell
$ wol list-hosts –database wol.db
+—-+——–+——————-+———————+
| ID | NAME | ADDR | CREATED AT | +—-+——–+——————-+———————+
| 1 | box-01 | aa:bb:cc:dd:ee:ff | 2021-12-26 14:27:19 |
| 2 | box-02 | 01:02:03:04:05:06 | 2021-12-26 14:27:30 | +—-+——–+——————-+———————+
#+end_src

You can now wake up hosts by referring to their names. In order to do
that use the =–database= and =–name= options of the =wol wake=
sub-command. The =–name= option can be repeated multiple times in
order to refer to different hosts, e.g.

#+begin_src shell
$ wol wake –database wol.db –name box-01 –name box-02
Waking up 01:02:03:04:05:06 ...
Waking up aa:bb:cc:dd:ee:ff ...
#+end_src

Deleting hosts from the database is done via the =wol delete-host=
sub-command, e.g.

#+begin_src shell
wol delete-host –database wol.db box-01 box-02
#+end_src

* Tests

Tests are provided as part of the =:cl-wol.test= system.

In order to run the tests you can evaluate the following expressions
from your Lisp REPL.

#+begin_src lisp
CL-USER> (ql:quickload :cl-wol.test)
CL-USER> (asdf:test-system :cl-wol.test)
#+end_src

Or you can run the tests using the =test= target instead, e.g.

#+begin_src shell
make test
#+end_src

Here’s how to run the tests against SBCL, CCL and ECL for example.

#+begin_src shell
for lisp in sbcl ccl ecl; do
echo "Running tests using ${lisp} ..."
LISP=${lisp} make test > ${lisp}-tests.out
done
#+end_src

* Docker Images

You can build and run a Docker image of the CLI application by
executing the following commands.

#+begin_src shell
docker build -t cl-wol.cli:latest -f Dockerfile .
#+end_src

A separate image can be built for running the test suite of =cl-wol=.

#+begin_src shell
docker build -t cl-wol.test:latest -f Dockerfile.tests .
docker run –rm cl-wol.test:latest
#+end_src

* Contributing

=cl-wol= is hosted on [[https://github.com/dnaeon/cl-wol][Github]]. Please contribute by reporting issues, suggesting features or by sending patches using pull requests.

* License

This project is Open Source and licensed under the [[http://opensource.org/licenses/BSD-2-Clause][BSD License]].

* Authors

- Marin Atanasov Nikolov <dnaeon@gmail.com>

Version

0.1.0

Dependencies
  • cl-ppcre (system).
  • usocket (system).
Source

cl-wol.core.asd.

Child Component

core (module).


3 Modules

Modules are listed depth-first from the system components tree.


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 cl-wol.cli/migrations

Source

cl-wol.cli.asd.

Parent Component

cl-wol.cli (system).

Child Components

3.2 cl-wol.cli/cli

Dependency

migrations (module).

Source

cl-wol.cli.asd.

Parent Component

cl-wol.cli (system).

Child Components

Previous: , Up: Modules   [Contents][Index]

3.3 cl-wol.core/core

Source

cl-wol.core.asd.

Parent Component

cl-wol.core (system).

Child Component

core.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.1 cl-wol.cli/cl-wol.cli.asd

Source

cl-wol.cli.asd.

Parent Component

cl-wol.cli (system).

ASDF Systems

cl-wol.cli.

Packages

cl-wol-cli-system.


4.1.2 cl-wol.core/cl-wol.core.asd

Source

cl-wol.core.asd.

Parent Component

cl-wol.core (system).

ASDF Systems

cl-wol.core.

Packages

cl-wol-core-system.


4.1.3 cl-wol.cli/cli/package.lisp

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Packages

cl-wol.cli.


4.1.4 cl-wol.cli/cli/db-utils.lisp

Dependency

package.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.5 cl-wol.cli/cli/wake.lisp

Dependency

db-utils.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.6 cl-wol.cli/cli/zsh-completions.lisp

Dependency

wake.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.7 cl-wol.cli/cli/print-doc.lisp

Dependency

zsh-completions.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.8 cl-wol.cli/cli/init-db.lisp

Dependency

print-doc.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.9 cl-wol.cli/cli/add-host.lisp

Dependency

init-db.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.10 cl-wol.cli/cli/delete-host.lisp

Dependency

add-host.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.11 cl-wol.cli/cli/list-hosts.lisp

Dependency

delete-host.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Internals

4.1.12 cl-wol.cli/cli/main.lisp

Dependency

list-hosts.lisp (file).

Source

cl-wol.cli.asd.

Parent Component

cli (module).

Public Interface

main (function).

Internals

4.1.13 cl-wol.core/core/core.lisp

Source

cl-wol.core.asd.

Parent Component

core (module).

Packages

cl-wol.core.

Public Interface
Internals

simple-octet-vector (type).


Previous: , Up: Files   [Contents][Index]

4.2 Static


4.2.1 cl-wol.cli/migrations/20211222183337-add_hosts_table.down.sql

Source

cl-wol.cli.asd.

Parent Component

migrations (module).


4.2.2 cl-wol.cli/migrations/20211222183337-add_hosts_table.up.sql

Source

cl-wol.cli.asd.

Parent Component

migrations (module).


5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 cl-wol-core-system

Source

cl-wol.core.asd.

Use List
  • asdf/interface.
  • common-lisp.

Next: , Previous: , Up: Packages   [Contents][Index]

5.2 cl-wol.cli

Source

package.lisp.

Nickname

wol.cli

Use List

common-lisp.

Public Interface

main (function).

Internals

Next: , Previous: , Up: Packages   [Contents][Index]

5.3 cl-wol.core

Source

core.lisp.

Nickname

wol.core

Use List

common-lisp.

Public Interface
Internals

simple-octet-vector (type).


Previous: , Up: Packages   [Contents][Index]

5.4 cl-wol-cli-system

Source

cl-wol.cli.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Public Interface


6.1.1 Special variables

Special Variable: *mac-regex*

Regex used to parse MAC addresses

Package

cl-wol.core.

Source

core.lisp.


6.1.2 Ordinary functions

Function: main ()

Main CLI entrypoint

Package

cl-wol.cli.

Source

main.lisp.

Function: make-octet-vector (contents)

Make an octet vector from the given contents

Package

cl-wol.core.

Source

core.lisp.

Function: parse-hex-bytes (str)

Parses a string representation of a MAC address or SecureOn password into a list of bytes

Package

cl-wol.core.

Source

core.lisp.


6.1.3 Generic functions

Generic Function: encode-payload (object)

Encodes the OBJECT and returns a vector of bytes representing the payload for waking up a remote system

Package

cl-wol.core.

Source

core.lisp.

Methods
Method: encode-payload ((object magic-packet))
Generic Function: mac-address (object)

Returns the string representation of the MAC address associated with the OBJECT

Package

cl-wol.core.

Source

core.lisp.

Methods
Method: mac-address ((object magic-packet))
Reader Method: mac-address ((condition invalid-mac-address))
Target Slot

address.

Generic Reader: mac-octets (object)

Returns a vector of bytes representing the MAC address associated with the OBJECT

Package

cl-wol.core.

Source

core.lisp.

Methods
Reader Method: mac-octets ((magic-packet magic-packet))

Destination MAC address

Target Slot

address.

Generic Function: make-magic-packet (address &optional password)

Creates a new magic packet destined to the given ADDRESS. If PASSWORD is specified it represents a SecureOn password

Package

cl-wol.core.

Source

core.lisp.

Methods
Method: make-magic-packet (address &optional password)
Method: make-magic-packet ((address string) &optional password)
Generic Reader: payload (condition)
Package

cl-wol.core.

Methods
Reader Method: payload ((condition invalid-payload))
Source

core.lisp.

Target Slot

payload.

Generic Reader: secureon-password (object)

Returns the SecureOn password associated with the OBJECT as a vector of octets

Package

cl-wol.core.

Source

core.lisp.

Methods
Reader Method: secureon-password ((magic-packet magic-packet))

Optional SecureOn password

Target Slot

password.

Reader Method: secureon-password ((condition invalid-password))
Target Slot

password.

Generic Function: wake (object address port)

Wakes up a remote system by encoding the OBJECT and sending a broadcast packet to the given ADDRESS and PORT

Package

cl-wol.core.

Source

core.lisp.

Methods
Method: wake ((object magic-packet) address port)

6.1.4 Standalone methods

Method: print-object ((object magic-packet) stream)
Source

core.lisp.


6.1.5 Conditions

Condition: invalid-mac-address

A condition which is signalled upon an invalid MAC address

Package

cl-wol.core.

Source

core.lisp.

Direct superclasses

simple-error.

Direct methods

mac-address.

Direct slots
Slot: address
Initform

(quote (error "must specify mac address"))

Initargs

:address

Readers

mac-address.

Writers

This slot is read-only.

Condition: invalid-password

A condition which is signalled upon invalid SecureOn password

Package

cl-wol.core.

Source

core.lisp.

Direct superclasses

simple-error.

Direct methods

secureon-password.

Direct slots
Slot: password
Initform

(quote (error "must specify password"))

Initargs

:password

Readers

secureon-password.

Writers

This slot is read-only.

Condition: invalid-payload

A condition which is signalled when invalid payload is generated

Package

cl-wol.core.

Source

core.lisp.

Direct superclasses

simple-error.

Direct methods

payload.

Direct slots
Slot: payload
Initform

(quote (error "must specify payload"))

Initargs

:payload

Readers

payload.

Writers

This slot is read-only.


Previous: , Up: Public Interface   [Contents][Index]

6.1.6 Classes

Class: magic-packet

A class which represents the Magic Packet used to wake remote systems

Package

cl-wol.core.

Source

core.lisp.

Direct methods
Direct slots
Slot: address

Destination MAC address

Initform

(error "must specify mac address")

Initargs

:address

Readers

mac-octets.

Writers

This slot is read-only.

Slot: password

Optional SecureOn password

Initargs

:password

Readers

secureon-password.

Writers

This slot is read-only.


6.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

6.2.1 Ordinary functions

Function: add-host/command ()

Returns the command for adding hosts to the database file

Package

cl-wol.cli.

Source

add-host.lisp.

Function: add-host/handler (cmd)

Handler for the ‘add-host’ command

Package

cl-wol.cli.

Source

add-host.lisp.

Function: add-host/options ()

Returns the options of the ‘add-host’ command

Package

cl-wol.cli.

Source

add-host.lisp.

Function: db-execute (db-conn stmt &rest params)

Execute a given statement against the database

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: db-migrations-path ()

Returns the path to the migration files

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: delete-host/command ()

Returns the command for deleting hosts from the database file

Package

cl-wol.cli.

Source

delete-host.lisp.

Function: delete-host/handler (cmd)

Handler for the ‘delete-host’ command

Package

cl-wol.cli.

Source

delete-host.lisp.

Function: delete-host/options ()

Returns the options of the ‘delete-host’ command

Package

cl-wol.cli.

Source

delete-host.lisp.

Function: disconnect-db-conn (db-conn)

Disconnects from the database

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: get-host-from-db (db-conn name)

Fetches the host with the given NAME from the database

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: get-hosts-to-wake (cmd)

Returns the list of MAC addresses to wake up based on the provided options and arguments from the command-line

Package

cl-wol.cli.

Source

wake.lisp.

Function: init-db/command ()

Returns the command for initializing the database

Package

cl-wol.cli.

Source

init-db.lisp.

Function: init-db/handler (cmd)

Handler for the ‘init-db’ command

Package

cl-wol.cli.

Source

init-db.lisp.

Function: init-db/options ()

Returns the options of the ‘init-db’ command

Package

cl-wol.cli.

Source

init-db.lisp.

Function: list-hosts/command ()

Returns the command for listing hosts from the database file

Package

cl-wol.cli.

Source

list-hosts.lisp.

Function: list-hosts/handler (cmd)

Handler for the ‘list-hosts’ command

Package

cl-wol.cli.

Source

list-hosts.lisp.

Function: list-hosts/options ()

Returns the options of the ‘list-hosts’ command

Package

cl-wol.cli.

Source

list-hosts.lisp.

Function: make-db-conn (db-path)

Creates a new database connection to the given DB-PATH

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: migrate-db (db-conn)

Migrates the database to the latest version

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: print-doc/command ()

Returns a command which will print the app’s documentation

Package

cl-wol.cli.

Source

print-doc.lisp.

Function: print-doc/handler (cmd)
Package

cl-wol.cli.

Source

print-doc.lisp.

Function: table-columns (db-conn table)

Get the list of columns for a given table

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: table-info (db-conn table)

Get details about a given table

Package

cl-wol.cli.

Source

db-utils.lisp.

Function: top-level/command ()

Returns the top-level command

Package

cl-wol.cli.

Source

main.lisp.

Function: top-level/handler (cmd)

The top-level handler

Package

cl-wol.cli.

Source

main.lisp.

Function: top-level/sub-commands ()

Returns the list of top-level sub-commands

Package

cl-wol.cli.

Source

main.lisp.

Function: wake/command ()

Returns the command for waking up remote systems

Package

cl-wol.cli.

Source

wake.lisp.

Function: wake/handler (cmd)

The handler for the ‘wake’ command

Package

cl-wol.cli.

Source

wake.lisp.

Function: wake/options ()

Returns the options for the ‘wake’ command

Package

cl-wol.cli.

Source

wake.lisp.

Function: zsh-completions/command ()

Returns a command for generating Zsh completions script

Package

cl-wol.cli.

Source

zsh-completions.lisp.

Function: zsh-completions/handler (cmd)
Package

cl-wol.cli.

Source

zsh-completions.lisp.


6.2.2 Types

Type: simple-octet-vector (&optional length)
Package

cl-wol.core.

Source

core.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   D   E   F   G   I   L   M   P   S   T   W   Z  
Index Entry  Section

A
add-host/command: Private ordinary functions
add-host/handler: Private ordinary functions
add-host/options: Private ordinary functions

D
db-execute: Private ordinary functions
db-migrations-path: Private ordinary functions
delete-host/command: Private ordinary functions
delete-host/handler: Private ordinary functions
delete-host/options: Private ordinary functions
disconnect-db-conn: Private ordinary functions

E
encode-payload: Public generic functions
encode-payload: Public generic functions

F
Function, add-host/command: Private ordinary functions
Function, add-host/handler: Private ordinary functions
Function, add-host/options: Private ordinary functions
Function, db-execute: Private ordinary functions
Function, db-migrations-path: Private ordinary functions
Function, delete-host/command: Private ordinary functions
Function, delete-host/handler: Private ordinary functions
Function, delete-host/options: Private ordinary functions
Function, disconnect-db-conn: Private ordinary functions
Function, get-host-from-db: Private ordinary functions
Function, get-hosts-to-wake: Private ordinary functions
Function, init-db/command: Private ordinary functions
Function, init-db/handler: Private ordinary functions
Function, init-db/options: Private ordinary functions
Function, list-hosts/command: Private ordinary functions
Function, list-hosts/handler: Private ordinary functions
Function, list-hosts/options: Private ordinary functions
Function, main: Public ordinary functions
Function, make-db-conn: Private ordinary functions
Function, make-octet-vector: Public ordinary functions
Function, migrate-db: Private ordinary functions
Function, parse-hex-bytes: Public ordinary functions
Function, print-doc/command: Private ordinary functions
Function, print-doc/handler: Private ordinary functions
Function, table-columns: Private ordinary functions
Function, table-info: Private ordinary functions
Function, top-level/command: Private ordinary functions
Function, top-level/handler: Private ordinary functions
Function, top-level/sub-commands: Private ordinary functions
Function, wake/command: Private ordinary functions
Function, wake/handler: Private ordinary functions
Function, wake/options: Private ordinary functions
Function, zsh-completions/command: Private ordinary functions
Function, zsh-completions/handler: Private ordinary functions

G
Generic Function, encode-payload: Public generic functions
Generic Function, mac-address: Public generic functions
Generic Function, mac-octets: Public generic functions
Generic Function, make-magic-packet: Public generic functions
Generic Function, payload: Public generic functions
Generic Function, secureon-password: Public generic functions
Generic Function, wake: Public generic functions
get-host-from-db: Private ordinary functions
get-hosts-to-wake: Private ordinary functions

I
init-db/command: Private ordinary functions
init-db/handler: Private ordinary functions
init-db/options: Private ordinary functions

L
list-hosts/command: Private ordinary functions
list-hosts/handler: Private ordinary functions
list-hosts/options: Private ordinary functions

M
mac-address: Public generic functions
mac-address: Public generic functions
mac-address: Public generic functions
mac-octets: Public generic functions
mac-octets: Public generic functions
main: Public ordinary functions
make-db-conn: Private ordinary functions
make-magic-packet: Public generic functions
make-magic-packet: Public generic functions
make-magic-packet: Public generic functions
make-octet-vector: Public ordinary functions
Method, encode-payload: Public generic functions
Method, mac-address: Public generic functions
Method, mac-address: Public generic functions
Method, mac-octets: Public generic functions
Method, make-magic-packet: Public generic functions
Method, make-magic-packet: Public generic functions
Method, payload: Public generic functions
Method, print-object: Public standalone methods
Method, secureon-password: Public generic functions
Method, secureon-password: Public generic functions
Method, wake: Public generic functions
migrate-db: Private ordinary functions

P
parse-hex-bytes: Public ordinary functions
payload: Public generic functions
payload: Public generic functions
print-doc/command: Private ordinary functions
print-doc/handler: Private ordinary functions
print-object: Public standalone methods

S
secureon-password: Public generic functions
secureon-password: Public generic functions
secureon-password: Public generic functions

T
table-columns: Private ordinary functions
table-info: Private ordinary functions
top-level/command: Private ordinary functions
top-level/handler: Private ordinary functions
top-level/sub-commands: Private ordinary functions

W
wake: Public generic functions
wake: Public generic functions
wake/command: Private ordinary functions
wake/handler: Private ordinary functions
wake/options: Private ordinary functions

Z
zsh-completions/command: Private ordinary functions
zsh-completions/handler: Private ordinary functions

Jump to:   A   D   E   F   G   I   L   M   P   S   T   W   Z  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   2  
A   C   D   F   I   L   M   P   S   T   W   Z  
Index Entry  Section

2
20211222183337-add_hosts_table.down.sql: The cl-wol․cli/migrations/20211222183337-add_hosts_table․down․sql file
20211222183337-add_hosts_table.up.sql: The cl-wol․cli/migrations/20211222183337-add_hosts_table․up․sql file

A
add-host.lisp: The cl-wol․cli/cli/add-host․lisp file

C
cl-wol-cli-system: The cl-wol-cli-system package
cl-wol-core-system: The cl-wol-core-system package
cl-wol.cli: The cl-wol․cli system
cl-wol.cli: The cl-wol․cli package
cl-wol.cli.asd: The cl-wol․cli/cl-wol․cli․asd file
cl-wol.core: The cl-wol․core system
cl-wol.core: The cl-wol․core package
cl-wol.core.asd: The cl-wol․core/cl-wol․core․asd file
Class, magic-packet: Public classes
cli: The cl-wol․cli/cli module
Condition, invalid-mac-address: Public conditions
Condition, invalid-password: Public conditions
Condition, invalid-payload: Public conditions
core: The cl-wol․core/core module
core.lisp: The cl-wol․core/core/core․lisp file

D
db-utils.lisp: The cl-wol․cli/cli/db-utils․lisp file
delete-host.lisp: The cl-wol․cli/cli/delete-host․lisp file

F
File, 20211222183337-add_hosts_table.down.sql: The cl-wol․cli/migrations/20211222183337-add_hosts_table․down․sql file
File, 20211222183337-add_hosts_table.up.sql: The cl-wol․cli/migrations/20211222183337-add_hosts_table․up․sql file
File, add-host.lisp: The cl-wol․cli/cli/add-host․lisp file
File, cl-wol.cli.asd: The cl-wol․cli/cl-wol․cli․asd file
File, cl-wol.core.asd: The cl-wol․core/cl-wol․core․asd file
File, core.lisp: The cl-wol․core/core/core․lisp file
File, db-utils.lisp: The cl-wol․cli/cli/db-utils․lisp file
File, delete-host.lisp: The cl-wol․cli/cli/delete-host․lisp file
File, init-db.lisp: The cl-wol․cli/cli/init-db․lisp file
File, list-hosts.lisp: The cl-wol․cli/cli/list-hosts․lisp file
File, main.lisp: The cl-wol․cli/cli/main․lisp file
File, package.lisp: The cl-wol․cli/cli/package․lisp file
File, print-doc.lisp: The cl-wol․cli/cli/print-doc․lisp file
File, wake.lisp: The cl-wol․cli/cli/wake․lisp file
File, zsh-completions.lisp: The cl-wol․cli/cli/zsh-completions․lisp file

I
init-db.lisp: The cl-wol․cli/cli/init-db․lisp file
invalid-mac-address: Public conditions
invalid-password: Public conditions
invalid-payload: Public conditions

L
list-hosts.lisp: The cl-wol․cli/cli/list-hosts․lisp file

M
magic-packet: Public classes
main.lisp: The cl-wol․cli/cli/main․lisp file
migrations: The cl-wol․cli/migrations module
Module, cli: The cl-wol․cli/cli module
Module, core: The cl-wol․core/core module
Module, migrations: The cl-wol․cli/migrations module

P
Package, cl-wol-cli-system: The cl-wol-cli-system package
Package, cl-wol-core-system: The cl-wol-core-system package
Package, cl-wol.cli: The cl-wol․cli package
Package, cl-wol.core: The cl-wol․core package
package.lisp: The cl-wol․cli/cli/package․lisp file
print-doc.lisp: The cl-wol․cli/cli/print-doc․lisp file

S
simple-octet-vector: Private types
System, cl-wol.cli: The cl-wol․cli system
System, cl-wol.core: The cl-wol․core system

T
Type, simple-octet-vector: Private types

W
wake.lisp: The cl-wol․cli/cli/wake․lisp file

Z
zsh-completions.lisp: The cl-wol․cli/cli/zsh-completions․lisp file

Jump to:   2  
A   C   D   F   I   L   M   P   S   T   W   Z