From 98b26ff13eeb8a9f730801720c4cba30eba9e61d Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Thu, 31 Mar 2016 06:41:42 -0700
Subject: Define a sock-peer syntactic place.

* share/txr/stdlib/socket.tl (sock-peer): Syntactic
place defined, allowing (set (sock-peer sock) addr).

* txr.1: Documented sock-peer as accessor and sock-set-peer.
---
 share/txr/stdlib/socket.tl |  6 ++++++
 txr.1                      | 49 ++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/share/txr/stdlib/socket.tl b/share/txr/stdlib/socket.tl
index 1c54c6eb..b6ad135e 100644
--- a/share/txr/stdlib/socket.tl
+++ b/share/txr/stdlib/socket.tl
@@ -142,3 +142,9 @@
              (cand-prefix [pieces 0..(trunc (+ w 15) 16)])
              (prefix (if (search cand-prefix '(0 0)) pieces cand-prefix)))
         `@(sys:in6addr-condensed-text prefix)/@(or width w)`))))
+
+(defplace (sock-peer sock) body
+  (getter setter
+    ^(macrolet ((,getter () ^(sock-peer ',',sock))
+                (,setter (val) ^(sock-set-peer ,',sock ,val)))
+       ,body)))
diff --git a/txr.1 b/txr.1
index f61a1216..c2f9e06d 100644
--- a/txr.1
+++ b/txr.1
@@ -37753,12 +37753,19 @@ data for a new datagram. The
 function implicitly flushes the stream in the same way, and thus also
 potentially generates a datagram.
 
-A client-style datagram stream is explicitly connected to a peer with the
+A client-style datagram stream can be explicitly connected to a peer with the
 .code sock-connect
-function and sends messages to that peer. This is similar to connecting a datagram socket using the
-C library
+function. This is equivalent to connecting a
+datagram socket using the C library
 .code connect
-function.
+function. Writes on the stream will be transmitted using the C library function
+.codn send .
+A client-style datagram stream can also be "soft-connected" to a
+peer using the
+.code sock-set-peer
+function. Writes on the stream will transmit data using the C library function
+.code sendto
+to the peer address.
 
 A datagram server program which needs
 to communicate using multiple peers is implemented by means of the
@@ -38191,14 +38198,15 @@ An exception of type
 .code type-error
 is thrown for other stream types.
 
-.coNP Function @ sock-peer
+.coNP Accessor @ sock-peer
 .synb
 .mets (sock-peer << socket )
+.mets (set (sock-peer << socket ) << address )
 .syne
 .desc
 If
 .meta socket
-is a socket stream connected to a remote peer, this
+is a socket stream connected to a remote peer,
 this function returns the socket address representing
 the remote peer. The return value is one of the concrete
 structure types derived from the
@@ -38221,6 +38229,12 @@ socket was produced as the return value of the
 .code sock-accept
 function. No other socket stream has a peer.
 
+Assigning an address to a
+.code sock-peer
+form is equivalent to using
+.code sock-set-peer
+to set the address.
+
 Implementation note: the
 .code sock-peer
 function does not use the
@@ -38229,6 +38243,29 @@ C library function; the association between a stream and
 .code sockaddr
 struct is maintained by \*(TX.
 
+.coNP Function @ sock-set-peer
+.synb
+.mets (sock-set-peer < socket << address )
+.syne
+.desc
+The
+.code sock-set-peer
+function stores
+.meta address
+into
+.meta socket
+as that socket's peer.
+
+Subsequently, the
+.code sock-peer
+function will retrieve that address.
+
+If
+.meta address
+is not an appropriate address object in the address family of
+.metn socket ,
+the behavior is unspecified.
+
 .coNP Function @ sock-connect
 .synb
 .mets (sock-connect < socket < address <> [ timeout-usec ])
-- 
cgit v1.2.3