Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/sdm-lang/sdml-ctags
- Owner: sdm-lang
- License: apache-2.0
- Created: 2024-07-13T00:20:29.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-08-29T01:57:23.000Z (3 months ago)
- Last Synced: 2024-10-18T08:44:40.870Z (27 days ago)
- Topics: ctags, emacs, sdml, vim
- Language: Shell
- Homepage: https://sdml.io
- Size: 14.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
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:defimport 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:baseproperty thingIdentifier -> MyInteger
; ^ p:def ^ t:typeentity BigThing is
; ^ E:def
identity ref thingIdentifier
; ^ p:refname -> {0..1} string
;^ m:def ^ t:type
endenum 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:defunion 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 JohnstonLicensed 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 athttp://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.