2 -- Implementation of the main LuaIRC module
6 local constants = require 'irc.constants'
7 local irc_debug = require 'irc.debug'
8 local message = require 'irc.message'
9 local misc = require 'irc.misc'
10 local socket = require 'socket'
11 local os = require 'os'
12 local string = require 'string'
13 local table = require 'table'
17 -- LuaIRC - IRC framework written in Lua
22 _VERSION = 'LuaIRC 0.2'
26 local Channel = base.require 'irc.channel'
29 -- local variables {{{
43 local requestinfo = {whois = {}}
45 local ctcp_handlers = {}
51 TIMEOUT = 60 -- connection timeout
52 NETWORK = "localhost" -- default network
53 PORT = 6667 -- default port
54 NICK = "luabot" -- default nick
55 USERNAME = "LuaIRC" -- default username
56 REALNAME = "LuaIRC" -- default realname
57 DEBUG = false -- whether we want extra debug information
58 OUTFILE = nil -- file to send debug output to - nil is stdout
61 -- private functions {{{
63 local function main_loop_iter()
64 if #rsockets == 0 and #wsockets == 0 then return false end
65 local rready, wready, err = socket.select(rsockets, wsockets)
66 if err then irc_debug._err(err); return false; end
68 for _, sock in base.ipairs(rready) do
69 local cb = socket.protect(rcallbacks[sock])
70 local ret, err = cb(sock)
72 irc_debug._warn("socket error: " .. err)
73 _unregister_socket(sock, 'r')
77 for _, sock in base.ipairs(wready) do
78 local cb = socket.protect(wcallbacks[sock])
79 local ret, err = cb(sock)
81 irc_debug._warn("socket error: " .. err)
82 _unregister_socket(sock, 'w')
90 -- begin_main_loop {{{
91 local function begin_main_loop()
92 while main_loop_iter() do end
96 -- incoming_message {{{
97 local function incoming_message(sock)
98 local raw_msg = socket.try(sock:receive())
99 irc_debug._message("RECV", raw_msg)
100 local msg = message._parse(raw_msg)
101 misc._try_call_warn("Unhandled server message: " .. msg.command,
102 handlers["on_" .. msg.command:lower()],
103 (misc.parse_user(msg.from)), base.unpack(msg.args))
109 -- internal message handlers {{{
110 -- command handlers {{{
112 function handlers.on_nick(from, new_nick)
113 for chan in channels() do
114 chan:_change_nick(from, new_nick)
116 misc._try_call(on_nick_change, new_nick, from)
121 function handlers.on_join(from, chan)
122 base.assert(serverinfo.channels[chan],
123 "Received join message for unknown channel: " .. chan)
124 if serverinfo.channels[chan].join_complete then
125 serverinfo.channels[chan]:_add_user(from)
126 misc._try_call(on_join, serverinfo.channels[chan], from)
132 function handlers.on_part(from, chan, part_msg)
133 -- don't assert on chan here, since we get part messages for ourselves
134 -- after we remove the channel from the channel list
135 if not serverinfo.channels[chan] then return end
136 if serverinfo.channels[chan].join_complete then
137 serverinfo.channels[chan]:_remove_user(from)
138 misc._try_call(on_part, serverinfo.channels[chan], from, part_msg)
144 function handlers.on_mode(from, to, mode_string, ...)
145 local dir = mode_string:sub(1, 1)
146 mode_string = mode_string:sub(2)
149 if to:sub(1, 1) == "#" then
150 -- handle channel mode requests {{{
151 base.assert(serverinfo.channels[to],
152 "Received mode change for unknown channel: " .. to)
153 local chan = serverinfo.channels[to]
155 for i = 1, mode_string:len() do
156 local mode = mode_string:sub(i, i)
157 local target = args[ind]
158 -- channel modes other than op/voice will be implemented as
159 -- information request commands
160 if mode == "o" then -- channel op {{{
161 chan:_change_status(target, dir == "+", "o")
162 misc._try_call(({["+"] = on_op, ["-"] = on_deop})[dir],
166 elseif mode == "v" then -- voice {{{
167 chan:_change_status(target, dir == "+", "v")
168 misc._try_call(({["+"] = on_voice, ["-"] = on_devoice})[dir],
175 elseif from == to then
176 -- handle user mode requests {{{
177 -- TODO: make users more easily accessible so this is actually
178 -- reasonably possible
179 for i = 1, mode_string:len() do
180 local mode = mode_string:sub(i, i)
181 if mode == "i" then -- invisible {{{
183 elseif mode == "s" then -- server messages {{{
185 elseif mode == "w" then -- wallops messages {{{
187 elseif mode == "o" then -- ircop {{{
197 function handlers.on_topic(from, chan, new_topic)
198 base.assert(serverinfo.channels[chan],
199 "Received topic message for unknown channel: " .. chan)
200 serverinfo.channels[chan]._topic.text = new_topic
201 serverinfo.channels[chan]._topic.user = (misc.parse_user(from))
202 serverinfo.channels[chan]._topic.time = os.time()
203 if serverinfo.channels[chan].join_complete then
204 misc._try_call(on_topic_change, serverinfo.channels[chan])
210 function handlers.on_invite(from, to, chan)
211 misc._try_call(on_invite, from, chan)
216 function handlers.on_kick(from, chan, to)
217 base.assert(serverinfo.channels[chan],
218 "Received kick message for unknown channel: " .. chan)
219 if serverinfo.channels[chan].join_complete then
220 serverinfo.channels[chan]:_remove_user(to)
221 misc._try_call(on_kick, serverinfo.channels[chan], to, from)
227 function handlers.on_privmsg(from, to, msg)
228 local msgs = ctcp._ctcp_split(msg, true)
229 for _, v in base.ipairs(msgs) do
230 if base.type(v) == "string" then
231 -- normal message {{{
232 if to:sub(1, 1) == "#" then
233 base.assert(serverinfo.channels[to],
234 "Received channel msg from unknown channel: " .. to)
235 misc._try_call(on_channel_msg, serverinfo.channels[to], from, v)
237 misc._try_call(on_private_msg, from, v)
240 elseif base.type(v) == "table" then
242 local words = misc._split(v[1])
243 local received_command = words[1]
244 local cb = "on_" .. received_command:lower()
245 table.remove(words, 1)
246 -- not using try_call here because the ctcp specification requires
247 -- an error response to nonexistant commands
248 if base.type(ctcp_handlers[cb]) == "function" then
249 ctcp_handlers[cb](from, to, table.concat(words, " "))
251 notice(from, {"ERRMSG Unknown query: " .. received_command})
260 function handlers.on_notice(from, to, msg)
261 local msgs = ctcp._ctcp_split(msg, true)
262 for _, v in base.ipairs(msgs) do
263 if base.type(v) == "string" then
264 -- normal message {{{
265 if to:sub(1, 1) == "#" then
266 base.assert(serverinfo.channels[to],
267 "Received channel msg from unknown channel: " .. to)
268 misc._try_call(on_channel_notice, serverinfo.channels[to],
271 misc._try_call(on_private_notice, from, v)
274 elseif base.type(v) == "table" then
276 local words = misc._split(v[1])
277 local command = words[1]:lower()
278 table.remove(words, 1)
279 misc._try_call_warn("Unknown CTCP message: " .. command,
280 ctcp_handlers["on_rpl_"..command], from, to,
281 table.concat(words, ' '))
289 function handlers.on_quit(from, quit_msg)
290 for name, chan in base.pairs(serverinfo.channels) do
291 chan:_remove_user(from)
293 misc._try_call(on_quit, from, quit_msg)
298 -- respond to server pings to make sure it knows we are alive
299 function handlers.on_ping(from, respond_to)
300 send("PONG", respond_to)
305 -- server replies {{{
307 -- catch topic changes
308 function handlers.on_rpl_topic(from, chan, topic)
309 base.assert(serverinfo.channels[chan],
310 "Received topic information about unknown channel: " .. chan)
311 serverinfo.channels[chan]._topic.text = topic
315 -- on_rpl_notopic {{{
316 function handlers.on_rpl_notopic(from, chan)
317 base.assert(serverinfo.channels[chan],
318 "Received topic information about unknown channel: " .. chan)
319 serverinfo.channels[chan]._topic.text = ""
323 -- on_rpl_topicdate {{{
324 -- "topic was set by <user> at <time>"
325 function handlers.on_rpl_topicdate(from, chan, user, time)
326 base.assert(serverinfo.channels[chan],
327 "Received topic information about unknown channel: " .. chan)
328 serverinfo.channels[chan]._topic.user = user
329 serverinfo.channels[chan]._topic.time = base.tonumber(time)
333 -- on_rpl_namreply {{{
334 -- handles a NAMES reply
335 function handlers.on_rpl_namreply(from, chanmode, chan, userlist)
336 base.assert(serverinfo.channels[chan],
337 "Received user information about unknown channel: " .. chan)
338 serverinfo.channels[chan]._chanmode = constants.chanmodes[chanmode]
339 local users = misc._split(userlist)
340 for k,v in base.ipairs(users) do
341 if v:sub(1, 1) == "@" or v:sub(1, 1) == "+" then
342 local nick = v:sub(2)
343 serverinfo.channels[chan]:_add_user(nick, v:sub(1, 1))
345 serverinfo.channels[chan]:_add_user(v)
351 -- on_rpl_endofnames {{{
352 -- when we get this message, the channel join has completed, so call the
354 function handlers.on_rpl_endofnames(from, chan)
355 base.assert(serverinfo.channels[chan],
356 "Received user information about unknown channel: " .. chan)
357 if not serverinfo.channels[chan].join_complete then
358 misc._try_call(on_me_join, serverinfo.channels[chan])
359 serverinfo.channels[chan].join_complete = true
364 -- on_rpl_welcome {{{
365 function handlers.on_rpl_welcome(from)
374 -- on_rpl_yourhost {{{
375 function handlers.on_rpl_yourhost(from, msg)
376 serverinfo.host = from
380 -- on_rpl_motdstart {{{
381 function handlers.on_rpl_motdstart(from)
387 function handlers.on_rpl_motd(from, motd)
388 serverinfo.motd = (serverinfo.motd or "") .. motd .. "\n"
392 -- on_rpl_endofmotd {{{
393 function handlers.on_rpl_endofmotd(from)
394 if not serverinfo.connected then
395 serverinfo.connected = true
396 serverinfo.connecting = false
397 misc._try_call(on_connect)
402 -- on_rpl_whoisuser {{{
403 function handlers.on_rpl_whoisuser(from, nick, user, host, star, realname)
405 requestinfo.whois[nick].user = user
406 requestinfo.whois[nick].host = host
407 requestinfo.whois[nick].realname = realname
411 -- on_rpl_whoischannels {{{
412 function handlers.on_rpl_whoischannels(from, nick, channel_list)
414 if not requestinfo.whois[nick].channels then
415 requestinfo.whois[nick].channels = {}
417 for _, channel in base.ipairs(misc._split(channel_list)) do
418 table.insert(requestinfo.whois[nick].channels, channel)
423 -- on_rpl_whoisserver {{{
424 function handlers.on_rpl_whoisserver(from, nick, server, serverinfo)
426 requestinfo.whois[nick].server = server
427 requestinfo.whois[nick].serverinfo = serverinfo
432 function handlers.on_rpl_away(from, nick, away_msg)
434 if requestinfo.whois[nick] then
435 requestinfo.whois[nick].away_msg = away_msg
440 -- on_rpl_whoisoperator {{{
441 function handlers.on_rpl_whoisoperator(from, nick)
442 requestinfo.whois[nick:lower()].is_oper = true
446 -- on_rpl_whoisidle {{{
447 function handlers.on_rpl_whoisidle(from, nick, idle_seconds)
448 requestinfo.whois[nick:lower()].idle_time = idle_seconds
452 -- on_rpl_endofwhois {{{
453 function handlers.on_rpl_endofwhois(from, nick)
455 local cb = table.remove(icallbacks.whois[nick], 1)
456 cb(requestinfo.whois[nick])
457 requestinfo.whois[nick] = nil
458 if #icallbacks.whois[nick] > 0 then send("WHOIS", nick)
459 else icallbacks.whois[nick] = nil
464 -- on_rpl_version {{{
465 function handlers.on_rpl_version(from, version, server, comments)
466 local cb = table.remove(icallbacks.serverversion[server], 1)
467 cb({version = version, server = server, comments = comments})
468 if #icallbacks.serverversion[server] > 0 then send("VERSION", server)
469 else icallbacks.serverversion[server] = nil
475 function on_rpl_time(from, server, time)
476 local cb = table.remove(icallbacks.servertime[server], 1)
477 cb({time = time, server = server})
478 if #icallbacks.servertime[server] > 0 then send("TIME", server)
479 else icallbacks.servertime[server] = nil
488 function ctcp_handlers.on_action(from, to, message)
489 if to:sub(1, 1) == "#" then
490 base.assert(serverinfo.channels[to],
491 "Received channel msg from unknown channel: " .. to)
492 misc._try_call(on_channel_act, serverinfo.channels[to], from, message)
494 misc._try_call(on_private_act, from, message)
500 -- TODO: can we not have this handler be registered unless the dcc module is
502 function ctcp_handlers.on_dcc(from, to, message)
503 local type, argument, address, port, size = base.unpack(misc._split(message, " ", nil, '"', '"'))
504 if type == "SEND" then
505 if misc._try_call(on_dcc, from, to, argument, address, port, size) then
506 dcc._accept(argument, address, port)
508 elseif type == "CHAT" then
509 -- TODO: implement this? do people ever use this?
515 function ctcp_handlers.on_version(from, to)
516 notice(from, {"VERSION " .. _VERSION .. " running under " .. base._VERSION .. " with " .. socket._VERSION})
521 function ctcp_handlers.on_errmsg(from, to, message)
522 notice(from, {"ERRMSG " .. message .. "No error has occurred"})
527 function ctcp_handlers.on_ping(from, to, timestamp)
528 notice(from, {"PING " .. timestamp})
533 function ctcp_handlers.on_time(from, to)
534 notice(from, {"TIME " .. os.date()})
541 -- actions are handled the same, notice or not
542 ctcp_handlers.on_rpl_action = ctcp_handlers.on_action
545 -- on_rpl_version {{{
546 function ctcp_handlers.on_rpl_version(from, to, version)
547 local cb = table.remove(icallbacks.ctcp_version[from], 1)
548 cb({version = version, nick = from})
549 if #icallbacks.ctcp_version[from] > 0 then say(from, {"VERSION"})
550 else icallbacks.ctcp_version[from] = nil
556 function ctcp_handlers.on_rpl_errmsg(from, to, message)
557 try_call(on_ctcp_error, from, to, message)
562 function ctcp_handlers.on_rpl_ping(from, to, timestamp)
563 local cb = table.remove(icallbacks.ctcp_ping[from], 1)
564 cb({time = os.time() - timestamp, nick = from})
565 if #icallbacks.ctcp_ping[from] > 0 then say(from, {"PING " .. os.time()})
566 else icallbacks.ctcp_ping[from] = nil
572 function ctcp_handlers.on_rpl_time(from, to, time)
573 local cb = table.remove(icallbacks.ctcp_time[from], 1)
574 cb({time = time, nick = from})
575 if #icallbacks.ctcp_time[from] > 0 then say(from, {"TIME"})
576 else icallbacks.ctcp_time[from] = nil
584 -- module functions {{{
585 -- socket handling functions {{{
586 -- _register_socket {{{
588 -- Register a socket to listen on.
589 -- @param sock LuaSocket socket object
590 -- @param mode 'r' if the socket is for reading, 'w' if for writing
591 -- @param cb Callback to call when the socket is ready for reading/writing.
592 -- It will be called with the socket as the single argument.
593 function _register_socket(sock, mode, cb)
602 base.assert(not cbs[sock], "socket already registered")
603 table.insert(socks, sock)
608 -- _unregister_socket {{{
610 -- Remove a previously registered socket.
611 -- @param sock Socket to unregister
612 -- @param mode 'r' to unregister it for reading, 'w' for writing
613 function _unregister_socket(sock, mode)
622 for i, v in base.ipairs(socks) do
623 if v == sock then table.remove(socks, i); break; end
631 -- public functions {{{
632 -- server commands {{{
635 -- Start a connection to the irc server.
636 -- @param args Table of named arguments containing connection parameters.
637 -- Defaults are the all-caps versions of these parameters given
638 -- at the top of the file, and are overridable by setting them
639 -- as well, i.e. <pre>irc.NETWORK = irc.freenode.net</pre>
640 -- Possible options are:
642 -- <li><i>network:</i> address of the irc network to connect to
643 -- (default: 'localhost')</li>
644 -- <li><i>port:</i> port to connect to
645 -- (default: '6667')</li>
646 -- <li><i>pass:</i> irc server password
647 -- (default: don't send)</li>
648 -- <li><i>nick:</i> nickname to connect as
649 -- (default: 'luabot')</li>
650 -- <li><i>username:</i> username to connect with
651 -- (default: 'LuaIRC')</li>
652 -- <li><i>realname:</i> realname to connect with
653 -- (default: 'LuaIRC')</li>
654 -- <li><i>timeout:</i> amount of time in seconds to wait before
655 -- dropping an idle connection
656 -- (default: '60')</li>
658 function connect(args)
659 local network = args.network or NETWORK
660 local port = args.port or PORT
661 local nick = args.nick or NICK
662 local username = args.username or USERNAME
663 local realname = args.realname or REALNAME
664 local timeout = args.timeout or TIMEOUT
665 serverinfo.connecting = true
666 if OUTFILE then irc_debug.set_output(OUTFILE) end
667 if DEBUG then irc_debug.enable() end
668 irc_sock = base.assert(socket.connect(network, port))
669 irc_sock:settimeout(timeout)
670 _register_socket(irc_sock, 'r', incoming_message)
671 if args.pass then send("PASS", args.pass) end
673 send("USER", username, get_ip(), network, realname)
680 -- Close the connection to the irc server.
681 -- @param message Quit message (optional, defaults to 'Leaving')
682 function quit(message)
683 message = message or "Leaving"
684 send("QUIT", message)
685 serverinfo.connected = false
692 -- @param channel Channel to join
693 function join(channel)
694 if not channel then return end
695 serverinfo.channels[channel] = Channel.new(channel)
696 send("JOIN", channel)
703 -- @param channel Channel to leave
704 function part(channel)
705 if not channel then return end
706 serverinfo.channels[channel] = nil
707 send("PART", channel)
713 -- Send a message to a user or channel.
714 -- @param name User or channel to send the message to
715 -- @param message Message to send
716 function say(name, message)
717 if not name then return end
718 message = message or ""
719 send("PRIVMSG", name, message)
725 -- Send a notice to a user or channel.
726 -- @param name User or channel to send the notice to
727 -- @param message Message to send
728 function notice(name, message)
729 if not name then return end
730 message = message or ""
731 send("NOTICE", name, message)
737 -- Perform a /me action.
738 -- @param name User or channel to send the action to
739 -- @param action Action to send
740 function act(name, action)
741 if not name then return end
742 action = action or ""
743 send("PRIVMSG", name, {"ACTION", action})
748 -- information requests {{{
749 -- server_version {{{
751 -- Request the version of the IRC server you are currently connected to.
752 -- @param cb Callback to call when the information is available. The single
753 -- table parameter to this callback will contain the fields:
755 -- <li><i>server:</i> the server which responded to the request</li>
756 -- <li><i>version:</i> the server version</li>
757 -- <li><i>comments:</i> other data provided by the server</li>
759 function server_version(cb)
760 -- apparently the optional server parameter isn't supported for servers
761 -- which you are not directly connected to (freenode specific?)
762 local server = serverinfo.host
763 if not icallbacks.serverversion[server] then
764 icallbacks.serverversion[server] = {cb}
765 send("VERSION", server)
767 table.insert(icallbacks.serverversion[server], cb)
773 -- TODO: allow server parameter (to get user idle time)
775 -- Request WHOIS information about a given user.
776 -- @param cb Callback to call when the information is available. The single
777 -- table parameter to this callback may contain any or all of the
780 -- <li><i>nick:</i> the nick that was passed to this function
781 -- (this field will always be here)</li>
782 -- <li><i>user:</i> the IRC username of the user</li>
783 -- <li><i>host:</i> the user's hostname</li>
784 -- <li><i>realname:</i> the IRC realname of the user</li>
785 -- <li><i>server:</i> the IRC server the user is connected to</li>
786 -- <li><i>serverinfo:</i> arbitrary information about the above
788 -- <li><i>awaymsg:</i> set to the user's away message if they are
790 -- <li><i>is_oper:</i> true if the user is an IRCop</li>
791 -- <li><i>idle_time:</i> amount of time the user has been idle</li>
792 -- <li><i>channels:</i> array containing the channels the user has
795 -- @param nick User to request WHOIS information about
796 function whois(cb, nick)
798 requestinfo.whois[nick] = {nick = nick}
799 if not icallbacks.whois[nick] then
800 icallbacks.whois[nick] = {cb}
803 table.insert(icallbacks.whois[nick], cb)
810 -- Request the current time of the server you are connected to.
811 -- @param cb Callback to call when the information is available. The single
812 -- table parameter to this callback will contain the fields:
814 -- <li><i>server:</i> the server which responded to the request</li>
815 -- <li><i>time:</i> the time reported by the server</li>
817 function server_time(cb)
818 -- apparently the optional server parameter isn't supported for servers
819 -- which you are not directly connected to (freenode specific?)
820 local server = serverinfo.host
821 if not icallbacks.servertime[server] then
822 icallbacks.servertime[server] = {cb}
825 table.insert(icallbacks.servertime[server], cb)
834 -- Send a CTCP ping request.
835 -- @param cb Callback to call when the information is available. The single
836 -- table parameter to this callback will contain the fields:
838 -- <li><i>nick:</i> the nick which responded to the request</li>
839 -- <li><i>time:</i> the roundtrip ping time, in seconds</li>
841 -- @param nick User to ping
842 function ctcp_ping(cb, nick)
844 if not icallbacks.ctcp_ping[nick] then
845 icallbacks.ctcp_ping[nick] = {cb}
846 say(nick, {"PING " .. os.time()})
848 table.insert(icallbacks.ctcp_ping[nick], cb)
855 -- Send a localtime request.
856 -- @param cb Callback to call when the information is available. The single
857 -- table parameter to this callback will contain the fields:
859 -- <li><i>nick:</i> the nick which responded to the request</li>
860 -- <li><i>time:</i> the localtime reported by the remote client</li>
862 -- @param nick User to request the localtime from
863 function ctcp_time(cb, nick)
865 if not icallbacks.ctcp_time[nick] then
866 icallbacks.ctcp_time[nick] = {cb}
869 table.insert(icallbacks.ctcp_time[nick], cb)
876 -- Send a client version request.
877 -- @param cb Callback to call when the information is available. The single
878 -- table parameter to this callback will contain the fields:
880 -- <li><i>nick:</i> the nick which responded to the request</li>
881 -- <li><i>version:</i> the version reported by the remote client</li>
883 -- @param nick User to request the client version from
884 function ctcp_version(cb, nick)
886 if not icallbacks.ctcp_version[nick] then
887 icallbacks.ctcp_version[nick] = {cb}
888 say(nick, {"VERSION"})
890 table.insert(icallbacks.ctcp_version[nick], cb)
896 -- misc functions {{{
898 -- TODO: CTCP quoting should be explicit, this table thing is quite ugly (if
901 -- Send a raw IRC command.
902 -- @param command String containing the raw IRC command
903 -- @param ... Arguments to the command. Each argument is either a string or
904 -- an array. Strings are sent literally, arrays are CTCP quoted
905 -- as a group. The last argument (if it exists) is preceded by
906 -- a : (so it may contain spaces).
907 function send(command, ...)
908 if not serverinfo.connected and not serverinfo.connecting then return end
909 local message = command
910 for i, v in base.ipairs({...}) do
912 -- passing a table in as an argument means to treat that table as a
913 -- CTCP command, so quote it appropriately
914 if base.type(v) == "string" then
916 elseif base.type(v) == "table" then
917 arg = ctcp._ctcp_quote(table.concat(v, " "))
922 message = message .. " " .. arg
924 message = ctcp._low_quote(message)
925 -- we just truncate for now. -2 to account for the \r\n
926 message = message:sub(1, constants.IRC_MAX_MSG - 2)
927 irc_debug._message("SEND", message)
928 irc_sock:send(message .. "\r\n")
934 -- Get the local IP address for the server connection.
935 -- @return A string representation of the local IP address that the IRC server
936 -- connection is communicating on
938 return (ip or irc_sock:getsockname())
944 -- Set the local IP manually (to allow for NAT workarounds)
945 -- @param new_ip IP address to set
946 function set_ip(new_ip)
952 -- TODO: @see doesn't currently work for files/modules
954 -- Iterate over currently joined channels.
955 -- channels() is an iterator function for use in for loops.
956 -- For example, <pre>for chan in irc.channels() do print(chan:name) end</pre>
959 return function(state, arg)
960 return misc._value_iter(state, arg,
962 return v.join_complete