Cutting release 0.3.0

NEWS

@@ -1,97 +1,110 @@
 elmpd News -- history of user-visible changes           -*- outline -*-
 
-* 0.2.4 build
+* 0.3 builds
+
+** 0.3.0
+
+*** User-visible changes
+
+**** Add two new functions
+
+Added `elmpd-conn-status' and `elmpd-conn-failed-p'.
+* 0.2 builds
+
+** 0.2.4
 
 No user-visible changes.
-* 0.2.3 build
+** 0.2.3
 
 No user-visible changes.
-* 0.2.2 build
+** 0.2.2
 
-** User-visible changes
+*** User-visible changes
 
-*** Added 'elmpd-chain'
+**** Added 'elmpd-chain'
 
 You can now chain commands with more convenient syntax.
-* 0.2.1 build
+** 0.2.1
+
+*** Bug fixes
 
-** Bug fixes
+**** 'elmpd-send' was sending "noidle" in the old way
+** 0.2.0
 
-*** 'elmpd-send' was sending "noidle" in the old way
-* 0.2.0 build
+*** User-visible changes
 
-** User-visible changes
+**** Support for command-lists
+* 0.1 builds
 
-*** Support for command-lists
-* 0.1.9 build
+** 0.1.9
 
-** Bug fixes
+*** Bug fixes
 
-*** Handle no current command in failure responses
-* 0.1.8 release
+**** Handle no current command in failure responses
+** 0.1.8
 
-** User-visible changes
+*** User-visible changes
 
-*** Minor changes to the docs
-* 0.1.7 build
+**** Minor changes to the docs
+** 0.1.7
 
-** User-visible changes
+*** User-visible changes
 
-*** Byte-compiled functions are handled better when logging
+**** Byte-compiled functions are handled better when logging
 
-*** All keyword arguments to `elmpd-connect' are validated
+**** All keyword arguments to `elmpd-connect' are validated
 
 An error will be signalled if any are un-recognized.
-* 0.1.6 build
+** 0.1.6
 
-** User-visible changes
+*** User-visible changes
 
 The `elmpd' logging facility now takes a facility field; the idea is that packages built on top of `elmpd' can re-use its logging feature while still distinguishing their log statements.
 
-* 0.1.5 build
+** 0.1.5
 
-** User-visible changes
+*** User-visible changes
 
 Callers can explicitly rule-out local sockets by setting `elmpd-socket' to nil before calling `elmpd-connect'.
 
-* 0.1.4 build
+** 0.1.4
 
-** User-visible changes
+*** User-visible changes
 
-*** Support for local Unix sockets
+**** Support for local Unix sockets
 
-* 0.1.3 build
+** 0.1.3
 
-** User-visible changes
+*** User-visible changes
 
-*** Signature change for idle callbacks
+**** Signature change for idle callbacks
 
 This commit changes the signature for idle callbacks; instead of receiving the response text ("changed: foo\nchanged: bar\n...") as its second parameter, it will now receive a list of symbols indicating the changed sub-system(s) (e.g. '(foo bar)).
 
-* 0.1.2 build
+** 0.1.2
 
-** Bug fixes
+*** Bug fixes
 
-*** No longer use regex to find successful responses
+**** No longer use regex to find successful responses
 
 For reasons unknown, the author obtusely chose to use an
 overly-complex regex to detect successful responses. This commit fixes
 that regrettable choice.
 
-* 0.1.1 build
+** 0.1.1
 
-** User-visible changes
+*** User-visible changes
 
-*** Added =elmpd-clear-log=
+**** Added =elmpd-clear-log=
 
-*** =elmpd-connection= objects being pretty-printed in log messages
+**** =elmpd-connection= objects being pretty-printed in log messages
 
-** Bug fixes
+*** Bug fixes
 
-*** "noidle" response not being processed
+**** "noidle" response not being processed
 
 Fixed a nasty bug wherein the "OK\n" response from "noidle" commands wasn't being processed correctly
 
-* 0.1.0 release
+** 0.1.0
 
 Initial release.

README.org

@@ -1,6 +1,6 @@
 #+TITLE: elmpd
 #+DESCRIPTION: A tight, async mpd library in Emacs Lisp
-#+DATE: <2024-02-08 Thu 06:25>
+#+DATE: <2024-08-30 Fri 07:47>
 #+AUTHOR: sp1ff
 #+EMAIL: sp1ff@pobox.com
 #+AUTODATE: t
@@ -13,20 +13,18 @@
 * Introduction
 
 [[https://github.com/sp1ff/elmpd][elmpd]] is a tight, asynchronous, ergonomic [[https://www.musicpd.org/][MPD]] client library in Emacs Lisp.
-
 * Prerequisites
 
 Emacs 25.1.
-
 * Installing
 
-The simplest way to install [[https://github.com/sp1ff/elmpd][elmpd]] is available from [[https://melpa.org][MELPA]].
+The simplest way to install [[https://github.com/sp1ff/elmpd][elmpd]] is from [[https://melpa.org][MELPA]].
 
 I'm now making GitHub releases that include Autotools source distributions:
 
 #+BEGIN_SRC bash
-curl -L --output elmpd-0.2.4.tar.gz  https://github.com/sp1ff/scribbu/archive/v0.5.tar.gz
-tar xf elmpd-0.2.4.tar.gz && cd elmpd-0.2.4
+curl -L --output elmpd-0.3.0.tar.gz https://github.com/sp1ff/elmpd/releases/download/0.2.4/elmpd-0.2.4.tar.gz  
+tar xf elmpd-0.3.0.tar.gz && cd elmpd-0.3.0
 ./configure && make all check
 sudo make install
 #+END_SRC
@@ -40,7 +38,6 @@ cd elmpd
 ./configure && make all check
 sudo make install
 #+END_SRC
-
 * Getting Started
 
 ** Creating Connections
@@ -53,13 +50,11 @@ Create an MPD connection by calling =elmpd-connect=; this will return an =elmpd-
 There are two idioms I've seen in MPD client libraries for sending commands while receiving notifications of server-side changes:
 
     1. just maintain two connections (e.g. [[https://github.com/vincent-petithory/mpdfav][mpdfav]]); issue the "idle" command on one, send commands on the other
-
     2. use one connection, issue the "idle" command, and when asked to issue another command, send "noidle", issue the requested command, collect the response, and then send "idle" again (e.g. [[https://gitea.petton.fr/mpdel/libmpdel][libmpdel]]).  Note that this is not a race condition per the MPD [[https://www.musicpd.org/doc/html/protocol.html#idle][docs]] -- any server-side changes that took place while processing the command will be saved & returned on "idle"
 
 Since =elmpd= is a library, I do not make that choice here, but rather support both styles. See the docstring for =elmpd-connect= on how to configure your new connection in either way.
 
 The implementation is callback-based; each connection comes at the cost of a single socket plus whatever memory is needed to do the text processing in handling responses. In particular, I declined to use =tq= despite the natural fit because I didn't want to use a buffer for each connection, as well.
-
 ** Invoking Commands
 
 Send commands via =elmpd-send=. For example, to start MPD playing:
@@ -69,7 +64,7 @@ Send commands via =elmpd-send=. For example, to start MPD playing:
     (elmpd-send conn "play"))
 #+END_SRC
 
-Sends the "play" command to your MPD server listening on port 6600 on localhost. Note that this code will likely return *before* anything actually happens. As mentioned [[#creating_connections][above]], =elmpd-connect= returns immediately after creating the network process; it only reads & parses the MPD greeting asynchronously. Likewise, =elmpd-send= only queues up the "play" command; it will actually be sent & its response read in the background.
+sends the "play" command to your MPD server listening on port 6600 on localhost. Note that this code will likely return *before* anything actually happens. As mentioned [[#creating_connections][above]], =elmpd-connect= returns immediately after creating the network process; it only reads & parses the MPD greeting asynchronously. Likewise, =elmpd-send= only queues up the "play" command; it will actually be sent & its response read in the background.
 
 If you'd like to do something with the response, you can provide a callback:
 
@@ -181,15 +176,13 @@ As with Javascript futures, this quickly became inconvenient & difficult to read
      :or-else
      (message "Failed to increase volume: %s" rsp)))
 #+END_SRC
-
 * Motivation & Design Philosphy
 
 [[https://github.com/DamienCassou][Damien Cassou]], the author of [[https://github.com/mpdel/mpdel][mpdel]] and [[https://gitea.petton.fr/mpdel/libmpdel][libmpdel]], [[https://github.com/sp1ff/elmpd/issues/1][reached out]] to ask "Why elmpd?" His question prompted me to clarify my thoughts around this project & I've adapted my response here.
 
 I've looked at a few [[https://www.musicpd.org/][MPD]] clients, including [[https://github.com/mpdel/mpdel][mpdel]]. As I experimented with my workflow, however, I found myself wanting _less_ functionality: rather than interacting with a fully-featured client, I just wanted to skip to the next song while I was editing code, for example. I customize my mode line heavily, and I wanted a little bit of logic to add the current track to the mode line & keep it up-to-date. I have written a companion [[https://github.com/sp1ff/mpdpopm][daemon]] to MPD that maintains ratings & play counts; I just needed a little function that would let me rate the current track while I was reading mail (in Emacs, of course!)
 
-My next move was to read through a number of client libraries for inspiration, both in C & Emacs LISP. Many of them had strong opinions on how one should talk to MPD. Having been programming MPD for a while I had come to appreciate its simplicity (after all, one can program it from bash by simply =echo=-ing  commands to =/dev/tcp/$host/$port=). I spent time earlier this year learning to write asynchronous Rust, and that inspired me to see how simple I could make this using just callbacks. At the time of this writing, =elmpd= exports just two functions: =elmpd-connect= & =elmpd-send=. Each connection consumes a socket & optionally a callback-- that's it (no buffer, no transaction queue). Put another way, if other libraries are Gnus (featureful, encourages you to read your e-mail in a certain way), then elmpd is [[https://mailutils.org/][Mailutils]] (small utilities that leave it up to the user to assemble them into something useful).
-
+My next move was to read through a number of client libraries for inspiration, both in C & Emacs LISP. Many of them had strong opinions on how one should talk to MPD. Having been programming MPD for a while I had come to appreciate its simplicity (after all, one can program it from bash by simply =echo=-ing  commands to =/dev/tcp/$host/$port=). My experience with async Rust inspired me to see how simple I could make this using just callbacks. =elmpd= exports two primary functions: =elmpd-connect= & =elmpd-send=. Each connection consumes a socket & optionally a callback-- that's it (no buffer, no transaction queue). Put another way, if other libraries are Gnus (featureful, encourages you to read your e-mail in a certain way), then elmpd is [[https://mailutils.org/][Mailutils]] (small utilities that leave it up to the user to assemble them into something useful).
 * Status & Roadmap
 
 I've been using the library for some time with good results. The bulk of the work has been in getting the asynchronous logic right; as such it is not very featureful. It is ripe for being used to build up a more caller-friendly API:  =(something-play)= instead of:
@@ -199,4 +192,6 @@ I've been using the library for some time with good results. The bulk of the wor
     (elmpd-send conn "play"))
 #+END_SRC
 
-I've written a separate package, [[https://github.com/mpdmacs][mpdmacs]], that hopefully does so in a generic way. I've recently, finally, gotten my head around LISP macros (short story: the code _really is_ just data!) and so I've just implemented =elmpd-chain=; my next project for this package is to re-implement my other packages built on top of this in terms of =elmpd-chain= & refine it.
+I've written a separate package, [[https://github.com/mpdmacs][mpdmacs]], that hopefully does so in a generic way.
+
+Comments, suggestions & bug reports welcome in the [[https://github.com/sp1ff/elmpd/issues][issues]] or at sp1ff@pobox.com.

configure.ac

@@ -1,4 +1,4 @@
-AC_INIT([elmpd], [0.2.4], [sp1ff@poboxcom], [elmpd], [https://github.com/sp1ff/elmpd])
+AC_INIT([elmpd], [0.3.0], [sp1ff@poboxcom], [elmpd], [https://github.com/sp1ff/elmpd])
 AC_CONFIG_AUX_DIR([build-aux])
 AC_CONFIG_SRCDIR([elmpd.el])
 AM_INIT_AUTOMAKE([-Wall -Werror gnits std-options dist-bzip2 dist-xz dist-zstd])

elmpd.el

@@ -3,7 +3,7 @@
 ;; Copyright (C) 2020-2024 Michael Herstine <sp1ff@pobox.com>
 
 ;; Author: Michael Herstine <sp1ff@pobox.com>
-;; Version: 0.2.4
+;; Version: 0.3.0
 ;; Keywords: comm
 ;; Package-Requires: ((emacs "25.1"))
 ;; URL: https://github.com/sp1ff/elmpd
@@ -67,7 +67,7 @@
 
 (require 'cl-lib)
 
-(defconst elmpd-version "0.2.4")
+(defconst elmpd-version "0.3.0")
 
 ;;; Logging-- useful for debugging asynchronous functions