mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 16:34:47 +01:00
192 lines
8.3 KiB
ReStructuredText
192 lines
8.3 KiB
ReStructuredText
==========================
|
|
Frequently Asked Questions
|
|
==========================
|
|
Ok, so, maybe no one actually asked them.
|
|
|
|
1. Why xonsh?
|
|
-------------
|
|
The idea for xonsh first struck while I was reviewing the Bash chapter
|
|
(written by my co-author `Katy Huff <http://katyhuff.github.io/>`_)
|
|
of `Effective Computation in Physics <http://physics.codes/>`_. In the book,
|
|
we spend a bunch of time describing important, but complex ideas, such
|
|
as piping. However, we don't even touch on more 'basic' aspects of the Bash
|
|
language, such as if-statements or loops. Even though I have been using Bash
|
|
for well over a decade, I am not even sure I *know how*
|
|
to add two numbers together in it or consistently create an array. This is
|
|
normal.
|
|
|
|
If the tool is so bad, then maybe we need a new tool. So xonsh is really meant
|
|
to solve the problem that other shells don't "fit your brain."
|
|
In some programming situations this is OK because of what you get
|
|
(an optimizing compiler, type safety, provable correctness, register access).
|
|
But a shell that doesn't fit your brain is only a liability.
|
|
|
|
Coincidentally, within the week, `an article floated to the top of Hacker News <http://stephen-brennan.com/2015/01/16/write-a-shell-in-c/>`_
|
|
that teaches you how to write a shell in C. So I thought, "It can't be
|
|
that hard..."
|
|
|
|
And thus, `again <http://exofrills.org>`_, I entered the danger zone.
|
|
|
|
|
|
2. Why not another exotic shell, such as ``fish``?
|
|
-----------------------------------------------------
|
|
While many other alternative shells have an amazing suite of features
|
|
as well as much improved syntax of traditional options, none of them
|
|
are quite as beautiful as Python. In xonsh, you get the best of all possible
|
|
worlds. A syntax that already fits your brain and any features that you
|
|
desire.
|
|
|
|
|
|
3. Why not just use the IPython command line interface?
|
|
-------------------------------------------------------
|
|
There are two serious drawbacks to this approach - though, believe me, I have
|
|
tried it.
|
|
|
|
The first is that typing ``!`` before every subprocess command is
|
|
extremely tedious. I think that this is because it is a prefix operator and
|
|
thus gets in the way of what you are trying to do right as you start to try
|
|
to do it. Making ``!`` a postfix operator could address some of this, but
|
|
would probably end up being annoying, though not nearly as jarring.
|
|
|
|
The second reason is that tab completion of subprocess commands after an ``!``
|
|
does not work. This is a deal breaker for day-to-day use.
|
|
|
|
|
|
4. So how does this all work?
|
|
-----------------------------
|
|
We use `PLY <http://www.dabeaz.com/ply/ply.html>`_ to tokenize and parse
|
|
xonsh code. This is heavily inspired by how `pycparser <https://github.com/eliben/pycparser>`_
|
|
used this PLY. From our parser, we construct an abstract syntax tree (AST)
|
|
only using nodes found in the Python ``ast`` standard library module.
|
|
This allows us to compile and execute the AST using the normal Python tools.
|
|
|
|
Of course, xonsh has special builtins, so the proper context
|
|
(builtins, globals, and locals) must be set up prior to actually executing
|
|
any code. However, the AST can be constructed completely independently of
|
|
any context...mostly.
|
|
|
|
While the grammar of the xonsh language is context-free, it was convenient
|
|
to write the executer in a way that is slightly context sensitive. This is
|
|
because certain expressions are ambiguous as to whether they belong to
|
|
Python-mode or subprocess-mode. For example, most people will look at
|
|
``ls -l`` and see a listing command. However, if ``ls`` and ``l`` were
|
|
Python variables, this could be transformed to the equivalent (Python)
|
|
expressions ``ls - l`` or ``ls-l``. Neither of which are valid listing
|
|
commands.
|
|
|
|
What xonsh does to overcome such ambiguity is to check if the names in the
|
|
expression (``ls`` and ``l`` above) are in the present Python context. If they are,
|
|
then it takes
|
|
the line to be valid xonsh as written. If one of the names cannot be found,
|
|
then xonsh assumes that the left-most name is an external command. It thus
|
|
attempts to parse the line after wrapping it in an uncaptured subprocess
|
|
call ``![]``. If wrapped version successfully parses, the ``![]`` version
|
|
stays. Otherwise, the original line is retained.
|
|
|
|
All of the context sensitive parsing occurs as an AST transformation prior to
|
|
any code is executed. This ensures that code will never be partially executed
|
|
before failing.
|
|
|
|
It is critical to note that the context sensitive parsing is a convenience
|
|
meant for humans. If ambiguity remains or exactness is required, simply
|
|
manually use the ``![]``, ``!()``, ``$[]`` or ``$()`` operators on your code.
|
|
|
|
|
|
5. Context-sensitive parsing is gross
|
|
--------------------------------------
|
|
Yes, context-sensitive parsing is gross. But the point of xonsh is that it uses
|
|
xontext-sensitive parsing and
|
|
is ultimately a lot less gross than other shell languages, such as Bash.
|
|
Furthermore, its use is heavily limited here.
|
|
|
|
|
|
6. My Branches are Timing Out?!
|
|
-------------------------------
|
|
Depending on you system, setup, and repository sizes, computing branch names
|
|
and colors (i.e. if the branch is dirty or not), can be a pretty slow operation.
|
|
This is bad news because xonsh can try to compute these each time it formats
|
|
the ``$PROMPT``.
|
|
|
|
In order to keep xonsh snappy, we have implemented branch computation timeouts.
|
|
This is set to a nominal value (usually 0.1 sec) via the ``$VC_BRANCH_TIMEOUT``
|
|
environment variable.
|
|
|
|
Feel free to set this to any limit that you feel comfortable with. So if you
|
|
don't mind a potentially slow prompt, set it to 1, 5, 20, 100 seconds! However,
|
|
if you never want to deal with a slow prompt or seeing this timeout message,
|
|
you can remove the ``{curr_branch}``, ``{branch_color}`` and ``{branch_bg_color}``
|
|
portions of your ``$PROMPT``, and these values will never be computed.
|
|
|
|
It is also worth noting that ``{branch_color}`` is usually the slow poke.
|
|
Just removing the color lookup from the ``$PROMPT`` can still provide the branch
|
|
name while being fast enough.
|
|
|
|
7. exec
|
|
-------
|
|
The notion of ``exec`` is a bit of a tricky beast in xonsh. Both Python and
|
|
basically every other shell language have an exec that perform radically
|
|
different operations.
|
|
|
|
* In Python, ``exec`` is a builtin function that executes strings, ASTs, or
|
|
code objects in a provided namespace.
|
|
* In sh-langs (and elsewhere), ``exec`` is a command the runs another command
|
|
directly in the current process.
|
|
|
|
These two ideas are central to both languages - without which most programs
|
|
cannot be run. Luckily, even though they share a name, they have distinct
|
|
syntax and don't share a namespace. Therefore, in xonsh,
|
|
|
|
.. code-block:: xonshcon
|
|
|
|
# exec() as a function is run as Python's exec
|
|
>>> exec('x = 41; x += 1', globals(), locals())
|
|
|
|
# while exec as a statement is like bash's exec
|
|
>>> exec gdb
|
|
(gdb)
|
|
|
|
Yes, this is potentially confusing. This is particularly true since earlier
|
|
versions of Python *had* an exec statement whose syntax would have clashed
|
|
with the sh-lang command form.
|
|
|
|
Yes, we are sorry. But the alternative is that important programs that use
|
|
exec under the covers, such as SSH and gdb, would not be usable when xonsh
|
|
is set as the default shell. (Note that we can't rename the exec() function
|
|
since Python would fail.) As usability is the most important aspect of a shell,
|
|
xonsh trades a small amount of potential confusion for large class of important
|
|
commands.
|
|
|
|
All of the above being true, if the exec duality is causing you problems there
|
|
a few operations that you can implement to mitigate the confusion. The first is
|
|
that you can remove the ``exec`` alias and use the ``xexec`` alias instead:
|
|
|
|
.. code-block:: xonshcon
|
|
|
|
>>> del aliases['exec']
|
|
>>> xexec ssh
|
|
|
|
Alternatively, you can always be sure to run the exec command explicitly in
|
|
subprocess mode with ``![]`` or ``!()``:
|
|
|
|
.. code-block:: xonshcon
|
|
|
|
>>> ![exec bash]
|
|
|
|
Lastly, you can assign the result of the exec() function to a throw away
|
|
variable (since the return is always None):
|
|
|
|
.. code-block:: xonshcon
|
|
|
|
>>> _ = exec('x = 42')
|
|
|
|
Hopefully, though, this trade-off makes sense and you never have to worry about
|
|
it...unless chimera slaying is your bag.
|
|
|
|
8. Gotchas
|
|
----------
|
|
There are a few gotchas when using xonsh across multiple versions of Python,
|
|
where some behavior can differ, as the underlying Python might behave
|
|
differently.
|
|
|
|
For example double star globbing `**` will only work on Python 3.5+ (ie not on 3.4)
|
|
as recursive globbing is `new in Python 3.5 <https://docs.python.org/3/library/glob.html#glob.glob>`_
|