.. 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)
``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 doc -v --library-dir <LIBRARY-DIR>


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.exe (``python -m sympathy cli``)
  
* RunSympathyGUI.exe (``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.



.. _credential_env_vars:

Passing credentials via environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Credentials can be passed to `gui` and `cli` via environment variables.
To so, use `--environment-credentials` `PREFIX`. They need to follow
a specific data format to be used.

1. The variable name must start with PREFIX. After matching, the prefix is not
   considered to be part of the name, the remaining part of the name should be a
   parse-able to a list of strings using json. There must be a credential type
   that can be constructed from the strings.

2. The variable value should be parse-able to a dictionary in the same format as
   is returned by `BasicNode.require_credentials`.


Here are 3 examples for the different credential types.


1. Secret credential

:Name: `SFD["secret","<secret-name>"]`
:Value: `{"secret":"<secret-value>"}`

2. Login credential

:Name: `SFD["login","<login-name>"]`
:Value: `{"username":"<username>","password":"<password>"}`

3. Azure credential

:Name: `SFD["azure","<client-name>","<login-name>"]`
:Value: `{"token":"<azure-token>","expires_on":<timestamp>}`

Note that expires_on is an integer.

While it can be tricky to enter such variables from the shell, it should
be possible to do for the intended usescase which is to supply the application
with sensitive information when running in a headless environment.