[Libguestfs] [libnbd PATCH 3/6] state_machine_generator: wrap state comments in lib/states.{h, c}

[Eric Blake]

On Thu, May 11, 2023 at 08:45:25AM +0200, Laszlo Ersek wrote:
> On 5/10/23 17:14, Eric Blake wrote:
> > On Wed, May 10, 2023 at 01:48:11PM +0200, Laszlo Ersek wrote:
> >> Wrap those comments in "lib/states.h" and "lib/states.c" that describe the
> >> automaton's states.
> >>
> >> Example changes from "lib/states.h":
> >>
> >>>    /* CONNECT_TCP.CONNECT: Initial call to connect(2) on a TCP socket */
> >>>    STATE_CONNECT_TCP_CONNECT,
> >>>
> >>> -  /* CONNECT_TCP.CONNECTING: Connecting to the remote server over a TCP socket */
> >>> +  /* CONNECT_TCP.CONNECTING: Connecting to the remote server over a TCP socket
> >>> +   */
> >
> > This one looks a bit unusual; I didn't find any instances of this
> > style in existing hand-written comments (
> >   git grep -B1 '^[:space:]*\*/$' | grep '/\*'

> This comment folding style (breaking off just the terminating '*/') is
> common at least in QEMU, as I recall:
> 
>   git grep -h -B1 '^ *\*/$' | grep  -A1 '^ */\*'
> 
> ... The same command also returns 5 hits in libnbd:
> 
> > /* Return true if size is a multiple of align. align must be power of 2.
> >  */

Oops, you proved me wrong.

> 
> Interestingly, your variant of the same grep does not produce any
> output, and I don't immediately see why...
> 
> Ah, I see now. Character classes such as [:space:] *only* work within
> bracket expressions. POSIX writes:
> 
>     The character sequences "[.", "[=", and "[:" ( <left-square-bracket>
>     followed by a <period>, <equals-sign>, or <colon>) shall be special
>     inside a bracket expression and are used to delimit collating
>     symbols, equivalence class expressions, and character class
>     expressions. These symbols shall be followed by a valid expression
>     and the matching terminating sequence ".]", "=]", or ":]", as
>     described in the following items.
> 
> In other words, the sequence "[:space:]" in itself is just a (weird)
> bracket expression, matching the 's', 'p', 'a', 'c', 'e', and ':'
> (twice) characters.

Yeah, and I should know that.  There is an exception ("tr '[:alpha:]"
... is allowed to operate on a character class without needing a
bracket expression, since it is not parsing a regex in the first
place), but I was indeed typing too fast and messed up on my grep.

> 
> If we want [:space:] to function as a character class, it must be
> embedded inside a bracket expression. So the following works:
> 
>   git grep -B1 '^[[:space:]]*\*/$' | grep '/\*'
> 
> (And then this form allows for other expressions alongside the character
> class within the bracket expression -- for example, *further* character
> classes.)
> 
> In fact this is the first time I've myself ever understood how character
> classes are supposed to be used in grep :/

Not my first time, but obviously something I don't do frequently
enough that I still tend to forget it.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org