Crate nodeset

Crate nodeset 

Source
Expand description

crates.io docs.rs

§Description

nodeset is a Rust library and command-line tool (ns) that deals with nodesets. It is heavily inspired by clustershell and aims at supporting the same nodeset representation in Rust. It also provides a C API for use in other languages.

A nodeset is a set of names which are generally indexed over one or more integer dimensions such as node1 or r1sw2-port0. Large nodesets can be represented in a compact way using a bracket notation such as node[1-1000]. When brackets are used in multiple dimensions, it implies a cartesian product. For example: r[1-2]sw[1-2]-port[1-2] represents 8 ports: r1sw1-port1,r1sw1-port2,r1sw2-port1,...,r2sw2-port2.

ns allows to fold or expand nodesets, as well as to perform algebraic operations on them (union, intersection, difference, …)

§Command line examples

  • Listing nodes:
$ ns list r[2-4/2]sw1-port[23-24]
r2esw1-port23 r2sw1-port24 r4sw1-port23 r4sw1-port24
  • Folding nodes:
$ ns fold r2esw1-port23 r2sw1-port24 r4sw1-port23 r4sw1-port24
r[2,4]esw1-port[23-24]
  • Counting nodes:
$ ns count r[2-4/2]esw1-port[23-24]
4
  • Algebraic operations using operators:
$ ns fold 'node[0-10] - (node[0-5] node[7-10])'
node6

$ ns fold 'node[1-2] ^ node[2-3]'
node[1,3]

§Configuration files and groups

ns understands and uses clustershell’s configuration files in which node groups can be defined. Please refer to clustershell’s documentation for a full description of the configuration files syntax.

§Library usage example

To compute and display the intersection of two nodesets

    use nodeset::NodeSet;

    let ns1: NodeSet = "node[01-15]".parse().unwrap();
    let ns2: NodeSet = "node[10-30/2]".parse().unwrap();
    let inter = ns1.intersection(&ns2);
    assert_eq!(inter.to_string(), "node[10,12,14]");

§C bindings

Along with the CLI binary (ns), running cargo build --all from the crate root generates the libnodeset.so C dynamic library. The C API is described in the nodeset.h header.

The following example shows how to iterate over a nodeset. More complete examples are available in the examples directory.

#include <stdio.h>
#include "nodeset-capi/include/nodeset.h"

int main(int argc, char **argv)
{
    NodeSet *nodeset;
    NodeSetIter *iter;
    char *node;

    /* Parse a nodeset */
    if ((nodeset = ns_parse("node[1-5]&node[5-10],node4", NULL)) == NULL) {
        return 1;
    }

    /* Iterate over the nodes */
    iter = ns_iter(nodeset);
    while ((node = ns_iter_next(iter, NULL)) != NULL) {
        printf("%s\n", node);
        ns_free_node(node);
    }

    /* Check whether the iterator ended due to an error */
    if (ns_iter_status(iter) != 0) {
        return 1;
    }

    /* Free the iterator and nodeset */
    ns_free_iter(iter);
    ns_free_nodeset(nodeset);

    return 0;
}

§Why use this crate

This project is not as mature as clustershell and has fewer features. However, compared to clustershell’s nodeset tool written in Python, ns starts much faster as it doesn’t rely on an interpreter. It can save a lot of time when performing multiple operations on nodesets in a shell script. It is also faster at parsing and performing operations on large nodesets. Last but not least, the library crate can be used to handle nodesets natively in Rust or C while sharing group definitions with clustershell.

§Similar rust projects

Structs§

IdRangeList
A 1D set of indexes stored in a Vec
IdRangeTree
A 1D set of indices stored in a BTreeSet
NodeSet
An unordered collection of nodes indexed in one or more dimensions.
NodeSetIter
An iterator over nodes in a NodeSet
Parser
Parse strings into nodesets
Resolver
An inventory of group sources used to resolve group names to node sets

Enums§

NodeSetParseError
Errors that may happen when parsing nodesets