[sunzi/development] doc/concepts: add vim syntax file to read easier

commit 04390284cf80a2d26794b0732a2b522850e224bb Author: Jan Pokorný <jpokorny(a)redhat.com&gt; 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&gt; 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"