Universal Ctags SDML Support

This repository contains a configuration file to allow Universal Ctags to create tag files for SDML source.

This allows code navigation in ctags-, or etags-, aware tools such as vim and Emacs. The following command will create a common tags file for all SDML files, recursively using the -R argument. To generate Emacs compatible ETAGS files add the -e argument.

❯ ctags -R *.sdm?

By default the command will create definition tags only, which is OK as these are the primary purpose of the tool anyway. If you wish to see references you need to enable them on the command-line with the following arguments.

❯ ctags -R --extras=+r --fields=+r *.sdm?

This creates tags as follows.

Name	Definition Kind	Reference Kind	Reference Role	Notes
Module	M	M	imported	1
Datatype	d	d, t	base, type	2
Entity	E	E, t	source, type	3
Enum	e	t	type
Event	x	t	type
Property	p	p	ref
Structure	s	t	type
Union	u	t	type
Member	m	N/A	N/A
Variant	V	N/A	N/A
Annotation Property	N/A	t	assertion	4
Annotation Constraint	C	N/A	N/A
Type	t	t	imported	5

1. Any unqualified name in an import statement is noted as an imported module reference.
2. Datatypes are required to have a base type, this is noted as a base datatype reference.
3. Events denote the source that emits them, this is noted as a source entity reference.
4. The name part of an annotation property is noted as an assertion reference. If the right-hand side of an annotation property is a qualified name it is noted as a type reference.
5. Any qualified name in an import statement is noted as an imported module reference.

module example is
  ;    ^ M:def

  import dc
  ;      ^ M:imported
  
  import xsd:integer
  ;      ^ t:imported

  @dc:description = "An example"@en
  ;^ t:assertion

  @dc:version =   xsd:decimal(2)
  ;^ t:assertion  ^ t:type
  
  datatype MyInteger <- integer
    ;      ^ d:def      ^ d:base

  property thingIdentifier -> MyInteger
    ;      ^ p:def            ^ t:type

  entity BigThing is
    ;    ^ E:def
    identity ref thingIdentifier
    ;            ^ p:ref

    name -> {0..1} string
    ;^ m:def       ^ t:type
  end

  enum ThingEnum of
    ;  ^ e:def
    ThingOne
    ; ^ V:def
    ThingTwo
    ; ^ V:def
  end
  
  event NewThing source BigThing
    ;   ^ x:def         ^ E:source
  
  structure LittleThing
  ;         ^ s:def
  
  structure OtherThing
  ;         ^ s:def

  union Things of
  ;     ^ u:def
    LittleThing
    ; ^ V:def
    OtherThing as SmallThing
    ;             ^ V:def
  end
  
end

Installation

The file sdml.ctags should be copied to, or linked into, the Ctags configuration directory which can be performed by the shell script install.sh.

The easiest way to install is to use the script with no arguments in which case the file in the same directory will be linked into the configuration directory. Adding the argument link has the same effect.

If you prefer to copy the file, instead of linking, as part of the install add the copy argument.

❯ ./install.sh
Linking from /home/me/.config/ctags/sdml.ctags to /home/me/gh/sdml-ctags/sdml.ctags

To remove the configuration file from the ctags configuration directory the install script takes a remove argument.

❯ ./install.sh remove
Removing installed file /home/me/.config/ctags/sdml.ctags

Installing Universal Ctags

If you have a ctags command, ensure you are running Universal Ctags by checking the result of the version command.

❯ ctags --version
Universal Ctags 6.1.0, Copyright (C) 2015-2023 Universal Ctags Team
Universal Ctags is derived from Exuberant Ctags.
Exuberant Ctags 5.8, Copyright (C) 1996-2009 Darren Hiebert
  Compiled: Jul  1 2024, 15:08:57
  URL: https://ctags.io/
  Output version: 0.0
  Optional compiled features: ... 

Detailed installation instructions are in the project's Github README.md file, but for macos or Linux these seem to be the most commonly used methods:

❯ brew install universal-ctags # macos, Linux
❯ sudo snap install universal-ctags # Linux

License(s)

The contents of this repository are made available under the following licenses:

Apache-2.0

Copyright 2025 Simon Johnston <[email protected]>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

See the enclosed file LICENSE-Apache.

MIT

Copyright 2025 Simon Johnston <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See the enclosed file LICENSE-MIT.

Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Changes

Version 0.1.0

• Initial release

Issues

If you find an issue, please include the following in your report.

1. A minimum working example (MWE), example.sdml.
2. The output of the command ctags --version.
3. The file tags and ctags.out generated by the following command.
4. The exact command-line arguments you were using.

❯ ctags --verbose --sort=no example.sdm >ctags.out 2>&1

Thank you.