# Socketboard Rust SDK

This is the official Rust SDK for Socketboard. It provides a simple way to interact with the Socketboard table.

## Installation

Add the following to your `Cargo.toml` file:

```toml
[dependencies]
socketboard = "0.1.0"
```

---

## Usage

Here is a simple example of how to use the SDK:
```rust
use std::process::exit;
use std::thread;
use std::time::Duration;

// important imports
use socketboard::Socketboard;
use socketboard::types::{ConnectionStatus, Data};

fn main() {
  let socketboard = Socketboard::new("clientName");

  // connect to the remote table
  match socketboard.start() {
    Ok(_) => {
      // put a value
      socketboard.put_value("variableName", Data::Number(123f64)).unwrap();

      // put another value
      // put_value will return an error if there is an issue with the connection
      // or if there are invalid permissions
      socketboard.put_value("differentVariable", Data::String("hello world".to_string())).unwrap();

      // get a value, increment it by 1, and put it back
      // retrieve a value from the table, if it doesn't exist, use the default value provided (second argument)
      let last = socketboard.get_value("differentVariable", Data::Number(0f64));

      match last {
        Data::Number(n) => {
          println!("num: {}", n.to_string());
          socketboard.put_value("num", Data::Number(n + 1f64)).unwrap();

          let num = socketboard.get_value("num", Data::Number(0f64));
          println!("num: {}", num.to_string());
        }
        _ => {}
      }

      // print the table
      socketboard.print_table();

      // close the connection
      socketboard.stop();
    },
    Err(e) => {
      println!("Error: {}", e);
    }
  }

  println!("Done!");
}
```

---

## Documentation

The SDK is split into two main parts: the `Socketboard` struct and the `types` module.

### Socketboard
```socketboard::Socketboard```

The main struct that is used to interact with the Socketboard table.

#### Methods
- ```new(client_name: &str) -> Socketboard```: Creates a new instance of the Socketboard struct.

- ```with_host(client_name: &str, address: &str, port: u16) -> Socketboard```: Creates a new instance of the Socketboard struct with a custom host and port. The server software doesn't currently support custom hosts and ports, so this method is not recommended.

- ```start() -> Result<(), String>```: Connects to the remote table. Returns an error if there is an issue with the connection.

- ```stop()```: Closes the connection to the remote table.

- ```put_value(name: &str, value: Data) -> Result<(), String>```: Puts a value into the table. Returns an error if there is an issue with the connection or if there are invalid permissions.

- ```get_value(name: &str, default: Data) -> Data```: Retrieves a value from the table. If the value does not exist, the default value is returned.

- ```get_status() -> ConnectionStatus```: Returns the current status of the connection to the remote table.

- ```print_table()```: Prints the table to the console.

### types
```socketboard::types```

Contains the different types that can be stored in the table.

#### Enums
- ```Data```: Represents the different types that can be stored in the table.
  - ```Number(f64)```: A floating point number.
  - ```String(String)```: A string.
  - ```Boolean(bool)```: A boolean.
  - ```Array(Vec<Data>)```: An array of Data values.
  - ```Object(HashMap<String, Data>)```: An object with string keys and Data values.

  Importantly, there is no distinction between integers and floating point numbers. All numbers are stored as floating point numbers, as the table is not strongly typed, and shares data between clients with different languages.

- ```ConnectionStatus```: Represents the different states of the connection to the table.
  - ```Connected(String)```: The connection is established.
  - ```Disconnected(String)```: The connection is closed.
  - ```Failed(String)```: There was an issue with the connection.
  - ```Connecting```: The connection is being established.
  - ```Stopped```: The connection is closed.
  - ```None```: The connection is not established.

### Examples
```rust
use socketboard::Socketboard;
use socketboard::types::{Data, ConnectionStatus};

fn main() {
  // initialization
  let socketboard = Socketboard::new("clientName");
  
  // OR
  
  let address = "127.0.0.1";
  let port = 8080;
  let socketboard = Socketboard::with_host("clientName", address, port);
  
  // connect to the remote table
  socketboard.start().unwrap();

  // different types of data
  let num = Data::Number(123f64);
  let string = Data::String("hello world".to_string());
  let boolean = Data::Boolean(true);
  let array = Data::Array(vec![Data::Number(1f64), Data::Number(2f64)]);
  let object = Data::Object(
    vec![
      ("key1".to_string(), Data::Number(123f64)),
      ("key2".to_string(), Data::String("hello world".to_string()))
    ].into_iter().collect()
  );

  // managing the connection status from socketboard
  match socketboard.get_status() {
    ConnectionStatus::Connected(client_name) => {
      println!("Connected to table with client name: {}", client_name);
    },
    ConnectionStatus::Disconnected(client_name) => {
      println!("Disconnected from table with client name: {}", client_name);
    },
    ConnectionStatus::Failed(error) => {
      println!("Failed to connect to table: {}", error);
    },
    ConnectionStatus::Connecting => {
      println!("Connecting to table...");
    },
    ConnectionStatus::Stopped => {
      println!("Connection stopped.");
    },
    ConnectionStatus::None => {
      println!("Connection not established.");
    }
  }

  // wait for 5 seconds
  thread::sleep(Duration::from_secs(5));

  socketboard.stop();
}
```

---

## Roadmap

- [x] Basic functionality
- [x] Documentation
- [ ] Support for password authenticated connections