stdweb 0.1.0

A standard library for the client-side Web
Documentation

Build Status

A standard library for the client-side Web

Documentation

The goal of this crate is to provide Rust bindings to the Web APIs and to allow a high degree of interoperability between Rust and JavaScript.

Examples

You can directly embed JavaScript code into Rust:

let message = "Hello, 世界!";
let result = js! {
    alert!( @{message} );
    return 2 + 2 * 2;
};

println!( "2 + 2 * 2 = {:?}", result );

Even closures are are supported:

let print_hello = |name: String| {
    println!( "Hello, {}!", name );
};

js! {
    var print_hello = @{print_hello};
    print_hello( "Bob" );
    print_hello.drop(); // Necessary to clean up the closure on Rust's side.
}

You can also pass arbitrary structures thanks to serde:

#[derive(Serialize)]
struct Person {
    name: String,
    age: i32
}

js_serializable!( Person );

js! {
    var person = @{person};
    console.log( person.name + " is " + person.age + " years old." );
};

This crate also exposes a number of Web APIs, for example:

let button = document().query_selector( "#hide-button" ).unwrap();
button.add_event_listener( move |_: ClickEvent| {
    for anchor in document().query_selector_all( "#main a" ) {
        js!( @{anchor}.style = "display: none;"; );
    }
});

Design goals

  • Expose a full suite of Web APIs as exposed by web browsers.
  • Try to follow the original JavaScript conventions and structure as much as possible, except in cases where doing otherwise results in a clearly superior design.
  • Be a building block from which higher level frameworks and libraries can be built.
  • Make it convenient and easy to embed JavaScript code directly into Rust and to marshal data between the two.
  • Integrate with the wider Rust ecosystem, e.g. support marshaling of structs which implement serde's Serializable.
  • Put Rust in the driver's seat where a non-trivial Web application can be written without touching JavaScript at all.
  • Allow Rust to take part in the upcoming WebAssembly (re)volution.

Getting started

WARNING: This crate is still a work-in-progress. Things might not work. Things might break. The APIs are in flux. Please do not use it in production.

  1. Add an asmjs target with rustup:

    $ rustup target add asmjs-unknown-emscripten
    
  2. Install emscripten. If you're on Arch Linux then you can just run sudo pacman -S emscripten; other distributions might also have recent enough emscripten packages in their repositories.

    Alternatively you can install it like this:

    $ curl -O https://s3.amazonaws.com/mozilla-games/emscripten/releases/emsdk-portable.tar.gz
    $ tar -xzf emsdk-portable.tar.gz
    $ source emsdk_portable/emsdk_env.sh
    $ emsdk update
    $ emsdk install sdk-incoming-64bit
    $ emsdk activate sdk-incoming-64bit
    
  3. Install cargo-web; it's not strictly necessary but it makes things more convenient:

    $ cargo install cargo-web
    
  4. Go into examples/todomvc and type:

    $ cargo web start
    
  5. Visit http://localhost:8000 with your browser.

License

Licensed under either of

at your option.

Snippets of documentation which come from Mozilla Developer Network are covered under the CC-BY-SA, version 2.5 or later.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.