#    interface_definition.rnc: VyConf reference tree XML grammar
#
#    Copyright (C) 2014 VyOS Development Group <maintainers@vyos.net>
#
#    This library is free software; you can redistribute it and/or
#    modify it under the terms of the GNU Lesser General Public
#    License as published by the Free Software Foundation; either
#    version 2.1 of the License, or (at your option) any later version.
#
#    This library is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#    Lesser General Public License for more details.
#
#    You should have received a copy of the GNU Lesser General Public
#    License along with this library; if not, write to the Free Software
#    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
#    USA

# The language of this file is compact form RELAX-NG
# http://relaxng.org/compact-tutorial-20030326.htm
# (unless converted to XML, then just RELAX-NG :)

# Interface definition starts with interfaceDefinition tag that may contain node tags
start = element interfaceDefinition
{
    extendsAttr?, node*
}

# Interface definitions may extend other definitions
# In this case you specify a whitespace-separated path
extendsAttr = attribute extends
{
    text
}

# Normal and tag nodes may have children
children = element children
{
    (node | tagNode | leafNode)+
}

# Nodes may have properties
# For simplicity, any property is allowed in any node,
# but whether they are used or not is implementation-defined
properties = element properties
{
    helpString?,
    constraint?,

    # These are meaningful only for leaf nodes
    valueHelpString?,
    (multi | valueless)?
}

# node tag may contain node, leafNode, or tagNode tags
# Those are intermediate configuration nodes that may only contain
# other nodes and must not have values
node = element node
{
    (ownerAttr? & nodeNameAttr),
    (properties? & children? )
}

# All nodes must have "name" attribute
nodeNameAttr = attribute name
{
    text
}

# Ordinary nodes and tag nodes can have "owner" attribute.
# Owner is the component that is notified when node changes.
ownerAttr = attribute owner
{
    text
}

# Tag and leaf nodes may have constraints on their names and values
# (respectively).
# When multiple constraints are listed, they work as logical OR
constraint = element constraint
{
    (regex | validator)+ &
    errorMessage?
}

# A constraint may be a regex pattern
regex = element regex
{
    text
}

# A constraint may also use an external validator
validator = element validator
{
    (validatorNameAttr & validatorArgumentAttr),
    empty
}

# Validators are named
validatorNameAttr = attribute name
{
    text
}

# An argument can be passed to validator, in addition to the value to be validated
validatorArgumentAttr = attribute argument
{
    text
}

# When validation fails, a message can be shown
errorMessage = element errorMessage
{
    text
}

# Tag nodes are containers for nodes without predefined names, like network interfaces
# or user names (e.g. "interfaces ethernet eth0" or "user jrandomhacker")
# Tag nodes may	contain	node and leafNode elements, and also nameConstraint tags
# They must not contain other tag nodes
tagNode = element tagNode
{
    (ownerAttr? & nodeNameAttr),
    (properties? & children )
}

# Leaf nodes are terminal configuration nodes that can't have children,
# but can have values.
# Leaf node may contain one or more valueConstraint tags
# If multiple valueConstraint tags are used, they work a logical OR
# Leaf nodes can have "multi" attribute that indicated that it can have
# more than one value
leafNode = element leafNode
{
    nodeNameAttr,
    properties
}

# Some leaf nodes may have more than one value
multi = element multi
{
    empty
}

# Some leaf nodes may not have values (e.g. enable/disable flags)
valueless = element valueless
{
    empty
}

# helpString tag contains brief description of the purpose of the node
# Must have description= attribute
helpString = element helpString
{
    text
}

# valueHelpString tags contain information about acceptable value format
valueHelpString = element valueHelpString
{
    text
}