---
name: "gv_lua"
section: "3"
platform: "linux"
package: "libgv-lua"
version: "2.20.2-3"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/gv_lua"
---

# gv\_lua(3)

graph manipulation in lua

## NAME

gv\_lua - graph manipulation in lua

## SYNOPSIS

\#!/usr/bin/lua\
 require('gv')

## USAGE

## INTRODUCTION

**gv\_lua** is a dynamically loaded extension for **lua** that provides access to the graph facilities of **graphviz.**

## COMMANDS

- **New graphs**

  - New empty graph

  *graph\_handle* **gv.graph** *(name);*\
   *graph\_handle* **gv.digraph** *(name);*\
   *graph\_handle* **gv.strictgraph** *(name);*\
   *graph\_handle* **gv.strictdigraph** *(name);*\

- New graph from a dot-syntax string or file

  *graph\_handle* **gv.readstring** *(string);*\
   *graph\_handle* **gv.read** *(filename);*\
   *graph\_handle* **gv.read** *(channel);*\

- Add new subgraph to existing graph

  *graph\_handle* **gv.graph** *(graph\_handle, name);*\

- **New nodes**

  - Add new node to existing graph

  *node\_handle* **gv.node** *(graph\_handle, name);*\

- **New edges**

  - Add new edge between existing nodes

  *edge\_handle* **gv.edge** *(tail\_node\_handle, head\_node\_handle);*\

- Add a new edge between an existing tail node, and a named head node which will be induced in the graph if it doesn't already exist

  *edge\_handle* **gv.edge** *(tail\_node\_handle, head\_name);*\

- Add a new edge between an existing head node, and a named tail node which will be induced in the graph if it doesn't already exist

  *edge\_handle* **gv.edge** *(tail\_name, head\_node\_handle);*\

- Add a new edge between named tail and head nodes which will be induced in the graph if they don't already exist

  *edge\_handle* **gv.edge** *(graph\_handle, tail\_name, head\_name);*\

- **Setting attribute values**

  - Set value of named attribute of graph/node/edge - creating attribute if necessary

  *string* **gv.setv** *(graph\_handle, attr\_name, attr\_value);*\
   *string* **gv.setv** *(node\_handle, attr\_name, attr\_value);*\
   *string* **gv.setv** *(edge\_handle, attr\_name, attr\_value);*\

- Set value of existing attribute of graph/node/edge (using attribute handle)

  *string* **gv.setv** *(graph\_handle, attr\_handle, attr\_value);*\
   *string* **gv.setv** *(node\_handle, attr\_handle, attr\_value);*\
   *string* **gv.setv** *(edge\_handle, attr\_handle, attr\_value);*\

- **Getting attribute values**

  - Get value of named attribute of graph/node/edge

  *string* **gv.getv** *(graph\_handle, attr\_name);*\
   *string* **gv.getv** *(node\_handle, attr\_name);*\
   *string* **gv.getv** *(edge\_handle, attr\_name);*\

- Get value of attribute of graph/node/edge (using attribute handle)

  *string* **gv.getv** *(graph\_handle, attr\_handle);*\
   *string* **gv.getv** *(node\_handle, attr\_handle);*\
   *string* **gv.getv** *(edge\_handle, attr\_handle);*\

- **Obtain names from handles**

  *string* **gv.nameof** *(graph\_handle);*\
   *string* **gv.nameof** *(node\_handle);*\
   *string* **gv.nameof** *(attr\_handle);*\

- **Find handles from names**

  *graph\_handle* **gv.findsubg** *(graph\_handle, name);*\
   *node\_handle* **gv.findnode** *(graph\_handle, name);*\
   *edge\_handle* **gv.findedge** *(tail\_node\_handle, head\_node\_handle);*\
   *attribute\_handle* **gv.findattr** *(graph\_handle, name);*\
   *attribute\_handle* **gv.findattr** *(node\_handle, name);*\
   *attribute\_handle* **gv.findattr** *(edge\_handle, name);*\

- **Misc graph navigators returning handles**

  *node\_handle* **gv.headof** *(edge\_handle);*\
   *node\_handle* **gv.tailof** *(edge\_handle);*\
   *graph\_handle* **gv.graphof** *(graph\_handle);*\
   *graph\_handle* **gv.graphof** *(edge\_handle);*\
   *graph\_handle* **gv.graphof** *(node\_handle);*\
   *graph\_handle* **gv.rootof** *(graph\_handle);*\

- **Obtain handles of proto node/edge for setting default attribute values**

  *node\_handle* **gv.protonode** *(graph\_handle);*\
   *edge\_handle* **gv.protoedge** *(graph\_handle);*\

- **Iterators**

  - Iteration termination tests

  *bool* **gv.ok** *(graph\_handle);*\
   *bool* **gv.ok** *(node\_handle);*\
   *bool* **gv.ok** *(edge\_handle);*\
   *bool* **gv.ok** *(attr\_handle);*\

- Iterate over subgraphs of a graph

  *graph\_handle* **gv.firstsubg** *(graph\_handle);*\
   *graph\_handle* **gv.nextsubg** *(graph\_handle, subgraph\_handle);*\

- Iterate over supergraphs of a graph (obscure and rarely useful)

  *graph\_handle* **gv.firstsupg** *(graph\_handle);*\
   *graph\_handle* **gv.nextsupg** *(graph\_handle, subgraph\_handle);*\

- Iterate over edges of a graph

  *edge\_handle* **gv.firstedge** *(graph\_handle);*\
   *edge\_handle* **gv.nextedge** *(graph\_handle, edge\_handle);*\

- Iterate over outedges of a graph

  *edge\_handle* **gv.firstout** *(graph\_handle);*\
   *edge\_handle* **gv.nextout** *(graph\_handle, edge\_handle);*\

- Iterate over edges of a node

  *edge\_handle* **gv.firstedge** *(node\_handle);*\
   *edge\_handle* **gv.nextedge** *(node\_handle, edge\_handle);*\

- Iterate over out-edges of a node

  *edge\_handle* **gv.firstout** *(node\_handle);*\
   *edge\_handle* **gv.nextout** *(node\_handle, edge\_handle);*\

- Iterate over head nodes reachable from out-edges of a node

  *node\_handle* **gv.firsthead** *(node\_handle);*\
   *node\_handle* **gv.nexthead** *(node\_handle, head\_node\_handle);*\

- Iterate over in-edges of a graph

  *edge\_handle* **gv.firstin** *(graph\_handle);*\
   *edge\_handle* **gv.nextin** *(node\_handle, edge\_handle);*\

- Iterate over in-edges of a node

  *edge\_handle* **gv.firstin** *(node\_handle);*\
   *edge\_handle* **gv.nextin** *(graph\_handle, edge\_handle);*\

- Iterate over tail nodes reachable from in-edges of a node

  *node\_handle* **gv.firsttail** *(node\_handle);*\
   *node\_handle* **gv.nexttail** *(node\_handle, tail\_node\_handle);*\

- Iterate over nodes of a graph

  *node\_handle* **gv.firstnode** *(graph\_handle);*\
   *node\_handle* **gv.nextnode** *(graph\_handle, node\_handle);*\

- Iterate over nodes of an edge

  *node\_handle* **gv.firstnode** *(edge\_handle);*\
   *node\_handle* **gv.nextnode** *(edge\_handle, node\_handle);*\

- Iterate over attributes of a graph

  *attribute\_handle* **gv.firstattr** *(graph\_handle);*\
   *attribute\_handle* **gv.nextattr** *(graph\_handle, attr\_handle);*\

- Iterate over attributes of an edge

  *attribute\_handle* **gv.firstattr** *(edge\_handle);*\
   *attribute\_handle* **gv.nextattr** *(edge\_handle, attr\_handle);*\

- Iterate over attributes of a node

  *attribute\_handle* **gv.firstattr** *(node\_handle);*\
   *attribute\_handle* **gv.nextattr** *(node\_handle, attr\_handle);*\

- **Remove graph objects**

  *bool* **gv.rm** *(graph\_handle);*\
   *bool* **gv.rm** *(node\_handle);*\
   *bool* **gv.rm** *(edge\_handle);*\

- **Layout**

  - Annotate a graph with layout attributes and values using a specific layout engine

  *bool* **gv.layout** *(graph\_handle, engine);*\

- **Render**

  - Render a layout into attributes of the graph

  *bool* **gv.render** *(graph\_handle);*\

- Render a layout in a specific format

  *bool* **gv.render** *(graph\_handle, format);*\
   *bool* **gv.render** *(graph\_handle, format, filename);*\
   *bool* **gv.render** *(graph\_handle, format, channel);*\
   *string* **gv.renderdata** *(graph\_handle, format);*\

- Writing graph back to file

  *bool* **gv.write** *(graph\_handle, filename);*\
   *bool* **gv.write** *(graph\_handle, channel);*\

## KEYWORDS

graph, dot, neato, fdp, circo, twopi, lua.