tiny.smg.zig

1pub const zig = @import("zig.zig");

1const std = @import("std");2const lines = @import("lines.zig");34/// An exact half-open declaration range in parsed Zig source.5pub const SourceSpan = struct {6    start_byte: u32,7    end_byte: u32,8};910pub fn tokenLine(source_lines: lines.SourceLines, ast: *const std.zig.Ast, token: std.zig.Ast.TokenIndex) i64 {11    return lines.lineForByte(source_lines, @intCast(ast.tokenStart(token)));12}1314pub fn nodeLine(source_lines: lines.SourceLines, ast: *const std.zig.Ast, node: std.zig.Ast.Node.Index) i64 {15    return tokenLine(source_lines, ast, ast.firstToken(node));16}1718pub fn nodeEndLine(source_lines: lines.SourceLines, ast: *const std.zig.Ast, node: std.zig.Ast.Node.Index) i64 {19    return tokenLine(source_lines, ast, ast.lastToken(node));20}2122/// Extracts leading file documentation from //! tokens.23pub fn moduleDocstring(24    allocator: std.mem.Allocator,25    ast: *const std.zig.Ast,26) !?[]const u8 {27    var end: std.zig.Ast.TokenIndex = 0;28    while (end < ast.tokens.len and ast.tokenTag(end) == .container_doc_comment) {29        end += 1;30    }31    return try docstring(allocator, ast, 0, end, .container_doc_comment);32}3334/// Extracts the contiguous /// tokens attached before a declaration.35pub fn declarationDocstring(36    allocator: std.mem.Allocator,37    ast: *const std.zig.Ast,38    node: std.zig.Ast.Node.Index,39) !?[]const u8 {40    var start = ast.firstToken(node);41    const end = start;42    while (start > 0 and ast.tokenTag(start - 1) == .doc_comment) start -= 1;43    return try docstring(allocator, ast, start, end, .doc_comment);44}4546/// Returns attached documentation and the complete declaration terminator.47pub fn declarationSourceSpan(48    ast: *const std.zig.Ast,49    node: std.zig.Ast.Node.Index,50) SourceSpan {51    var first = ast.firstToken(node);52    while (first > 0 and ast.tokenTag(first - 1) == .doc_comment) first -= 1;53    const last = ast.lastToken(node);54    var end = ast.tokenStart(last) + ast.tokenSlice(last).len;55    if (last + 1 < ast.tokens.len and ast.tokenTag(last + 1) == .semicolon) {56        const terminator = last + 1;57        end = ast.tokenStart(terminator) + ast.tokenSlice(terminator).len;58    }59    const start = ast.tokenStart(first);60    std.debug.assert(start < end);61    std.debug.assert(end <= ast.source.len);62    return .{ .start_byte = @intCast(start), .end_byte = @intCast(end) };63}6465/// Extracts the contiguous /// tokens attached before a source token.66pub fn tokenDocstring(67    allocator: std.mem.Allocator,68    ast: *const std.zig.Ast,69    token: std.zig.Ast.TokenIndex,70) !?[]const u8 {71    var start = token;72    while (start > 0 and ast.tokenTag(start - 1) == .doc_comment) start -= 1;73    return try docstring(allocator, ast, start, token, .doc_comment);74}7576/// Copies a function prototype without its body.77pub fn functionSignature(78    allocator: std.mem.Allocator,79    ast: *const std.zig.Ast,80    proto: std.zig.Ast.full.FnProto,81) ![]const u8 {82    const node = proto.ast.proto_node;83    const last = ast.lastToken(node);84    const has_semicolon = last + 1 < ast.tokens.len and85        ast.tokenTag(last + 1) == .semicolon;86    return try copyTrimmedSignature(87        allocator,88        ast.getNodeSource(node),89        has_semicolon,90    );91}9293/// Copies a value declaration or the header of a container declaration.94pub fn variableSignature(95    allocator: std.mem.Allocator,96    ast: *const std.zig.Ast,97    node: std.zig.Ast.Node.Index,98    container: bool,99) ![]const u8 {100    var raw = ast.getNodeSource(node);101    if (container) {102        const brace = std.mem.indexOfScalar(u8, raw, '{') orelse raw.len;103        raw = raw[0..brace];104        return try copyTrimmed(allocator, raw);105    }106    const last = ast.lastToken(node);107    const has_semicolon = last + 1 < ast.tokens.len and108        ast.tokenTag(last + 1) == .semicolon;109    return try copyTrimmedSignature(allocator, raw, has_semicolon);110}111112fn docstring(113    allocator: std.mem.Allocator,114    ast: *const std.zig.Ast,115    start: std.zig.Ast.TokenIndex,116    end: std.zig.Ast.TokenIndex,117    expected: std.zig.Token.Tag,118) !?[]const u8 {119    if (start == end) return null;120    var size: usize = end - start - 1;121    for (start..end) |raw_index| {122        const index: std.zig.Ast.TokenIndex = @intCast(raw_index);123        std.debug.assert(ast.tokenTag(index) == expected);124        size = try std.math.add(usize, size, docLine(ast.tokenSlice(index)).len);125    }126    const out = try allocator.alloc(u8, size);127    var offset: usize = 0;128    for (start..end, 0..) |raw_index, line_index| {129        const index: std.zig.Ast.TokenIndex = @intCast(raw_index);130        const line = docLine(ast.tokenSlice(index));131        if (line_index != 0) {132            out[offset] = '\n';133            offset += 1;134        }135        @memcpy(out[offset .. offset + line.len], line);136        offset += line.len;137    }138    std.debug.assert(offset == out.len);139    return out;140}141142fn docLine(raw: []const u8) []const u8 {143    std.debug.assert(raw.len >= 3);144    var line = raw[3..];145    if (std.mem.startsWith(u8, line, " ")) line = line[1..];146    return std.mem.trimEnd(u8, line, "\r");147}148149fn copyTrimmed(allocator: std.mem.Allocator, raw: []const u8) ![]const u8 {150    return try allocator.dupe(u8, std.mem.trim(u8, raw, " \t\r\n"));151}152153fn copyTrimmedSignature(154    allocator: std.mem.Allocator,155    raw: []const u8,156    semicolon: bool,157) ![]const u8 {158    const trimmed = std.mem.trim(u8, raw, " \t\r\n");159    const size = try std.math.add(usize, trimmed.len, @intFromBool(semicolon));160    const out = try allocator.alloc(u8, size);161    @memcpy(out[0..trimmed.len], trimmed);162    if (semicolon) out[trimmed.len] = ';';163    return out;164}165166test "ast nodes map to source lines" {167    const source: [:0]const u8 = "const alpha = 1;\n\nfn beta() void {}\n";168    var source_lines = try lines.SourceLines.init(std.testing.allocator, .{ .source = source });169    defer source_lines.deinit(std.testing.allocator);170    source_lines.fill();171    source_lines.activate();172    var ast = try std.zig.Ast.parse(std.testing.allocator, source, .{});173    defer ast.deinit(std.testing.allocator);174175    const root_decls = ast.rootDecls();176    try std.testing.expectEqual(@as(i64, 1), nodeLine(source_lines, &ast, root_decls[0]));177    try std.testing.expectEqual(@as(i64, 3), nodeLine(source_lines, &ast, root_decls[1]));178    try std.testing.expectEqual(@as(i64, 3), nodeEndLine(source_lines, &ast, root_decls[1]));179}180181test "ast documentation and signatures preserve source meaning" {182    const source: [:0]const u8 =183        \\//! Module summary.184        \\//!185        \\//! More detail.186        \\/// Builds a value.187        \\pub fn build(188        \\    input: u32,189        \\) u32 {190        \\    return input;191        \\}192        \\/// Stores state.193        \\pub const State = struct {194        \\    value: u32,195        \\};196        \\pub const default_state = State{ .value = 1 };197        \\/// Calls an external implementation.198        \\pub extern fn external() void;199        \\200    ;201    var ast = try std.zig.Ast.parse(std.testing.allocator, source, .{});202    defer ast.deinit(std.testing.allocator);203    try std.testing.expectEqual(@as(usize, 0), ast.errors.len);204    const module_doc = (try moduleDocstring(std.testing.allocator, &ast)).?;205    defer std.testing.allocator.free(module_doc);206    try std.testing.expectEqualStrings("Module summary.\n\nMore detail.", module_doc);207    const declarations = ast.rootDecls();208    var buffer: [1]std.zig.Ast.Node.Index = undefined;209    const proto = ast.fullFnProto(&buffer, declarations[0]).?;210    const function_doc = (try declarationDocstring(std.testing.allocator, &ast, declarations[0])).?;211    defer std.testing.allocator.free(function_doc);212    try std.testing.expectEqualStrings("Builds a value.", function_doc);213    const function_signature = try functionSignature(std.testing.allocator, &ast, proto);214    defer std.testing.allocator.free(function_signature);215    try std.testing.expectEqualStrings("pub fn build(\n    input: u32,\n) u32", function_signature);216    const container_signature = try variableSignature(std.testing.allocator, &ast, declarations[1], true);217    defer std.testing.allocator.free(container_signature);218    try std.testing.expectEqualStrings("pub const State = struct", container_signature);219    const value_signature = try variableSignature(std.testing.allocator, &ast, declarations[2], false);220    defer std.testing.allocator.free(value_signature);221    try std.testing.expectEqualStrings("pub const default_state = State{ .value = 1 };", value_signature);222    const external_proto = ast.fullFnProto(&buffer, declarations[3]).?;223    const external_signature = try functionSignature(std.testing.allocator, &ast, external_proto);224    defer std.testing.allocator.free(external_signature);225    try std.testing.expectEqualStrings("pub extern fn external() void;", external_signature);226227    const expected = [_][]const u8{228        "/// Builds a value.\npub fn build(\n    input: u32,\n) u32 {\n    return input;\n}",229        "/// Stores state.\npub const State = struct {\n    value: u32,\n};",230        "pub const default_state = State{ .value = 1 };",231        "/// Calls an external implementation.\npub extern fn external() void;",232    };233    for (declarations, expected) |declaration, exact| {234        const span = declarationSourceSpan(&ast, declaration);235        try std.testing.expectEqualStrings(236            exact,237            source[span.start_byte..span.end_byte],238        );239    }240}241242test "declaration spans preserve every public declaration form" {243    const source: [:0]const u8 =244        \\/// Stores one value.245        \\pub const Box = struct {246        \\    value: u8,247        \\    /// Reads the value.248        \\    pub fn read(self: Box) u8 {249        \\        return self.value;250        \\    }251        \\};252        \\/// Names the container.253        \\pub const Alias = Box;254        \\/// Builds a value.255        \\pub fn build() Box {256        \\    return .{ .value = 1 };257        \\}258        \\/// Calls an external implementation.259        \\pub extern fn external() void;260        \\261    ;262    var ast = try std.zig.Ast.parse(std.testing.allocator, source, .{});263    defer ast.deinit(std.testing.allocator);264    try std.testing.expectEqual(@as(usize, 0), ast.errors.len);265    const declarations = ast.rootDecls();266    const expected = [_][]const u8{267        "/// Stores one value.\npub const Box = struct {\n    value: u8,\n    /// Reads the value.\n    pub fn read(self: Box) u8 {\n        return self.value;\n    }\n};",268        "/// Names the container.\npub const Alias = Box;",269        "/// Builds a value.\npub fn build() Box {\n    return .{ .value = 1 };\n}",270        "/// Calls an external implementation.\npub extern fn external() void;",271    };272    for (declarations, expected) |declaration, exact| {273        try expectDeclarationBytes(&ast, declaration, exact);274    }275    var buffer: [2]std.zig.Ast.Node.Index = undefined;276    const variable = ast.fullVarDecl(declarations[0]).?;277    const initializer = variable.ast.init_node.unwrap().?;278    const container = ast.fullContainerDecl(&buffer, initializer).?;279    var method: ?std.zig.Ast.Node.Index = null;280    for (container.ast.members) |member| {281        var proto_buffer: [1]std.zig.Ast.Node.Index = undefined;282        if (ast.fullFnProto(&proto_buffer, member) != null) method = member;283    }284    try expectDeclarationBytes(285        &ast,286        method.?,287        "/// Reads the value.\n    pub fn read(self: Box) u8 {\n        return self.value;\n    }",288    );289}290291fn expectDeclarationBytes(292    ast: *const std.zig.Ast,293    declaration: std.zig.Ast.Node.Index,294    expected: []const u8,295) !void {296    const span = declarationSourceSpan(ast, declaration);297    try std.testing.expectEqualStrings(298        expected,299        ast.source[span.start_byte..span.end_byte],300    );301}