<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="cockpit-util">
  <refnamediv>
    <refname>cockpit.js: Utilities</refname>
    <refpurpose>Various utility functions</refpurpose>
  </refnamediv>

  <refsection id="cockpit-format">
    <title>cockpit.format()</title>
<programlisting>
string = cockpit.format(template, args)
string = cockpit.format(template, [arg, ...])
</programlisting>

    <para>Format a string interpolating <code>args</code> into <code>template</code> using
      shell like syntax. The <code>args</code> may be either an array or javascript object.
      The <code>template</code> can contain fields that look like <code>$name</code> or
      <code>${name}</code> or <code>$0</code>. Numeric fields are used with array
      <code>args</code> and start at zero.</para>

    <para>In the second form, multiple <code>arg</code> arguments may be passed directly,
      and interpolated as as numeric fields in the <code>template</code>.</para>

    <para>All falsy arguments except the numbers <code>0</code> and <code>0.0</code>are
      replaced by an empty string.</para>
  </refsection>

  <refsection id="cockpit-format-number">
    <title>cockpit.format_number()</title>
<programlisting>
string = cockpit.format_number(number, [precision])
</programlisting>
    <para>Formats <code>number</code> into a displayable <code>string</code>. If the number is not
      an integer, it is rounded to the given number of decimal places, defaulting to 3. If the number
      is near zero, but not quite zero it is rounded to the smallest non-zero value of the given precision;
      i.e. ±0.001 for default precision 3.</para>

    <para>If <code>number</code> is <code>null</code> or <code>undefined</code> an empty string
      will be returned.</para>
  </refsection>

  <refsection id="cockpit-format-bytes">
    <title>cockpit.format_bytes()</title>
<programlisting>
string = cockpit.format_bytes(number, [factor])
array = cockpit.format_bytes(number, [factor, options])
</programlisting>
    <para>Formats <code>number</code> into a displayable <code>string</code> with a suffix, such as
      <emphasis>KB</emphasis> or <emphasis>MB</emphasis>. Returns an <code>array</code> of the
      formatted number and the suffix if <code>options.separate</code> is set to <code>true</code>.</para>

    <para>If specifying 1000 or 1024 is specified as a <code>factor</code> then an appropriate suffix
      will be chosen. By default the <code>factor</code> is 1000.  You can pass a string suffix as a
      <code>factor</code> in which case the resulting number will be formatted with the same suffix.</para>

    <para>If the <code>number</code> is less than the <code>factor</code> or an unknown factor
      was passed in, then the formatted number is returned without a suffix. If <code>options.separate</code>
      is true, returns an array of <code>[formatted_number, suffix]</code> or
      <code>[formatted_number]</code> if returned without a suffix.</para>

    <para>By default, non-integer numbers will be formatted with 3 digits of precision. This can be changed
      with <code>options.precision</code>.</para>

    <para>If <code>number</code> is <code>null</code> or <code>undefined</code> an empty string or
      an array without a suffix will be returned.</para>
  </refsection>

  <refsection id="cockpit-format-bytes-per-sec">
    <title>cockpit.format_bytes_per_sec()</title>
<programlisting>
 string = cockpit.format_bytes_per_sec(number, [factor])
 array = cockpit.format_bytes_per_sec(number, [factor, options])
</programlisting>
    <para>Format <code>number</code> of bytes into a displayable speed <code>string</code>.</para>

    <para>If specifying 1000 or 1024 is specified as a <code>factor</code> then an appropriate suffix
      will be chosen. By default the <code>factor</code> is 1000.  You can pass a string suffix as a
      <code>factor</code> in which case the resulting number will be formatted with the same suffix.</para>

    <para>If the <code>number</code> is less than the <code>factor</code> or an unknown factor
      was passed in, then the formatted number is returned without a suffix. If <code>options.separate</code>
      is true, returns an array of <code>[formatted_number, suffix]</code> or
      <code>[formatted_number]</code> if returned without a suffix.</para>

    <para>By default, non-integer numbers will be formatted with 3 digits of precision. This can be changed
      with <code>options.precision</code>.</para>

    <para>If <code>number</code> is <code>null</code> or <code>undefined</code> an empty string or array
      will be returned.</para>
  </refsection>

  <refsection id="cockpit-format-bits-per-sec">
    <title>cockpit.format_bits_per_sec()</title>
<programlisting>
  string = cockpit.format_bits_per_sec(number, [factor])
 array = cockpit.format_bytes_per_sec(number, [factor, options])
</programlisting>
    <para>Format <code>number</code> of bits into a displayable speed <code>string</code>.</para>

    <para>If specifying 1000 or 1024 is specified as a <code>factor</code> then an appropriate suffix
      will be chosen. By default the <code>factor</code> is 1000.  You can pass a string suffix as a
      <code>factor</code> in which case the resulting number will be formatted with the same suffix.</para>

    <para>If the <code>number</code> is less than the <code>factor</code> or an unknown factor
      was passed in, then the formatted number is returned without a suffix. If <code>options.separate</code>
      is true, returns an array of <code>[formatted_number, suffix]</code> or
      <code>[formatted_number]</code> if returned without a suffix.</para>

    <para>By default, non-integer numbers will be formatted with 3 digits of precision. This can be changed
      with <code>options.precision</code>.</para>

    <para>If <code>number</code> is <code>null</code> or <code>undefined</code> an empty string or array
      will be returned.</para>
  </refsection>

  <refsection id="cockpit-info">
    <title>cockpit.info</title>
<programlisting>
cockpit.info["version"]
cockpit.info["build"]
</programlisting>
    <para>This object contains information about cockpit itself. Note that when cockpit is
      running on multiple servers, this only reflects the server that was connected to.
      The following fields are defined:</para>

    <variablelist>
      <varlistentry>
        <term><code>"build"</code></term>
        <listitem><para>A string containing build details.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"version"</code></term>
        <listitem><para>A string containing the cockpit version number. It is almost always
          incorrect to use this to make a decision in code.</para></listitem>
      </varlistentry>
    </variablelist>

  </refsection>

  <refsection id="cockpit-event-target">
    <title>cockpit.event_target</title>
<programlisting>
cockpit.event_target(object, [handlers])
</programlisting>
    <para>Adds an
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget">EventTarget</ulink>
      implementation to the <code>object</code>. Optionally store the handlers in <code>handlers</code>
      if its specified.</para>
  </refsection>

</refentry>
