Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sdm-lang/sdml-ctags

Universal Ctags support for SDML
https://github.com/sdm-lang/sdml-ctags

ctags emacs sdml vim

Last synced: 5 days ago
JSON representation

Universal Ctags support for SDML

Awesome Lists containing this project

README

        

# Universal Ctags SDML Support

This repository contains a configuration file to allow [Universal
Ctags](https://ctags.io/) 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.

```bash
❯ 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.

```bash
❯ 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.

```sdml
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.

```bash
❯ ./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.

```bash
❯ ./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.

``` bash
❯ 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](https://github.com/universal-ctags/ctags) `README.md` file,
but for macos or Linux these seem to be the most commonly used methods:

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

## License

```text
Copyright (c) 2024 Simon Johnston

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.
```

## 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.

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

Thank you.