=====================
``grail.gsys`` module
=====================

.. include:: ..\version.h
.. include:: ..\Library_Reference\lib-reference.h

.. contents:: Table of Contents
   :backlinks: top


-----------
Description
-----------

System module for the MineSightŪ Grail. This module contains some of the major
system components used throughout all of MineSightŪ Grail.


------
Helper
------

:df:`GMAIN(main_function, name)`:
   *New in version 4.70.*

   Utility for quickly letting you define the 'standard' gmain entry
   point for all MineSight(r) scripts.
  
     .. python::
 
       from grail import gsys
 
       def run():
           # Run my code...
 
       gmain = gsys.GMAIN(run, __name__)
       gmain.run()

   This little snippet will execute your :a:`main_function` if you are
   running from the command line OR if you are running from within MS3D.
   This is determined by inspecting the :a:`name` argument.

   The object returned must be named :c:`gmain`.

   The :c:`gmain` object can also be queried for further properties,
   namely,

   :a:`args` : list
     If the script is executed from the command line, a :d:`gmain.args`
     will be populated with a list of command line arguments, where
     the first argument is the command line.

   :a:`is_cl` : Boolean
     Set to :d:`True` if the script is being executed from the command
     line. You can use the :a:`args` property to get the list of
     arguments supplied to the script. 

   :a:`is_ip` : Boolean
     Set to :d:`True` if the script is being executed within MSIP.
     
   :a:`is_ms3d`: Boolean
     Set to :d:`True` if the script is being executed within MS3D.

   :a:`is_mscompass` : Boolean
     Set to :d:`True` if the script is being executed within MSCOMPASS.

   :a:`actual_path` : string
     This is set to the actual location that a script was executed from.
     For a PY/PYC file, the actual and logical locations are equal;
     however, for a PYZ the actual path will correspond to unpacked
     location, and the logical path will refer to the place where the
     PYZ originally resided.

   :a:`logical_path` : string
     This is set to the location that a script was selected. For a
     PY/PYC file, the actual and logical locations are equal; however,
     for a PYZ the actual path will correspond to unpacked location, and
     the logical path will refer to the place where the PYZ originally
     resided.

   Some examples are,

     .. python::

        from grail import gsys

        def run():
           if gmain.is_cl:
              params, options = parse_args(gmain.args)
           else:
              params, options = get_defaults()
           do_something(params, options)

        gmain = gsys.GMAIN(run, __name__)
        gmain.run()

   you can see that the :d:`gmain` object will have properties that
   indicate the context that the script was executed in.

---------
Functions
---------


:df:`getdialogregistry(filename)`
    Returns a standard registry for a dialog. *Internal usage only*.

:df:`getgrailregistry()`
    Returns the standard WinRegistry object for the MineSightŪ Grail's key.
    *Internal usage only*.

:df:`grailmain(message, data)`
    Generic catch-all main function.
    
    This allows us to write scripts and feed messages and data
    off to one place for all scripts.
    
    An example of using this involves using gmain(),
    
    .. Python:: 
     
      from grail import gsys
      from grail import messages
     
      def gmain(message, data):
         if message is messages.gRUN:
            domyrunstuff()
         else:
           return gsys.grailmain(messaged, data)
    
    Arguments:
      :a:`message` : integer 
        A messages as defined in grail.messages_. The type of message
        sent effects the type of data that accompanies the message.
      :a:`data` : any
        This could take any form and generally accompanies
        a message.

.. _grail.messages: lib-grail-messages.html