<?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>
  </refsection>

  <refsection id="cockpit-format-bytes">
    <title>cockpit.format_bytes()</title>
<programlisting>
string = cockpit.format_bytes(number, [factor])
array = cockpit.format_bytes(number, [factor, separate])
</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>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 1024.  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>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>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-number">
    <title>cockpit.format_number()</title>
<programlisting>
string = cockpit.format_number(number)
</programlisting>
    <para>Formats <code>number</code> into a displayable <code>string</code>. If the number is not
      an integer, it is rounded to a single decimal place precision. If the number is near zero, but
      not quite zero it is rounded up or down to a single decimal place.</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-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, separate])
</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 1024.  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>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>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, separate])
</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 1024.  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>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>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>

  <refsection id="cockpit-extend">
    <title>cockpit.extend</title>
<programlisting>
cockpit.extend(target, src, ...)
</programlisting>
    <para>This function is used to copy the values of all enumerable own properties
      from one or more source objects to a target object. It will return the target object. This
      is similar to <code>Object.assign()</code>.</para>
  </refsection>

</refentry>
