.. This file is part of Sympathy for Data.
.. Copyright (c) 2010-2012 Combine Control Systems AB
..
.. Sympathy for Data is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, version 3 of the License.
..
.. Sympathy for Data is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with Sympathy for Data.  If not, see <http://www.gnu.org/licenses/>.

.. _batch:

Command line
============

When Sympathy is installed in your python environment you can run
``python -m sympathy`` to access the command line interface.

For a comprehensive list of commands and options, see :ref:`appendix_cli`.

.. _launch_options:

Top-level commands
------------------

Running ``python -m sympathy --help`` will print the top level commands available.

``gui``
  run Sympathy in GUI mode
``cli``
  run Sympathy in CLI mode
``viewer``
  run the viewer for sydata files
``doc``
  generate documentation files
``install``
  install Sympathy (start menu, file associations)
``uninstall``
  uninstall Sympathy (start menu, file associations)
``tests``
  run the test suite
``clear``
  cleanup temporary files

.. _start_options:

Command options
---------------

As mentioned there are several top level commands. Most of which have
their own options.

In order to list the options available for a command, run sympathy adding
the desired command and ``--help`` to the command line. For example,
``python -m sympathy gui --help`` shows the available options for running
Sympathy in GUI mode.


Noteable examples
-----------------

Here are a few examples that might be useful, for the full list please use
the ``--help`` flag.


Run *Sympathy for Data GUI*:

.. code-block:: bash

   python -m sympathy gui

Run *Sympathy for Data CLI*, executing a specified syx-workflow-file:

.. code-block:: bash

   python -m sympathy cli filename


Build documentation for Sympathy for the platform and standard library.

.. code-block:: bash

   python -m sympathy_app install --generate-docs

Run the test suite

.. code-block:: bash

   python -m sympathy_app tests -v


Shortcuts
---------

Depending on how Sympathy was installed, you might also have shortcuts
available to some commands.

Wheel installer:

sympathy (``python -m sympathy``)
sympathy cli (``python -m sympathy cli``)
sympathy gui (``python -m sympathy gui``)

Windows installer:

RunSympathyCLI.bat (``python -m sympathy cli``)
RunSympathyGUI.bat (``python -m sympathy gui``)


.. _env_vars:

Using environment variables
---------------------------
Environment variable expansion is useful in node configurations where the node
should behave differently depending on the environment where it is executed.
A simple example would be a workflow that always loads a certain file from the
current user's home directory. To achieve that you can simply configure a
:ref:`Datasource` node to point to *$(HOME)/somefile.txt* and it will point to
the file *somefile.txt* in the user's home directory.

Apart from using already existing OS environment variables you can also add your
own environment variables at three different levels: OS/shell, workflow, and
global.  Workflow level variables are generally preferred as they do not
risk affecting workflows that they should not affect.

.. _default_workflow_vars:

Default workflow environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A few variables are always defined in every workflow. ``$(SY_FLOW_FILEPATH)``
holds the full path to the workflow file, and ``$(SY_FLOW_DIR)`` contains the
directory of the workflow file. These variables behave just like normal workflow
variables, but they are not stored in a syx-file. Instead they are computed on the
fly when they are used. Check properties for a flow to see what values these
variables have for that flow.

.. _shell_vars:

Adding OS/shell environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Setting environment variables or shell variables is done differently depending
on operating system, version, shell, and so on. As an example let us set the shell
variable ``GREETING`` and start Sympathy in a command prompt in Windows::

    > set GREETING=Hi!
    > RunSympathyGUI.exe

.. TODO : Write about OSX and linux?

Add a :ref:`Hello world Example` node and configure it to display
``$(GREETING)``. Run the node. The output should be *Hi!*.

.. _flow_vars:

Adding workflow environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Workflow level environment variables can be added and removed via the
preferences GUI. Right click in your flow and click *Properties* and go to the
tab *Environment variables*, where you can add, change, and remove workflow
variables. These variables are stored in the workflow file, and will only
affect that workflow, and its subflows. A subflow can always override a
variable set by one of its parent flows.

Adding environment variables to the global file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Just as workflow level variables, global variables can be added and
edited in:ref:`Environment Preferences<preferences_environment>` but they are
stored in the global config file for Sympathy so they affect all workflows.

Priority
^^^^^^^^
In case of name conflicts, environment variables are looked up in the following
order:

1. OS/shell
2. Workflow (defined in current subflow)
3. Workflow (defined in a parent workflow)
4. Global settings


Special variables
^^^^^^^^^^^^^^^^^

**SY_OVERRIDE_TEMP_PATH**
    Used to override the folder where session data (temporary files) are
    stored. The temporary path may in turn contain environment variables.