Global functions
======================

The following functions are imported into the global namespace
of all scripts that are running inside widelands. They provide convenient
access to other scripts in other locations, localisation features and more.

There is also a global variable called __file__ defined that is the current
files name.

.. function:: string.bformat

   Not really a global function. But we add a method to ``string`` built-in type in
   Lua that has similar functionality to the built-in ``string.format``, but
   instead uses our own ``format`` function. This allows for better control of the
   formatting as well as reordering of arguments which is needed for proper localisation.

   Use ``bformat()`` whenever your string contains values from variables.

   :returns: The formatted string.

   ``bformat()`` can be used with the global :func:`_(str) function <_>`. Examples:

   .. code-block:: lua

      local a_str    = _("Widelands")
      local a_number = 5
      local a_float  = 3.4

      _("This is a string: %1$s"):bformat(a_str)             -- s = string
      _("This is a number: %1$d"):bformat(a_number)          -- d = number (integer)
      _("This is a number: %1$f"):bformat(a_float)           -- f = number (float)

      -- %1$ refers to the first,
      -- %2$ to the second placeholder and so on:

      local tribe_name = _("Atlanteans")
      _("The %1$s are one of the tribes in %2$s."):bformat(tribe_name, a_str)

      -- Formatting numbers with two digits:
      local hours   = 2
      local minutes = 10
      local seconds = 5

      -- TRANSLATORS: A time string (hh:mm:ss) like "10:02:30"
      _("%1$02d:%2$02d:%3$02d"):bformat(hours, minutes, seconds) -- result: 02:10:05

      -- Formatting floating point numbers with precision:
      local endless = 10 / 3

      _("Precision of 2: %1$.2f"):bformat(endless)           -- result: Precision of 2: 3.33

   If your variable contains a number you should use :func:`ngettext` or
   :func:`npgettext` to allow proper translation of plural strings.


.. function:: push_textdomain(domain [, addon=false])

   Sets the textdomain for all further calls to :func:`_` until it is reset
   to the previous value using :func:`pop_textdomain`.

   If your script is part of an add-on, the second parameter needs to be `true`.

   :arg domain: The textdomain
   :type domain: :class:`string`
   :returns: :const:`nil`

.. function:: pop_textdomain()

   Resets the textdomain for calls to :func:`_` to the value it had
   before the last call to :func:`push_textdomain`.

   :returns: :const:`nil`

.. function:: _(str)

   This peculiar function is used to translate texts in your scenario into
   another language. The function takes a single string, grabs the
   textdomain of your map (which is usually the maps name) and returns the
   translated string. Make sure that you separate translatable and untranslatable
   stuff:

   .. code-block:: lua

      s = "<p><br>" .. _("Only this should be translated") .. "<br></p>"

   :arg str: text to translate.
   :type str: :class:`string`
   :returns: The translated string.

.. function:: ngettext(msgid, msgid_plural, n)

   A wrapper for the ngettext() function, needed for translations of numbered
   strings.

   :arg msgid: text to translate (singular)
   :type msgid: :class:`string`
   :arg msgid_plural: text to translate (plural)
   :type msgid_plural: :class:`string`
   :arg n: The number of elements.
   :type n: An unsigned integer.

   :returns: The translated string.

   Example to show how it works:

   .. code-block:: lua

      local count = _get_items()                -- count can be 0 or more
      local text  = ngettext("You have %1$d item", "You have %1$d items", count):bformat(count)

   .. note::
      The singular and plural forms should be identical except for the plural form itself.
      If you want to special-case the number ``1`` (or any other number),
      or if you don't want to include the ``count`` variable in the string,
      do *not* use ``ngettext``, but rather an ``if``-``else``-construct. Example:

   .. code-block:: lua

      local count = _get_items()  -- count can be 0 or more
      local text

      if count == 0 then
         text = _("You have no items.")
      elseif count == 1 then
         text = _("You have only one item.")
      else
         text = _("You have a lot of items.")
      end

      -- Note the _() function for translation.
      -- The arguments to ngettext do not require an additional _() call.

.. function:: pgettext(msgctxt, msgid)

   A wrapper for the pgettext() function, needed for allowing multiple translations of the same
   string according to context.

   :arg msgctxt: a named context for this string for disambiguation
   :type msgctxt: :class:`string`
   :arg msgid: text to translate
   :type msgid: :class:`string`

   :returns: The translated string.

.. function:: npgettext(msgctxt, msgid, msgid_plural, n)

   A wrapper for the npgettext() function, needed for allowing multiple translations of the same
   plural string according to context.

   :arg msgctxt: a named context for this string for disambiguation
   :type msgctxt: :class:`string`
   :arg msgid: text to translate
   :type msgid: :class:`string`
   :arg msgid_plural: text to translate (plural)
   :type msgid_plural: :class:`string`
   :arg n: The number of elements.
   :type n: An unsigned integer.

   :returns: The translated string.

.. function:: include(script)

   Includes the script at the given location at the current position in the
   file. The script can begin with 'map:' to include files from the map.

   :type script: :class:`string`
   :arg script: The filename relative to the root of the data directory.
   :returns: :const:`nil`

.. function:: ticks()

   Returns an integer value representing the number of milliseconds since the SDL library
   initialized.

.. function:: get_build_id()

   returns the version string of this widelands executable.  Something like
   "1.1" (for a release),
   "1.2~git26354 (4ba897c@master)" (development for 1.2) or
   "build-16[debug]" (old, before version 1.0).

.. function:: play_sound(file[, priority = 100, allow_multiple = true, field = nil])

   .. versionadded:: 1.3

   Play a sound effect.

   See :ref:`the playsound program <map_object_programs_playsound>` for information
   on how the file has to be provided and the meaning of the optional arguments.
   Only ``.ogg`` files are supported.

   If a field is provided, the sound is played in stereo,
   and only if the player can hear sounds on the given field.

   The volume of the sound and whether the sound will be played at all are determined
   by the user's settings for ambient sounds.

   :arg file: The path and basename of the sound effect to play
      (without the .ogg filename extension and the optional ``_??`` numbering).
   :type file: :class:`string`
   :arg priority: The priority of the sound in percent.
   :type priority: :class:`number`
   :arg allow_multiple: Whether the sound may be played
      even when another instance of it is already playing.
   :type allow_multiple: :class:`boolean`
   :arg field: The map position of the sound, if any.
   :type field: :class:`wl.map.Field`