home | help 
notionflux(1)		     General Commands Manual		   notionflux(1)

NAME
     notionflux -- Lua remote control for notion

SYNOPSIS
     notionflux [-R | -e lua-code | file]

DESCRIPTION
     notionflux is a tool to send scripts to the Lua scripting engine inside the
     notion(1) window manager.	The script can thus access notion's internal Lua
     API.

     There  are two modes of operation, interactive and batch.	Interactive mode
     is enabled by running notionflux with its standard  input	connected  to  a
     terminal and without passing any commandline flags.

     Otherwise, batch mode is enabled:

     -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 dis-
	     played.

     -e code
	     Almost the same as above, except instead of reading from stdin, the
	     command line parameter code is submitted for processing.

     file    The content of the file is evaluated.

INTERACTIVE MODE
     This mode is similar to running an interactive lua(1) shell.   Tab  comple-
     tion for notion's Lua API is available, as well as line-editing.

     Code  that  has been entered is evaluated by notion as soon as it is a com-
     plete Lua statement.  The result is displayed after which the  next  state-
     ment can be entered.

ENVIRONMENT
     DISPLAY  The  DISPLAY  environment variable must be set to an X server run-
	      ning notion in order for notionflux to obtain the socket path.

SECURITY
     notionflux connects to notion(1) through a Unix domain socket.  This socket
     is created with read/write permissions only for the user  who  started  no-
     tion.  The socket path can be queried with the following command:

	   $ xprop -root _NOTION_MOD_NOTIONFLUX_SOCKET
	   _NOTION_MOD_NOTIONFLUX_SOCKET(STRING) = "/tmp/fileuj6onu"

EXAMPLES
     The command

	   $ notionflux -e "return notioncore.current():name()"
	   "emacs: notionflux.1"

     will display the title of the currently focused window, while

	   $ notionflux -e "print(notioncore.current():name())"
	   "emacs: notionflux.1"
	   nil

     will  collect  the  messages  and print them before returning.  In order to
     write to notion's standard output (usually ~/.xsession-errors), like  print
     used to in previous versions of notionflux, please use

	   $ notionflux -e 'io.stdout:write("hello .xsession-errors!\n")'
	   nil

     Using input redirection:

	   $ echo "return notioncore.current()" | notionflux
	   WClientWin: 0x9bb6b8

     Using interactive mode:

	   $ 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

     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
     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.

SEE ALSO
     The notion homepage

     Configuring and extending Notion with Lua

     The Lua 5.4 reference manual

     /usr/local/share/doc/notion/

     notion(1), X(7), lua(1), readline(3)

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.

AUTHORS
     notionflux was rewritten in 2019 by The Notion development team  under  the
     GNU GPL in order to add the interactive mode.

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.

notion				  June 20, 2019 		   notionflux(1)
home | help