Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jakewharton/cite
A Kotlin compiler plugin for embedding information about the file being compiled
https://github.com/jakewharton/cite
Last synced: 13 days ago
JSON representation
A Kotlin compiler plugin for embedding information about the file being compiled
- Host: GitHub
- URL: https://github.com/jakewharton/cite
- Owner: JakeWharton
- License: apache-2.0
- Created: 2023-02-03T04:40:34.000Z (almost 2 years ago)
- Default Branch: trunk
- Last Pushed: 2024-04-12T22:57:58.000Z (7 months ago)
- Last Synced: 2024-04-14T08:41:39.152Z (7 months ago)
- Language: Kotlin
- Homepage:
- Size: 207 KB
- Stars: 248
- Watchers: 5
- Forks: 5
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Cite for Kotlin
A Kotlin compiler plugin for embedding information about the file being compiled.
For example, given:
```kotlin
object Greeter {
fun sayHi() {
println("Hello: $__FILE__, $__TYPE__, $__MEMBER_, $__LINE__")
}
}
```
When invoked, this will output:
```
Hello: main.kt, Greeter, sayHi, 16
```
The Java bytecode shows values were resolved at compile time:
```
9: getstatic #19 // Field java/lang/System.out:Ljava/io/PrintStream;
11: ldc #27 // String Hello: main.kt, Greeter, sayHi, 16
14: invokevirtual #25 // Method java/io/PrintStream.println:(Ljava/lang/Object;)V
```
The values are constants, so they can be folded with other constants.
Every Kotlin target is supported. Here's JS:
```js
Greeter.prototype.h = function () {
println('Hello: main.kt, Greeter, sayHi, 16');
};
```
Native (as LLVM IR, and you might need your ASCII table):
```
@792 = … { …, [34 x i16] [i16 72, i16 101, i16 108, i16 108, i16 111, i16 58, i16 32, i16 109, i16 97, i16 105, i16 110, i16 46, i16 107, i16 116, i16 44, i16 32, i16 71, i16 114, i16 101, i16 101, i16 116, i16 101, i16 114, i16 44, i16 32, i16 115, i16 97, i16 121, i16 72, i16 105, i16 44, i16 32, i16 49, i16 54] }
⋮
call void @Kotlin_io_Console_println(… ({ %struct.ArrayHeader, [34 x i16] }* @792 …)), !dbg !12017
```
## API
Four properties are provided:
| Property | Type | Description | Example |
|--------------|----------|------------------------------------------------------------------|-----------|
| `__FILE__` | `String` | Filename of the source file. | "main.kt" |
| `__TYPE__` | `String` | Name of the nearest enclosing class, object, interface, or enum. | "Greeter" |
| `__MEMBER__` | `String` | Name of the nearest enclosing function or property body. | "sayHi" |
| `__LINE__` | `Int` | One-based line number of this property access. | 16 |
Use of a property in a location without an associated enclosing type is an error.
For example, using `__TYPE__` in a top-level function will fail to compile.
## Usage
Add the buildscript dependency and apply the plugin to each module in which
you want to access the properties.
```groovy
buildscript {
repository {
mavenCental()
}
dependencies {
classpath 'com.jakewharton.cite:cite-gradle-plugin:0.2.0'
}
}
apply plugin: 'org.jetbrains.kotlin.multiplatform' // Or .jvm
apply plugin: 'com.jakewharton.cite'
```
The runtime dependency will be added as an `implementation` dependency automatically.
Never add the runtime dependency yourself, as use without the plugin will not work.
Snapshots of the development version are available in Sonatype's snapshots repository.
```groovy
buildscript {
repositories {
mavenCentral()
maven {
url 'https://oss.sonatype.org/content/repositories/snapshots/'
}
}
dependencies {
classpath 'com.jakewharton.cite:cite-gradle-plugin:0.3.0-SNAPSHOT'
}
}
apply plugin: 'org.jetbrains.kotlin.multiplatform' // Or .jvm
apply plugin: 'com.jakewharton.cite'
```
### Compatibility
Since Kotlin compiler plugins are an unstable API, certain versions of Cite only work with
certain versions of Kotlin.
| Kotlin | Cite |
|----------------|---------------|
| 1.8.0 - 1.9.20 | 0.1.0 - 0.2.0 |
Kotlin versions newer than those listed may be supported but have not been tested.
# License
Copyright 2023 Jake Wharton
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.