.\" Copyright (c) 2019 The Notion development team
.\" This file is hereby licensed Creative Commons CC0 - no rights reserved
.\" For more information, see https://creativecommons.org/share-your-work/public-domain/cc0/
.\" This is an mdoc(7) manual page, as any manual page should be.
.Dd June 20, 2019
.Dt notionflux 1
.Os notion
.Sh NAME
.Nm notionflux
.Nd Lua remote control for notion
.Sh SYNOPSIS
.Nm Op Fl R | Fl e Ar lua-code | Pa file
.Sh DESCRIPTION
.Nm
is a tool to send scripts to the Lua scripting engine inside the
.Xr notion 1
window manager.
The script can thus access notion's internal Lua API.
.Pp
There are two modes of operation, interactive and batch.
Interactive mode is enabled by running
.Nm
with its standard input connected to a terminal and without passing any commandline flags.
.Pp
Otherwise, batch mode is enabled:
.Bl -tag -width Ds
.It Fl R
Force batch-mode even if stdin is connected to a terminal.
Lua code is read from stdin until the end-of-file is reached,
is sent to notion for processing, and the result is read back and displayed.
.It Fl e Ar code
Almost the same as above, except instead of reading from stdin, the command line parameter
.Ar code
is submitted for processing.
.It Pa file
The content of the file is evaluated.
.El
.Sh INTERACTIVE MODE
This mode is similar to running an interactive
.Xr lua 1
shell.
Tab completion for notion's Lua API is available, as well as line-editing.
.Pp
Code that has been entered is evaluated by notion as soon as it is a complete
Lua statement.
The result is displayed after which the next statement can be entered.
.Sh ENVIRONMENT
.Bl -tag -width DISPLAY
.It Ev DISPLAY
The
.Ev DISPLAY
environment variable must be set to an X server running notion in order for
.Nm
to obtain the socket path.
.El
.Sh SECURITY
.Nm
connects to
.Xr notion 1
through a Unix domain socket.
This socket is created with read/write permissions only for the user who started notion.
The socket path can be queried with the following command:
.Bd -literal -offset indent
$ xprop \-root _NOTION_MOD_NOTIONFLUX_SOCKET
_NOTION_MOD_NOTIONFLUX_SOCKET(STRING) = "/tmp/fileuj6onu"
.Ed
.Sh EXAMPLES
The command
.Bd -literal -offset indent
$ notionflux -e "return notioncore.current():name()"
"emacs: notionflux.1"
.Ed
.Pp
will display the title of the currently focused window, while
.Bd -literal -offset indent
$ notionflux -e "print(notioncore.current():name())"
"emacs: notionflux.1"
nil
.Ed
.Pp
will collect the messages and print them before returning.
In order to write to notion's standard output (usually
.Pa ~/.xsession\-errors ) ,
like print used to in previous versions of
.Nm ,
please use
.Bd -literal -offset indent
$ notionflux -e 'io.stdout:write("hello .xsession-errors!\\n")'
nil
.Ed
.Pp
Using input redirection:
.Bd -literal -offset indent
$ echo "return notioncore.current()" | notionflux
WClientWin: 0x9bb6b8
.Ed
.Pp
Using interactive mode:
.Bd -literal -offset indent
$ notionflux
lua> notioncore.current():rootwin_of()
WRootWin: 0x8c9688
lua> do
\&...>   local x = 42 -- Lua defaults to global scope, don't litter
\&...>   return x
\&...> end
42
lua> ^D
.Ed
.Pp
In any response from mod_notionflux, strings are quoted in a way that can be
directly pasted back into a Lua interpreter to yield the same string, while
other types are turned into their string representation using
.Fn tostring .
This is why there are quotation marks around the response in the first example
where nil (which is the return value of a block which has no return statement)
does not have them.
.Sh SEE ALSO
.Lk https://notionwm.net/ "The notion homepage"
.Pp
.Lk https://raboof.github.io/notion-doc/notionconf/ "Configuring and extending Notion with Lua"
.Pp
.Lk https://www.lua.org/manual/5.3/manual.html "The Lua 5.3 reference manual"
.Pp
.Pa /usr/share/doc/notion/
.Pp
.Xr notion 1 ,
.Xr X 7 ,
.Xr lua 1 ,
.Xr readline 3
.Sh HISTORY
An ionflux command appeared in ion3 around 2004.
It was adapted to notion by the notion development team when notion was forked from ion3 in 2010.
.Sh AUTHORS
.Nm
was rewritten in 2019 by
.An The Notion development team
under the GNU GPL in order to add the interactive mode.
.Sh BUGS
Currently, the script must be 4095 bytes or shorter.
If you need more, consider passing a filename, which is passed to notion for
evaluation and therefore circumvents this limit.