Introduction

Installation

Add this line to your dependencies section of your Cargo.toml file.

vii = "0.0"

Current interface is highly unstable.

Features

Default comes with a lot of useful features, but there are a lot of features available, to increase the quality of your program.

Quickstart

If possible, use the examples directly from the documentation as they are more clear and tested.

Plugin

Note: Server plugins, or persistent plugins are not yet implemented.
Note: FiletypePlugin, for a Vim filetype plugin, is not yet implemented.

Creating a Vim plugin using Rust. Can be installed and run using the Vim plugin rust-plug.

Acts almost just like a Vim plugin would. It runs on startup, running it's code. Exceptions include adding pythonx code, the autoload directory, but it can still create functions, commands, global variables, and read from Vim itself.

Uses PluginConfig struct to add configuration support.
Uses Plugin trait to create a plugin.
- get_config - Get the configuration struct.
- plugin - The plugin, the important information.

Here's an example, taken from rust-plug proof of concept.

# Cargo.toml
[package]
name = "rust-plug-poc"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
vii = "0.0"

// src/main.rs
use std::env;
use std::net::TcpStream;

use vii::plugin::Plugin;
use vii::plugin::PluginConfig;

struct MyPlugin{
    ip: String,
    port: String,
}

/// Make your struct, MyPlugin, into a Plugin ready for Vim.
impl Plugin for MyPlugin {
    fn get_config(&self) -> PluginConfig {
        PluginConfig::new("127.0.0.1".to_string(), "8765".to_string())
    }
    fn plugin(&mut self, _stream: &mut TcpStream) -> Result<(), String> {
        Ok(())
    }
}

fn main() {

  // Environment Variable, to communicate with rust-plug
  let port = env::var("VII_PLUGIN_PORT").unwrap();
  let mut plugin = MyPlugin {
    ip: "127.0.0.1".to_string(),
    port,
  };

  // Run your plugin.
  //
  // Here you can run your plugin as many times as you'd like, create multiple plugins, etc.
  plugin.run();
}

Data Types

Working with Vim data types.

See documentation for supported data types.

#![allow(unused)]
fn main() {
use vii::DataType;

// Using a Vim data type
let vim_float = DataType::Float(3.14);
// Serializing for transmission to Vim
let serialized_float = vim_float.to_string();  // "3.14"

let vim_string = DataType::String("Hello World!".to_string());
let serialized_string = vim_string.to_string();  // "\"Hello World!\""
}

Text Properties

Working with Vim text properties (see :help textprop.txt in Vim).

Note: This is a low-level API.

#![allow(unused)]
fn main() {
use vii::textprop::{
    TextProperty,
    PropertyType,
};
use vii::textprop::PropertyTypeBuilder;

// Create New Property

let prop = TextProperty { id: 0, r#type: "number".to_string() };

// Create New Property Type

let prop_type = PropertyTypeBuilder::default().highlight("Constant".to_string()).build();
}

Channels

Working with Vim channels (see :help channel.txt in Vim).

Note: This is a low-level API. The eventual, high-level API should look like let expr = Expr::from("line('$')");.

#![allow(unused)]
fn main() {
use vii::channel::{
    ChannelCommand,
    Call,
    Expression,
};

// Number of Lines in Current Buffer
// ["expr","line('$')"]
let expression = ChannelCommand::Expr(
    Expression {
        expression: "line('$')".to_string(),
    },
    None,
);

// Number of Lines in Current Buffer
// ["call", "line", ["$"]]
let call = ChannelCommand::Call(
    Call {
        function: "line".to_string(),
        args: vec![DataType::String("$")],
    },
    None,
);


println!("{}", expression.to_string());
// ["expr","line('$')"]
println!("{}", call.to_string());
// ["call", "line", ["$"]]
}

vii