This change has two implications:
1) tree_render() will now be called precisely once for input which consists of
multiple commands (like "focus left; focus right"). Also, the caller of
parse_command() has to call it. This makes us able to fix tickets such as
ticket #608 (where multiple tree_render() calls are noticable).
2) The output of a command is now a JSON array of return values of the
individual subcommands. In the case of "focus left; focus right", this is:
[{"success":true}, {"success":true}]
While this is incompatible with what i3 returned before, the return value of
commands was undocumented and therefore not subject to our API stability.
On the rationale of using a custom parser instead of a lex/yacc one, see this
quote from src/commands_parser.c:
We use a hand-written parser instead of lex/yacc because our commands are
easy for humans, not for computers. Thus, it’s quite hard to specify a
context-free grammar for the commands. A PEG grammar would be easier, but
there’s downsides to every PEG parser generator I have come accross so far.
This parser is basically a state machine which looks for literals or strings
and can push either on a stack. After identifying a literal or string, it
will either transition to the current state, to a different state, or call a
function (like cmd_move()).
Special care has been taken that error messages are useful and the code is
well testable (when compiled with -DTEST_PARSER it will output to stdout
instead of actually calling any function).
During the migration phase (I plan to completely switch to this parser before
4.2 will be released), the new parser will parse every command you send to
i3 and save the resulting call stack. Then, the old parser will parse your
input and actually execute the commands. Afterwards, both call stacks will be
compared and any differences will be logged.
The new parser works with 100% of the test suite and produces identical call
stacks.
Please test this! Plug in screens, unplug them, use your video projector,
change resolutions, etc.
To use the assignments, use the following syntax:
workspace <number> [screen <screen>] [name]
Where screen can be one of:
<number> (It is not provided that these numbers stay constant, so use with care)
<x>x<y> (Coordinates where the screen starts, so 1280 will be fine to match the
screen right of the main screen if your main screen is 1280 pixels
width. However, 1281 will not match)
<x>
x<y>
Some examples follow:
workspace 1 screen 0
workspace 1 screen 1
workspace 1 screen 1280x0
workspace 2 screen 1280
workspace 3 screen x0
workspace 3 screen 1 www
workspace 4 screen 0 mail
This is a relatively big change, however all cases should be handled by
now.
Because the function to do graphical resizing got rather large, I’ve created
a new file src/resize.c for it.
This fixes ticket #35.
Thanks to psychoschlumpf for the hint. Having comments in the headers
makes it easier to get the big picture when not being interested in the
source.
The doxygen file extracts as much as it can into HTML files. Please note
that this is not official/supported documentation, but rather being nice
to people who have to/want to use doxygen (I don’t).
Let me paste the header of the doxygen file:
You can use this file with doxygen to create a pseudo-documentation
automatically from source. doxygen-comments are not used very extensively
in i3, mostly for the reason that it clutters the source code and has no
real use (doxygen’s output looks really ugly).
So, if you want to use it, here you go. This is however not a supported
document, and I recommend you have a look at the docs/ folder or at
http://i3.zekjur.net/ for more, real documentation.
Michael Stapelberg