commit 04390284cf80a2d26794b0732a2b522850e224bb
Author: Jan Pokorný <jpokorny(a)redhat.com>
Date: Mon Feb 27 15:36:36 2012 +0100
doc/concepts: add vim syntax file to read easier
Signed-off-by: Jan Pokorný <jpokorny(a)redhat.com>
doc/_vimrc_local.vim | 12 +
doc/concepts | 521 +++++++++++++++++++++++++++++++++++++++++++++--
doc/concepts_syntax.vim | 30 +++
3 files changed, 548 insertions(+), 15 deletions(-)
---
diff --git a/doc/_vimrc_local.vim b/doc/_vimrc_local.vim
new file mode 100644
index 0000000..57e32ee
--- /dev/null
+++ b/doc/_vimrc_local.vim
@@ -0,0 +1,12 @@
+" extra syntax for concepts file
+
+set expandtab
+set tabstop=8
+set softtabstop=4
+set shiftwidth=4
+
+" hack to register syntax + reread file using it's modeline
+if expand('%:t') == 'concepts'
+ au! Syntax concepts source <sfile>:h/concepts_syntax.vim
+ edit!
+endif
diff --git a/doc/concepts b/doc/concepts
index 1d22d98..b536380 100644
--- a/doc/concepts
+++ b/doc/concepts
@@ -1,18 +1,319 @@
-This documents uses hypothetical free-form understandable
-OOP-like language to define concepts in the project and
-the relations amongst them (inspired by Elixir a bit).
-
-Flags used so far:
- <no flag> general attribute
- @one-of contraint for the concept domain: at least one
- specification must fit
- @refcollection collection as a bunch of references to items
- of other concept (aggregation/composition)
- @refsingle single reference to item of other concept
- (item forming aggregation/composition)
- @enum enumeration values
- @dynamic attributes highly dynamic
+# vim: set syntax=concepts: <-- see concepts_syntax.vim
+#
+# This documents uses hypothetical free-form understandable
+# OOP-like language to define concepts in the project and
+# the relations amongst them (inspired by Elixir a bit).
+# There may be not (and probably is not) 1:1 correspondence
+# with how the things are seen by Pacemaker.
+#
+# Flags used so far:
+# <no flag> general attribute
+# @one-of contraint for the concept domain: at least one
+# specification must fit
+# @refcollection collection as a bunch of references to items
+# of other concept (aggregation/composition)
+# @refsingle single reference to item of other concept
+# (item forming aggregation/composition)
+# @enum enumeration values
+# @dynamic attributes highly dynamic
+#
+# Q: contraints for any undefined "singleval", e.g.
+# - UTF-8, 1-63 length, excluding ':'
+
+
+# -- META -----------------------------------------------------------------
+# MetaString and such have obvious meaning, omitted
+# Similarly, known lexical-based concepts marked <CONCEPT> and omitted
+
+
+# -- GENERAL --------------------------------------------------------------
+
+concept HostnameOrIP derives MetaString:
+ @one-of
+ <FQDN>
+ <IPv4> # only single canonical notation (?)
+ <IPv6> # beware: plenty of notations
+
+concept MulticastAddress derives MetaString:
+ @one-of
+ MulticastIPv4
+ MulticastIPv6
+
+concept MulticastIPv4:
+ # Q: restricted to range of D/E-class only?
+
+concept MulticastIPv6:
+ # Q: restrictions here?
+
+concept SyslogFacility derives MetaEnumeration:
+ @enum
+ SfDaemon
+ ...
+
+concept SyslogPriority derives MetaEnumeration:
+ @enum
+
+ SpInfo
+# vim: set filetype=concepts: <-- see concepts_syntax.vim
+# vim: set filetype=concepts: <-- see concepts_syntax.vim
+#
+# This documents uses hypothetical free-form understandable
+# OOP-like language to define concepts in the project and
+# the relations amongst them (inspired by Elixir a bit).
+# There may be not (and probably is not) 1:1 correspondence
+# with how the things are seen by Pacemaker.
+#
+# Flags used so far:
+# <no flag> general attribute
+# @one-of contraint for the concept domain: at least one
+# specification must fit
+# @refcollection collection as a bunch of references to items
+# of other concept (aggregation/composition)
+# @refsingle single reference to item of other concept
+# (item forming aggregation/composition)
+# @enum enumeration values
+# @dynamic attributes highly dynamic
+#
+# Q: contraints for any undefined "singleval", e.g.
+# - UTF-8, 1-63 length, excluding ':'
+
+
+# -- META -----------------------------------------------------------------
+# MetaString and such have obvious meaning, omitted
+# Similarly, known lexical-based concepts marked <CONCEPT> and omitted
+
+
+# -- GENERAL --------------------------------------------------------------
+
+concept HostnameOrIP derives MetaString:
+ @one-of
+ <FQDN>
+ <IPv4> # only single canonical notation (?)
+ <IPv6> # beware: plenty of notations
+
+concept MulticastAddress derives MetaString:
+ @one-of
+ MulticastIPv4
+ MulticastIPv6
+
+concept MulticastIPv4:
+ # Q: restricted to range of D/E-class only?
+
+concept MulticastIPv6:
+ # Q: restrictions here?
+
+concept SyslogFacility derives MetaEnumeration:
+ @enum
+ SfDaemon
+ ...
+
+concept SyslogPriority derives MetaEnumeration:
+ @enum
+ SpInfo
+ SpDebug
+ ...
+
+
+# -- CLUSTER --------------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/pacemaker-1.2.rng
+
+concept Cluster:
+ # cluster
+ name
+ # fence
+ fencePostFailDelay
+ fencePostJoinDelay
+ # network
+ networkCommunication: ClusterNetworkCommunication
+ # Pacemaker
+ ...
+ # logging
+ globalLogging: ClusterGlobalLogging
+ otherLogging: ClusterOtherLogging[]
+ @dynamic
+ # Q: is configuration version relevant?
+ configurationVersion
+ status: ClusterStatus
+ @refcollection
+ nodes: Node[]
+
+concept ClusterLogging:
+ # TODO
+
+concept ClusterGlobalLogging derives ClusterLogging:
+ logBuggingMessages: MetaBool
+ syslog: MetaBool
+ syslogFacility: SyslogFacility
+ syslogPriority: SyslogPriority
+
+concept ClusterNetworkCommunication:
+ @one-of
+ CncUDPAuto
+ CncUDPManual
+ # Q: can be more addresses?
+ multicastAddress: MulticastAddress[]
+ CncUDPUnicast
+
+concept ClusterStatus:
+ # Q: ?
+
+# Q: is this relevant after all?
+concept ClusterDaemon:
+ name
+ @dynamic
+ status: ClusterDaemonStatus
+
+# Q: dtto
+concept ClusterDaemonStatus derives MetaEnumeration:
+ @enum
+ # Q: guessed for now
+ CdsRunning
+ CdsNotRunning
+ CdsFailed
+
+
+# -- NODES ---------------------------------------------------------------
+
+concept Node:
+ name: HostnameOrIP
+ id
+ @dynamic
+ uptime
+ status: NodeStatus
+ @refsingle
+ # Q: can node be active in more clusters (running or at least declaratively)?
+ cluster: ManyToOne(Cluster, backref=nodes)
+ @refcollection
+ clusterDaemons: ClusterDaemon[]
+ collocatedResources: Resource[]
+ fenceDevices: FenceDevice[]
+ failoverDomains: FailoverDomainRelationship[]
+
+concept NodeStatus derives MetaEnumeration:
+ @enum
+ # Q: guessed for now
+ NsActive
+ NsInactive
+
+
+# -- RESOURCES -----------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/resources-1.2.rng
+
+concept Resource:
+ name
+ class: ResourceClass
+ type: ResourceType
+ provider: ResourceProvider
+ @refsingle
+ location: ManyToOne(Node, backref=collocalatedResources)
+ @refcollection
+ constraints: Constraint[]
+
+concept ResourceClass derives MetaEnumeration:
+ # Q: is this enumeration to be queried at runtime?
+ enum:
+
+concept ResourceType derives MetaEnumeration:
+ # Q: is this enumeration to be queried at runtime?
+ enum:
+
+concept ResourceProvider
+ # Q: also queried at runtime (i.e., dynamical)?
+ name
+
+# sample concrete Resource
+concept ResourceApache derives Resource:
+ serverRoot
+ configFile
+ ...
+# similarly for other resources (not interesting in this context)
+
+
+# -- CONSTRAINTS (aka Resource Dependencies) -----------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/constraints-1.2.rng
+
+concept Contraint:
+ name
+ resourceConstraints: ResourceConstraint[]
+
+concept ResourceConstraint:
+ dependency: ConstrainDependency
+ quantification # Q: ?
+ @refsingle
+ resource: ManyToOne(Resource, backref=constraints)
+ constraint: ManyToOne(Constraint, backref=resourceConstraints)
+
+concept ConstraintDependency derives MetaEnumeration:
+ @enum
+ CdColocation
+ # Q: ?
+
+
+# -- FENCE DEVICES -------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/fencing.rng
+
+concept FenceDevice:
+ name
+ type
+ hostname
+ @dynamic
+ status: FenceDeviceStatus
+
+concept SharedFenceDevice derives FenceDevice:
+ @refcollection
+ nodesUsing: ManyToMany(Node, backref=fenceDevices)
+
+concept NonSharedFenceDevice derives FenceDevice:
+ @refcollection
+ nodesUsing: ManyToOne(Node, backref=fenceDevices)
+
+concept FenceDeviceStatus derives MetaEnumeration:
+ @enum
+ # Q: guessed for now
+ FdsActive
+ FdsInactive
+
+# sample concrete FenceDevice
+concept APCPowerSwitch derives SharedFenceDevice:
+ port
+ login
+ password
+ ...
+# similarly for other fence devices
+
+# -- FAILOVER DOMAINS ----------------------------------------------------
+
+concept FailoverDomain:
+ name
+ prioritized: MetaBool
+ restricted: MetaBool
+ noFailBack: MetaBool
+ @refcollection
+ registeredNodes: FailoverDomainRelationship[]
+
+concept FailoverDomainRelationship:
+ @refsingle
+ node: ManyToOne(Node, backref=failoverDomains)
+ failoverDomain: ManyToOne(FailoverDomain, backref=registeredNodes)
+#
+# This documents uses hypothetical free-form understandable
+# OOP-like language to define concepts in the project and
+# the relations amongst them (inspired by Elixir a bit).
+# There may be not (and probably is not) 1:1 correspondence
+# with how the things are seen by Pacemaker.
+#
+# Flags used so far:
+# <no flag> general attribute
+# @one-of contraint for the concept domain: at least one
+# specification must fit
+# @refcollection collection as a bunch of references to items
+# of other concept (aggregation/composition)
+# @refsingle single reference to item of other concept
+# (item forming aggregation/composition)
+# @enum enumeration values
+# @dynamic attributes highly dynamic
+#
# Q: contraints for any undefined "singleval", e.g.
# - UTF-8, 1-63 length, excluding ':'
@@ -54,6 +355,193 @@ concept SyslogPriority derives MetaEnumeration:
# -- CLUSTER --------------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/pacemaker-1.2.rng
+
+concept Cluster:
+ # cluster
+ name
+ # fence
+ fencePostFailDelay
+ fencePostJoinDelay
+ # network
+ networkCommunication: ClusterNetworkCommunication
+ # Pacemaker
+ ...
+ # logging
+ globalLogging: ClusterGlobalLogging
+ otherLogging: ClusterOtherLogging[]
+ @dynamic
+ # Q: is configuration version relevant?
+ configurationVersion
+ status: ClusterStatus
+ @refcollection
+ nodes: Node[]
+
+concept ClusterLogging:
+ # TODO
+
+concept ClusterGlobalLogging derives ClusterLogging:
+ logBuggingMessages: MetaBool
+ syslog: MetaBool
+ syslogFacility: SyslogFacility
+ syslogPriority: SyslogPriority
+
+concept ClusterNetworkCommunication:
+ @one-of
+ CncUDPAuto
+ CncUDPManual
+ # Q: can be more addresses?
+ multicastAddress: MulticastAddress[]
+ CncUDPUnicast
+
+concept ClusterStatus:
+ # Q: ?
+
+# Q: is this relevant after all?
+concept ClusterDaemon:
+ name
+ @dynamic
+ status: ClusterDaemonStatus
+
+# Q: dtto
+concept ClusterDaemonStatus derives MetaEnumeration:
+ @enum
+ # Q: guessed for now
+ CdsRunning
+ CdsNotRunning
+ CdsFailed
+
+
+# -- NODES ---------------------------------------------------------------
+
+concept Node:
+ name: HostnameOrIP
+ id
+ @dynamic
+ uptime
+ status: NodeStatus
+ @refsingle
+ # Q: can node be active in more clusters (running or at least declaratively)?
+ cluster: ManyToOne(Cluster, backref=nodes)
+ @refcollection
+ clusterDaemons: ClusterDaemon[]
+ collocatedResources: Resource[]
+ fenceDevices: FenceDevice[]
+ failoverDomains: FailoverDomainRelationship[]
+
+concept NodeStatus derives MetaEnumeration:
+ @enum
+ # Q: guessed for now
+ NsActive
+ NsInactive
+
+
+# -- RESOURCES -----------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/resources-1.2.rng
+
+concept Resource:
+ name
+ class: ResourceClass
+ type: ResourceType
+ provider: ResourceProvider
+ @refsingle
+ location: ManyToOne(Node, backref=collocalatedResources)
+ @refcollection
+ constraints: Constraint[]
+
+concept ResourceClass derives MetaEnumeration:
+ # Q: is this enumeration to be queried at runtime?
+ enum:
+
+concept ResourceType derives MetaEnumeration:
+ # Q: is this enumeration to be queried at runtime?
+ enum:
+
+concept ResourceProvider
+ # Q: also queried at runtime (i.e., dynamical)?
+ name
+
+# sample concrete Resource
+concept ResourceApache derives Resource:
+ serverRoot
+ configFile
+ ...
+# similarly for other resources (not interesting in this context)
+
+
+# -- CONSTRAINTS (aka Resource Dependencies) -----------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/constraints-1.2.rng
+
+concept Contraint:
+ name
+ resourceConstraints: ResourceConstraint[]
+
+concept ResourceConstraint:
+ dependency: ConstrainDependency
+ quantification # Q: ?
+ @refsingle
+ resource: ManyToOne(Resource, backref=constraints)
+ constraint: ManyToOne(Constraint, backref=resourceConstraints)
+
+concept ConstraintDependency derives MetaEnumeration:
+ @enum
+ CdColocation
+ # Q: ?
+
+
+# -- FENCE DEVICES -------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/fencing.rng
+
+concept FenceDevice:
+ name
+ type
+ hostname
+ @dynamic
+ status: FenceDeviceStatus
+
+concept SharedFenceDevice derives FenceDevice:
+ @refcollection
+ nodesUsing: ManyToMany(Node, backref=fenceDevices)
+
+concept NonSharedFenceDevice derives FenceDevice:
+ @refcollection
+ nodesUsing: ManyToOne(Node, backref=fenceDevices)
+
+concept FenceDeviceStatus derives MetaEnumeration:
+ @enum
+ # Q: guessed for now
+ FdsActive
+ FdsInactive
+
+# sample concrete FenceDevice
+concept APCPowerSwitch derives SharedFenceDevice:
+ port
+ login
+ password
+ ...
+# similarly for other fence devices
+
+
+# -- FAILOVER DOMAINS ----------------------------------------------------
+
+concept FailoverDomain:
+ name
+ prioritized: MetaBool
+ restricted: MetaBool
+ noFailBack: MetaBool
+ @refcollection
+ registeredNodes: FailoverDomainRelationship[]
+
+concept FailoverDomainRelationship:
+ @refsingle
+ node: ManyToOne(Node, backref=failoverDomains)
+ failoverDomain: ManyToOne(FailoverDomain, backref=registeredNodes)
+ SpDebug
+ ...
+
+
+# -- CLUSTER --------------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/pacemaker-1.2.rng
concept Cluster:
# cluster
@@ -89,7 +577,7 @@ concept ClusterNetworkCommunication:
CncUDPAuto
CncUDPManual
# Q: can be more addresses?
- multicastAddress MulticastAddress[]
+ multicastAddress: MulticastAddress[]
CncUDPUnicast
concept ClusterStatus:
@@ -135,6 +623,7 @@ concept NodeStatus derives MetaEnumeration:
# -- RESOURCES -----------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/resources-1.2.rng
concept Resource:
name
@@ -167,6 +656,7 @@ concept ResourceApache derives Resource:
# -- CONSTRAINTS (aka Resource Dependencies) -----------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/constraints-1.2.rng
concept Contraint:
name
@@ -186,6 +676,7 @@ concept ConstraintDependency derives MetaEnumeration:
# -- FENCE DEVICES -------------------------------------------------------
+# see
https://github.com/ClusterLabs/pacemaker/blob/master/xml/fencing.rng
concept FenceDevice:
name
diff --git a/doc/concepts_syntax.vim b/doc/concepts_syntax.vim
new file mode 100644
index 0000000..3c75016
--- /dev/null
+++ b/doc/concepts_syntax.vim
@@ -0,0 +1,30 @@
+" common prologue skipped
+
+if exists("b:current_syntax")
+ finish
+endif
+
+syn keyword conceptStatement concept derives
+syn keyword conceptKeyword backref
+syn keyword conceptRelation ManyToOne ManyToMany
+syn keyword conceptMeta MetaEnumeration
+
+syn match conceptComment "\(#.*\)"
+syn match conceptKind "\(@.[^ ]*\)"
+syn match conceptLexical "\(<[a-zA-Z0-9_]\+>\)"
+
+" blindly borrowed from python.vim
+syn match conceptDefinition "\%(\%(concept\|derives\)\s*\)\@<=\h\%(\w\)*"
+syn match conceptType "\%(\%(:\|(\)\s*\)\@<=\h\%(\w\)*\(\[\]\)\?"
+
+highlight link conceptStatement Statement
+highlight link conceptKeyword Keyword
+highlight link conceptComment Comment
+highlight link conceptKind Define
+highlight link conceptMeta Include
+highlight link conceptRelation Operator
+highlight link conceptDefinition Identifier
+highlight link conceptType Structure
+highlight link conceptLexical String
+
+"let b:current_syntax = "concepts"