# `Gamepad.Wire`
[🔗](https://github.com/jaman/gamepad/blob/v0.1.0/lib/gamepad/wire.ex#L1)

The line protocol between `Gamepad` and a platform helper, and the event
maps a controller produces.

A helper writes one line per event to its standard output:

    device <id> <name...>
    gone <id>
    button <id> <button> <0|1>
    axis <id> <axis> <value>

`id` is a small integer the helper assigns per connected controller. Buttons and axes
use the Xbox layout names below whatever the hardware is; a helper maps its platform's
names to these. Axis values are floats: sticks from `-1.0` (left or up) to `1.0`
(right or down), triggers from `0.0` to `1.0`.

`parse/1` turns a line into the event map delivered by `Gamepad`:

  * `%{type: :connected, device: id, name: name}`
  * `%{type: :disconnected, device: id}`
  * `%{type: :button, device: id, button: button, pressed: boolean}`
  * `%{type: :axis, device: id, axis: axis, value: float}`

A line that is not one of these parses to `nil`.

# `axis`

```elixir
@type axis() ::
  :left_x | :left_y | :right_x | :right_y | :left_trigger | :right_trigger
```

# `button`

```elixir
@type button() ::
  :a
  | :b
  | :x
  | :y
  | :left_bumper
  | :right_bumper
  | :back
  | :start
  | :guide
  | :left_stick
  | :right_stick
  | :dpad_up
  | :dpad_down
  | :dpad_left
  | :dpad_right
```

# `event`

```elixir
@type event() ::
  %{type: :connected, device: non_neg_integer(), name: String.t()}
  | %{type: :disconnected, device: non_neg_integer()}
  | %{
      type: :button,
      device: non_neg_integer(),
      button: button(),
      pressed: boolean()
    }
  | %{type: :axis, device: non_neg_integer(), axis: axis(), value: float()}
```

# `axes`

```elixir
@spec axes() :: [axis()]
```

The axis names.

# `buttons`

```elixir
@spec buttons() :: [button()]
```

The button names, in the Xbox layout.

# `parse`

```elixir
@spec parse(String.t()) :: event() | nil
```

The event a helper line describes, or `nil` for a line that is not an event.

    iex> Gamepad.Wire.parse("button 0 a 1")
    %{type: :button, device: 0, button: :a, pressed: true}

    iex> Gamepad.Wire.parse("axis 2 left_y -0.25")
    %{type: :axis, device: 2, axis: :left_y, value: -0.25}

    iex> Gamepad.Wire.parse("device 0 Xbox Wireless Controller")
    %{type: :connected, device: 0, name: "Xbox Wireless Controller"}

    iex> Gamepad.Wire.parse("gone 0")
    %{type: :disconnected, device: 0}

    iex> Gamepad.Wire.parse("button 0 select 1")
    nil

---

*Consult [api-reference.md](api-reference.md) for complete listing*