kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/docs/schema/schema.txt (about) 1 // Copyright 2014 The Kythe Authors. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 Kythe Schema Reference 16 ====================== 17 :Revision: 1.0 18 :toc2: 19 :toclevels: 3 20 :priority: 999 21 22 .This document is part of the Kythe test suite. 23 TIP: Successfully generating this document is part of the test suite for the 24 Kythe indexers. The assertions in the example code all verify and the 25 graphs provided are the graphs that are actually output. Feel free to add 26 examples from your own languages, but be sure to keep them up to date. 27 28 Kythe Namespace 29 --------------- 30 31 All fact names in this doc are implicitly prefixed by `/kythe`:: 32 e.g. `node/kind` is really `/kythe/node/kind` 33 34 All edge kinds in this doc are implicitly prefixed by `/kythe/edge`:: 35 e.g. `aliases` is really `/kythe/edge/aliases` 36 37 The verifier will automatically prepend the respective prefix 38 unless the fact name or edge kind starts with `/`. 39 40 41 VName conventions 42 ----------------- 43 44 By default, assume that the VNames of nodes should be chosen according to the 45 following rules (more details are given in the link:../kythe-storage.html#TermVName[storage model]): 46 47 * `language`: the source language. 48 * `corpus`: the node's containing corpus. 49 * `root`: a root path relative to the node's corpus. 50 * `path`: a path relative to the corpus *and* root of the node. 51 * `signature`: a unique string (per `corpus`, `root`, `path`, and `language`) 52 that should be consistently generated given the same input to the indexer, 53 but that does not necessarily need to be stable across different versions of 54 the input. 55 56 Additional rules govern the generation of VNames for certain kinds of nodes, 57 most notably <<file,files>>. These nodes are frequently used as points 58 for linking together the output of discrete indexer runs and may have greater 59 stability properties than may be derived using the preceding VName rules. 60 61 Absent additional rules, an indexer is permitted to encode the `signature` field 62 arbitrarily, as long as the chance of this encoding causing distinct field 63 values to become indistinguishable is vanishingly small. This is meant to permit 64 implementations to use one-way hash functions to crunch large `signature` values 65 down to manageable fingerprints. 66 67 Edge kinds 68 ---------- 69 .Reverse Edges 70 TIP: The Kythe API uses `%` to denote a reverse edge. 71 For example, if NodeA `defines/binding` NodeB, then NodeB 72 `%/kythe/edge/defines/binding` NodeA. Reverse edges are constructed 73 during post-processing, and should not be emitted by indexers. 74 75 [[aliases]] 76 aliases 77 ~~~~~~~ 78 79 Brief description:: 80 A *aliases* T if A may be used in place of T. 81 Commonly arises from:: 82 typedefs, imports 83 Points from:: 84 <<talias>> 85 Points toward:: 86 types 87 Ordinals are used:: 88 never 89 See also:: 90 <<aliasesroot, [aliases/root]>> 91 92 [kythe,C++,"Typedefs are aliases."] 93 -------------------------------------------------------------------------------- 94 //- @Counter defines/binding TAlias 95 //- TAlias aliases TInt 96 typedef int Counter; 97 -------------------------------------------------------------------------------- 98 99 [[aliasesroot]] 100 aliases/root 101 ~~~~~~~~~~~~ 102 103 Brief description:: 104 A *aliases/root* T if following all *aliases* edges from A may lead to T, 105 possibly with language-specific qualifiers applied. 106 Commonly arises from:: 107 typedefs 108 Points from:: 109 <<talias>> 110 Points toward:: 111 types 112 Ordinals are used:: 113 never 114 See also:: 115 <<aliasesroot, [aliases/root]>> 116 117 [kythe,C++,"Following aliases."] 118 -------------------------------------------------------------------------------- 119 //- @T defines/binding AliasT 120 //- AliasT aliases TInt 121 //- AliasT aliases/root TInt 122 using T = int; 123 //- AliasS aliases AliasT 124 //- AliasS aliases/root TInt 125 using S = T; 126 //- AliasU aliases AliasS 127 //- AliasU aliases/root TInt 128 using U = S; 129 -------------------------------------------------------------------------------- 130 131 [kythe,C++,"Following aliases and collecting qualifiers."] 132 -------------------------------------------------------------------------------- 133 //- @CInt defines/binding ConstIntAlias 134 //- ConstIntAlias aliases CInt 135 //- CInt.node/kind tapp 136 //- CInt param.0 Const 137 //- CInt param.1 TInt 138 using CInt = const int; 139 //- @T defines/binding AliasT 140 //- AliasT aliases TInt 141 //- AliasT aliases/root TInt 142 using T = int; 143 //- AliasS aliases ConstAliasT 144 //- ConstAliasT param.0 Const 145 //- ConstAliasT param.1 AliasT 146 //- AliasS aliases/root CInt 147 using S = const T; 148 //- AliasU aliases AliasS 149 //- AliasU aliases/root CInt 150 using U = S; 151 -------------------------------------------------------------------------------- 152 153 [[annotatedby]] 154 annotatedby 155 ~~~~~~~~~~~ 156 157 Brief description:: 158 A *annotatedby* B if A provides metadata for B. 159 Points from:: 160 semantic nodes 161 Points toward:: 162 semantic nodes 163 Ordinals are used:: 164 never 165 166 [kythe,Java,"Classes can be annotated."] 167 -------------------------------------------------------------------------------- 168 //- @Deprecated ref Deprecated 169 //- @E defines/binding Class 170 //- Class annotatedby Deprecated 171 @Deprecated public class E {} 172 -------------------------------------------------------------------------------- 173 174 [[bounded]] 175 bounded/upper or bounded/lower 176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 177 178 Brief description:: 179 <<tvar>> A is *bounded/upper* by B when A is constrained to be a 180 subtype of B. <<tvar>> A is *bounded/lower* by B when A is 181 constrained to be a supertype of B. 182 See also:: 183 <<tvar>> 184 Commonly arises from:: 185 Type parameters 186 Notes:: 187 * Kythe leaves the interpretation of unbounded <<tvar>> nodes to 188 each language. For example, an <<tvar>> with no *bounded* edges 189 in Java may be assigned any subtype of Object, but no primitive type. 190 * It is possible for an <<tvar>> to have multiple bounds. For 191 example, this occurs in Java when a type parameter must implement several 192 interfaces. In cases where the order of the bounds matters (e.g., in Java, 193 where the order affects type erasure), the bound edge kind may be qualified 194 by an ordinal, so that A is *bounded/upper.N* by B if B is the Nth upper 195 bound of A. Code interpreting *bounded* edges should be able to handle both 196 ordered and unordered edges. 197 198 [kythe,Java,"Generic type parameters can be bound."] 199 -------------------------------------------------------------------------------- 200 package pkg; 201 import java.util.Optional; 202 public class E { 203 //- @"Optional<?>" ref OptionalWild 204 //- OptionalWild.node/kind tapp 205 //- OptionalWild param.0 OptionalClass 206 //- OptionalWild param.1 Wildcard0 207 //- Wildcard0.node/kind tvar 208 //- !{ Wildcard0 bounded/upper Anything0 209 //- Wildcard0 bounded/lower Anything1 } 210 private static void wildcard(Optional<?> o) {} 211 212 //- @"Optional<? extends String>" ref OptionalWildString 213 //- OptionalWildString.node/kind tapp 214 //- OptionalWildString param.0 OptionalClass 215 //- OptionalWildString param.1 Wildcard1 216 //- Wildcard1.node/kind tvar 217 //- Wildcard1 bounded/upper Str 218 //- @String ref Str 219 //- !{ Wildcard1 bounded/lower Anything2 } 220 private static void wildcardBound(Optional<? extends String> o) {} 221 222 //- @"Optional<? super String>" ref OptionalWildSuperString 223 //- OptionalWildSuperString.node/kind tapp 224 //- OptionalWildSuperString param.0 OptionalClass 225 //- OptionalWildSuperString param.1 WildcardSuper1 226 //- WildcardSuper1.node/kind tvar 227 //- WildcardSuper1 bounded/lower Str 228 //- !{ WildcardSuper1 bounded/upper Anything1 } 229 //- @String ref Str 230 private static void wildcardSuperBound(Optional<? super String> o) {} 231 232 //- @objAndOneIFaceBound defines/binding OIFunc 233 //- @S1 defines/binding S1Var 234 //- @List ref List 235 //- S1Var bounded/upper.0 Obj 236 //- S1Var bounded/upper.1 List 237 public <S1 extends Object & java.util.List> void objAndOneIFaceBound() {} 238 239 } 240 -------------------------------------------------------------------------------- 241 242 // TODO(salguarnieri) Add in Objective-C example once this feature is added to 243 // the Objective-C indexer. 244 245 [[childof]] 246 childof 247 ~~~~~~~ 248 249 Brief description:: 250 A *childof* B if A is contained in or dominated by B. 251 Commonly arises from:: 252 <<anchor>>s, block syntax, membership 253 Points from:: 254 any 255 Points toward:: 256 semantic nodes 257 Ordinals are used:: 258 never 259 Notes:: 260 <<anchor>>s should not be `childof` the <<file>> in which they reside. As an 261 optimization due to the overwhelming number of such edges, the parentage 262 relationship between these nodes is determined by the shared `corpus`, 263 `path`, and `root` VName fields. 264 265 [kythe,C++,"Enumerators are children of enumerations."] 266 -------------------------------------------------------------------------------- 267 //- @Enum defines/binding Enumeration 268 enum class Enum { 269 //- @Etor defines/binding Enumerator 270 Etor 271 }; 272 //- Enumerator childof Enumeration 273 -------------------------------------------------------------------------------- 274 275 [[childofcontext]] 276 childof/context 277 ~~~~~~~~~~~~~~~ 278 279 Brief description:: 280 A *childof/context* T if anchor A is associated with some instantiation T. 281 Commonly arises from:: 282 template instantiations 283 Points from:: 284 <<anchor>>s 285 Points toward:: 286 semantic nodes 287 Ordinals are used:: 288 never 289 290 [kythe,C++,"Template instantiations create new anchor contexts."] 291 -------------------------------------------------------------------------------- 292 //- @C defines/binding CTemplate 293 //- CTemplateBody childof CTemplate 294 template <typename T> struct C { 295 //- @x=AnchorX defines/binding XBinding 296 //- @x=AnchorCX defines/binding CXBinding 297 int x; 298 }; 299 //- @C defines/binding CInst 300 //- AnchorCX childof/context CInst 301 //- !{ AnchorX childof/context CInst } 302 template struct C<int>; 303 -------------------------------------------------------------------------------- 304 305 [[completedby]] 306 completedby 307 ~~~~~~~~~~~ 308 309 Brief description:: 310 Declaration A *completedby* definition B if B fully specifies A. 311 There may exist other definitions that may also fully specify A. 312 Commonly arises from:: 313 definitions of forward declarations 314 Points from:: 315 semantic nodes with `complete` facts set to `incomplete` or `complete` 316 Points toward:: 317 semantic nodes with `complete` facts set to `complete` 318 See also:: 319 <<record>>, <<sum>> 320 321 [kythe,C++,"Declarations are completed by definitions."] 322 -------------------------------------------------------------------------------- 323 #include "test.h" 324 //- Decl1 completedby Defn 325 //- Decl2 completedby Defn 326 //- @C defines/binding Defn 327 class C { }; 328 329 #example test.h 330 //- @C defines/binding Decl1 331 class C; 332 //- @C defines/binding Decl2 333 class C; 334 -------------------------------------------------------------------------------- 335 336 [[defines]] 337 defines 338 ~~~~~~~ 339 340 Brief description:: 341 A *defines* B if A generates the semantic object B. 342 Commonly arises from:: 343 definitions and declarations 344 Points from:: 345 anchors 346 Points toward:: 347 semantic nodes 348 Ordinals are used:: 349 never 350 See also:: 351 <<definesbinding,[defines/binding]>> 352 Notes:: 353 It is valid for multiple anchors to define the same semantic object. These 354 anchors may even overlap. 355 356 357 [kythe,Java,"Class definitions span their entire body."] 358 -------------------------------------------------------------------------------- 359 //- ClassEDef defines ClassE 360 //- ClassEDef.node/kind anchor 361 //- ClassEDef.loc/start @^public 362 //- ClassEDef.loc/end @$+3"}" 363 public class E { 364 // class contents here... 365 } 366 -------------------------------------------------------------------------------- 367 368 [kythe,Java,"Method definitions span their entire body."] 369 -------------------------------------------------------------------------------- 370 public class E { 371 //- MethodDef defines Method 372 //- MethodDef.node/kind anchor 373 //- MethodDef.loc/start @^public 374 //- MethodDef.loc/end @$+3"}" 375 public int methodName(int param) { 376 return 42; 377 } 378 } 379 -------------------------------------------------------------------------------- 380 381 [[definesbinding]] 382 defines/binding 383 ~~~~~~~~~~~~~~~ 384 385 Brief description:: 386 A *defines/binding* B when A covers an identifier bound to B when that binding is established. 387 Commonly arises from:: 388 definitions 389 Points from:: 390 anchors 391 Points toward:: 392 semantic nodes 393 Ordinals are used:: 394 never 395 See also:: 396 <<defines>> 397 Notes:: 398 Source anchors are not necessarily identifiers. For example, the $$C++$$ 399 indexer will start a *defines/binding* edge from an anchor spanning 400 the text `operator()`. 401 402 [kythe,Java,"Class names bind their definitions."] 403 -------------------------------------------------------------------------------- 404 //- @E defines/binding ClassE 405 public class E {} 406 -------------------------------------------------------------------------------- 407 408 [kythe,Java,"Method names bind their definitions."] 409 -------------------------------------------------------------------------------- 410 public class E { 411 //- @main defines/binding MethodMain 412 public static void main(String[] args) {} 413 } 414 -------------------------------------------------------------------------------- 415 416 [kythe,C++,"Variable definitions define bindings for variables."] 417 -------------------------------------------------------------------------------- 418 //- @x defines/binding VariableX 419 int x; 420 -------------------------------------------------------------------------------- 421 422 [[definesimplicit]] 423 defines/implicit 424 ~~~~~~~~~~~~~~~~ 425 426 Brief description:: 427 A *defines/implicit* B if A semantically defines an entity B, but that 428 definition is not explicitly related to the decorated text. 429 Commonly arises from:: 430 filename-based packages, C++ special member functions 431 Points from:: 432 anchors 433 Points toward:: 434 semantic nodes 435 See also:: 436 <<package>> 437 Notes:: 438 The most common situations in which this edge should be used are in languages 439 for which modules don't have an explicit syntactic marker, deriving the module 440 name from the file or directory path and C++'s compiler-defined special member 441 functions. 442 443 [kythe,C++,"Implicit destructor definition."] 444 -------------------------------------------------------------------------------- 445 ///- @X defines/implicit XDtor 446 ///- XDtor.subkind destructor 447 class X {}; 448 -------------------------------------------------------------------------------- 449 450 [kythe,clike,"Implicit module definition."] 451 -------------------------------------------------------------------------------- 452 ///- Mod=vname(_, _, _, _, _).node/kind package 453 ///- ModAnchor.node/kind anchor 454 ///- ModAnchor./kythe/loc/start 0 455 ///- ModAnchor./kythe/loc/end 0 456 ///- ModAnchor defines/implicit Mod 457 -------------------------------------------------------------------------------- 458 459 [[denotes]] 460 denotes 461 ~~~~~~~ 462 463 Brief description:: 464 A *denotes* B if A is a concrete representation of B, an abstract 465 representation that may not be written down. 466 Commonly arises from:: 467 library support code (flags, database wrappers, etc) 468 Points from:: 469 semantic nodes with a definition 470 Points toward:: 471 semantic nodes 472 Ordinals are used:: 473 never 474 See also:: 475 <<completedby>>, <<generates>> 476 Notes:: 477 In contrast to *generates*, where it is expected that both source 478 and target nodes have definition locations, only the source of a 479 *denotes* edge must have a definition location. The source (or 480 concrete representation) is used as the canonical definition of the 481 target (or abstract representation). 482 483 If the source of a *denotes* edge participates in a completion 484 relationship, that source should have completion type `definition`. 485 It is not necessary for the target to also participate in a 486 completion relationship or to have a completion fact set. 487 488 It is not necessary for the source and target to share the same 489 node kind. 490 491 [[depends]] 492 depends 493 ~~~~~~~ 494 495 Brief description:: 496 A *depends* B if processing of A depends on the existence or presence of B. For example, if a 497 process depends a set of files and/or processes. Another example, a file depends upon a process 498 which outputs said file. 499 Commonly arises from:: 500 build dependencies 501 Points from:: 502 <<process>>, <<file>> 503 Points toward:: 504 <<process>>, <<file>> 505 Ordinals are used:: 506 never 507 508 [[documents]] 509 documents 510 ~~~~~~~~~ 511 512 Brief description:: 513 A *documents* B if A describes (in possibly marked up natural language) the 514 semantic object B. 515 Commonly arises from:: 516 documentation comments 517 Points from:: 518 anchors and <<doc>>s 519 Points toward:: 520 semantic nodes 521 Ordinals are used:: 522 never 523 Notes:: 524 Kythe does not specify a particular flavor of markup. Documentation comment 525 anchors include all of the characters of the comment, including (e.g.) the 526 $$///$$s. It is up to the language indexer to determine which comments to 527 treat as documentation comments. 528 See also:: 529 <<doc,refdoc,ref/doc>> 530 531 In the $$C++$$ example below, there are really two documentation blocks: the 532 first comes from merging together the verification annotations; the second is 533 the Doxygen-style $$///$$ line. The Doxygen line is not merged with the verifier 534 lines owing to heuristics in Clang's comment parser. 535 536 [kythe,C++,"Comments document objects."] 537 -------------------------------------------------------------------------------- 538 int v; //- @"/// An empty class." documents ClassC 539 //- ClassC.node/kind record 540 /// An empty class. 541 class C { }; 542 -------------------------------------------------------------------------------- 543 544 [[exports]] 545 exports 546 ~~~~~~~~ 547 548 Brief description:: 549 A *exports* B if process node A exports process node B. 550 Commonly arises from:: 551 build rules 552 Points from:: 553 process nodes 554 Points toward:: 555 process nodes 556 Orginals are used:: 557 never 558 See also:: 559 <<process>> 560 Notes:: 561 Tools like bazel have cases where build rules export other build rules, wherein the closure of all 562 rules reached via exports attributes are considered direct dependencies of any rule that directly 563 depends on the target with exports. The exports are not direct dependencies of the rule they belong 564 to. 565 566 [kythe,clike,"Process node exports other process node."] 567 -------------------------------------------------------------------------------- 568 //- ProcessNodeA.node/kind process 569 //- ProcessNodeB.node/kind process 570 //- ProcessNodeA exports ProcessNodeB 571 java_library( 572 name = "A", 573 exports = [ 574 ":B", 575 ], 576 ) 577 578 java_library( 579 name = "B", 580 ) 581 -------------------------------------------------------------------------------- 582 583 [[extends]] 584 extends 585 ~~~~~~~ 586 587 Brief description:: 588 A *extends* B if A explicitly derives from B. It neither implies nor excludes 589 any type relationship between A and B. 590 Commonly arises from:: 591 inheritance 592 Points from:: 593 semantic nodes 594 Points toward:: 595 type/semantic nodes 596 Ordinals are used:: 597 never 598 Notes:: 599 An indexer may emit more descriptive edges with the *extends* prefix. 600 For example, $$C++$$ will emit *extends/public*, *extends/public/virtual*, 601 *extends/protected*, *extends/protected/virtual*, *extends/private*, 602 *extends/private/virtual*, and *extends/virtual*. 603 604 [kythe,Java,"Classes extend classes."] 605 -------------------------------------------------------------------------------- 606 package pkg; 607 public class E { 608 //- @A defines/binding ClassA 609 static class A { } 610 //- @B defines/binding ClassB 611 //- ClassB extends ClassA 612 static class B extends A { } 613 } 614 -------------------------------------------------------------------------------- 615 616 [kythe,Java,"Classes and interfaces extend interfaces."] 617 -------------------------------------------------------------------------------- 618 package pkg; 619 //- @I defines/binding IntfI 620 interface I { } 621 622 //- @J defines/binding IntfJ 623 //- IntfJ extends IntfI 624 interface J extends I { } 625 626 //- @C defines/binding ClassC 627 //- ClassC extends IntfJ 628 //- !{ClassC extends IntfI} 629 class C implements J { } 630 -------------------------------------------------------------------------------- 631 632 [kythe,C++,"Classes extend classes."] 633 -------------------------------------------------------------------------------- 634 //- @A defines/binding ClassA 635 class A { }; 636 637 //- @B defines/binding ClassB 638 //- ClassB extends/public ClassA 639 class B : public A { }; 640 641 //- @C defines/binding ClassC 642 //- ClassC extends/private ClassA 643 class C : private A { }; 644 -------------------------------------------------------------------------------- 645 646 [[generates]] 647 generates 648 ~~~~~~~~~ 649 650 Brief description:: 651 A *generates* B if A is related to B through some extralingual process. 652 Commonly arises from:: 653 code generation 654 Points from:: 655 semantic nodes, files 656 Points toward:: 657 semantic nodes, files 658 Ordinals are used:: 659 never 660 See also:: 661 <<denotes>>, <<imputes>>, <<semanticgenerated>> 662 663 Tools like RPC interface generators read specification languages and emit 664 code in one or more target languages. Although the specification language 665 and target languages do not share Kythe indexers, it is still semantically 666 useful to connect the nodes they emit. For example, one might want to list 667 all the $$C++$$ and Java uses of a particular service call, starting at the 668 specification of that service. The specification and its generated artifacts 669 may be joined by the *generates* edge. Either both the specification and its 670 generated artifact are file nodes or both are semantic nodes. 671 672 [[influences]] 673 influences 674 ~~~~~~~~~~ 675 676 Brief description:: 677 A *influences* B if A directly affects B during the evaluation of a program. 678 Commonly arises from:: 679 assignment 680 Points from:: 681 semantic nodes 682 Points toward:: 683 semantic nodes 684 Ordinals are used:: 685 never 686 Notes:: 687 This is an experimental definition and is expected to undergo refinement. 688 689 [kythe,C++,"Assignment causes influence"] 690 -------------------------------------------------------------------------------- 691 void f() { 692 //- @x defines/binding VarX 693 //- @y defines/binding VarY 694 //- @z defines/binding VarZ 695 int x = 0, y = 1, z = 2; 696 //- VarZ influences VarY 697 //- VarY influences VarX 698 //- !{VarZ influences VarX} 699 //- !{VarY influences VarZ} 700 x = y = z; 701 } 702 -------------------------------------------------------------------------------- 703 704 [[instantiates]] 705 instantiates 706 ~~~~~~~~~~~~ 707 708 Brief description:: 709 A *instantiates* B if A is the result of monomorphizing B. 710 Commonly arises from:: 711 implicit template application 712 Points from:: 713 semantic nodes 714 Points toward:: 715 semantic nodes (<<tapp>>) 716 Ordinals are used:: 717 never 718 See also:: 719 <<instantiatesspeculative,[instantiates/speculative]>>, <<specializes>> 720 721 In $$C++$$, *specialization* and *instantiation* capture distinct relationships. 722 Every template `T` has a primary template, which defines the number and kind 723 of template parameters that are written down whenever `T` is (normally) 724 expressed. Other templates *specialize* `T` by specifying alternate bodies 725 for the template depending on the values bound to the template parameters. 726 This *specializes* relationship is always between a more-specific (or implicit) 727 template and its primary template (applied to one or more arguments). We do not 728 attempt to model a subtyping relationship between template specializations. 729 730 When `T<...>` is written down, an element from the set of *T* and its 731 specializations must be chosen for manifestation. This element may have free 732 type parameters. These are deduced during the process of *instantiating* the 733 chosen specialization of *T*. Some $$C++$$ _total specializations_ do not bind 734 any template parameters. Other $$C++$$ _partial specializations_ do, and may 735 bind different numbers of type parameters than the primary template. The 736 *instantiates* relationship records which total or partial specialization was 737 chosen (or if the primary template was chosen), and the template arguments that 738 were matched to that specialization's parameters. In contrast, the *specializes* 739 relationship for `T<...>` records the primary template for T, as well as which 740 template arguments were substituted for the primary template's parameters. 741 742 When the primary template is chosen for the *instantiates* relationship, the 743 *specializes* edge points to the same node: 744 745 [kythe,C++,"Instantiating the primary template"] 746 -------------------------------------------------------------------------------- 747 //- @t_equals_float defines/binding PrimaryTemplate 748 template<typename T, typename S> bool t_equals_float = false; 749 750 //- @t_equals_float ref TEqualsFloatForLongLong 751 //- TEqualsFloatForLongLong instantiates TAppLongLong 752 //- TEqualsFloatForLongLong specializes TAppLongLong 753 //- TAppLongLong param.0 PrimaryTemplate 754 bool is_false = t_equals_float<long, long>; 755 -------------------------------------------------------------------------------- 756 757 When a specialization of a template is chosen for *instantiates*, the 758 *specializes* edge still points to the primary template applied to the correct 759 number of arguments. The *instantiates* edge points to the specialization that 760 was used. It is applied to the template arguments appropriate for that 761 specialization. Note in the below example how we *specialize* 762 `PrimaryTemplate<float, long>` but *instantiate* `SpecificTemplate<long>`: 763 764 [kythe,C++,"Instantiating a partial specialization"] 765 -------------------------------------------------------------------------------- 766 //- @t_equals_float defines/binding PrimaryTemplate 767 template<typename T, typename S> bool t_equals_float = false; 768 //- @int ref IntType @long ref LongType 769 int i; long l; 770 771 //- @t_equals_float defines/binding SpecificTemplate 772 template <typename S> bool t_equals_float<float, S> = true; 773 //- @t_equals_float ref TEqualsFloatForFloatLong 774 //- TEqualsFloatForFloatLong instantiates TAppSpecificFloatLong 775 //- TAppSpecificFloatLong param.0 SpecificTemplate 776 //- TAppSpecificFloatLong param.1 LongType 777 //- TEqualsFloatForLongLong specializes TAppPrimaryFloatLong 778 //- TAppPrimaryFloatLong param.0 PrimaryTemplate 779 //- TAppPrimaryFloatLong param.1 FloatType 780 //- TAppPrimaryFloatLong param.2 LongType 781 bool is_true = t_equals_float<float, long>; 782 -------------------------------------------------------------------------------- 783 784 Here is another similar example: 785 786 [kythe,C++,"Instantiation versus specialization."] 787 -------------------------------------------------------------------------------- 788 //- @v defines/binding PrimaryTemplate 789 template <typename T, typename S, typename V> T v; 790 template <typename U> 791 //- @v defines/binding PartialSpecialization 792 U v<int, U, long>; 793 //- @v ref ImplicitSpecialization 794 float w = v<int, float, long>; 795 //- ImplicitSpecialization specializes TAppPrimaryTemplate 796 //- ImplicitSpecialization instantiates TAppPartialSpecialization 797 //- TAppPrimaryTemplate param.0 PrimaryTemplate 798 //- TAppPrimaryTemplate param.1 vname("int#builtin",_,_,_,_) 799 //- TAppPrimaryTemplate param.2 vname("float#builtin",_,_,_,_) 800 //- TAppPrimaryTemplate param.3 vname("long#builtin",_,_,_,_) 801 //- TAppPartialSpecialization param.0 PartialSpecialization 802 //- TAppPartialSpecialization param.1 vname("float#builtin",_,_,_,_) 803 -------------------------------------------------------------------------------- 804 805 [[instantiatesspeculative]] 806 instantiates/speculative 807 ~~~~~~~~~~~~~~~~~~~~~~~~ 808 809 Brief description:: 810 A *instantiates/speculative* B if A could be the result of monomorphizing B. 811 Commonly arises from:: 812 implicit template application 813 Points from:: 814 semantic nodes 815 Points toward:: 816 semantic nodes (<<tapp>>) 817 Ordinals are used:: 818 never 819 See also:: 820 <<instantiates>>, <<specializes>> 821 822 It may not be possible to decide whether a type instantiation actually occurs, 823 especially when dependent types are involved. The *instantiates/speculative* 824 and *specializes/speculative* edges are like the *instantiates* and 825 *specializes* edges, but they also record the fact that the instantiation 826 (specialization) did not occur when the code was indexed. 827 828 [kythe,C++,"Speculative instantiation and specialization."] 829 -------------------------------------------------------------------------------- 830 // Checks indexing refs and defs of dependent function specializations. 831 //- @f defines/binding AbsF1 832 template <typename S> long f(S s) { return 0; } 833 //- @f defines/binding AbsF2 834 template <typename S> int f(S s) { return 0; } 835 template <typename T> struct S { 836 // Note that C++ doesn't even check the kindedness of these type applications. 837 friend 838 //- @f defines/binding DepSpecFT 839 //- DepSpecFT instantiates/speculative TAppAbsF1T 840 //- DepSpecFT specializes/speculative TAppAbsF1T 841 //- TAppAbsF1T param.0 AbsF1 842 //- DepSpecFT instantiates/speculative TAppAbsF2T 843 //- DepSpecFT specializes/speculative TAppAbsF2T 844 //- TAppAbsF2T param.0 AbsF2 845 long f<int, short>(T t); 846 }; 847 -------------------------------------------------------------------------------- 848 849 [[imputes]] 850 imputes 851 ~~~~~~~ 852 853 Brief description:: 854 A *imputes* B if the syntactic span at A is related to the semantic node B 855 through some extralingual process. 856 Commonly arises from:: 857 code generation 858 Points from:: 859 anchors 860 Points toward:: 861 semantic nodes 862 Ordinals are used:: 863 never 864 See also:: 865 <<denotes>>, <<generates>> 866 867 Mechanically, if A *defines/binding* A' and A *imputes* B, where A is an anchor 868 and both A' and B are semantic nodes, the *imputes* edge has the same effect as 869 though the edge A' *generates* B were produced. This edge is useful in cases 870 where it isn't otherwise possible to produce the VName for A' and where the 871 span A in source text can uniquely identify A' by the *defines/binding* edge. 872 873 [[narrows]] 874 narrows 875 ~~~~~~~ 876 877 Brief description:: 878 A *narrows* B if A identifies the same target language object as B but is 879 subject to additional constraints. 880 Commonly arises from:: 881 type refinement 882 Points from:: 883 variables 884 Points toward:: 885 variables 886 Ordinals are used:: 887 never 888 See also:: 889 <<generates>>, <<typed>> 890 891 Some languages allow the types of variables to change over the course of a 892 program. For example, a type test can be used to narrow the type of a variable: 893 894 [source,java] 895 ---- 896 Object x; // x : Object 897 if (x instanceof String) { 898 x; // x : String 899 } 900 ---- 901 902 In this example, every `x` refers to the same variable `x`, but the `x` in 903 the body of the conditional has a different static type than both the `x` 904 in the conditional expression and the `x` declared at the top. This program 905 is represented in the following way: 906 907 [source,java] 908 ---- 909 //- @x defines/binding XObject 910 //- XObject typed Object 911 Object x; 912 //- @x ref XObject 913 if (x instanceof String) { 914 //- @x ref XString 915 //- XString narrows XObject 916 //- XString typed String 917 x; 918 } 919 ---- 920 921 The `x` with type `String` has no `defines/binding` edge, but is associated 922 with the `x` with type `Object` with the `narrows` edge. Clients should 923 interpret these variables as the same (in the way that nodes associated with 924 the `generates` edge are the same), but should prefer facts and edges from the 925 particular `x` being identified. In particular, `documents` edges and `code` 926 facts should be chosen from the particular node that is the target of a `ref` 927 when that node is in a `narrows` relationship. 928 929 [[named]] 930 named 931 ~~~~~ 932 933 Brief description:: 934 A *named* B if B is an external identifier for A. 935 Commonly arises from:: 936 definitions and declarations 937 Points from:: 938 semantic nodes 939 Points toward:: 940 name/linkage nodes 941 Ordinals are used:: 942 never 943 See also:: 944 <<name>> 945 946 [kythe,Java,"Classes have JVM binary names."] 947 -------------------------------------------------------------------------------- 948 package pkg; 949 //- @E defines/binding EClass 950 //- EClass named EClassName = vname("pkg.E", "kythe", "", "", "jvm") 951 //- EClassName.node/kind record 952 public class E {} 953 -------------------------------------------------------------------------------- 954 955 [[overrides]] 956 overrides 957 ~~~~~~~~~ 958 959 Brief description:: 960 A *overrides* B if A directly overrides B in an inheritance-based relationship. 961 Points from:: 962 semantic nodes 963 Points toward:: 964 semantic nodes 965 Ordinals are used:: 966 never 967 See also:: 968 <<overridestransitive,[overrides/transitive]>>, <<overridesroot,[overrides/root]>> 969 970 [kythe,Java,"Methods have overrides edges."] 971 -------------------------------------------------------------------------------- 972 package pkg; 973 public class E { 974 static class A implements I { 975 //- @method defines/binding AMethod 976 //- AMethod overrides IMethod 977 public void method() {} 978 } 979 static class B extends A implements I { 980 //- @method defines/binding BMethod 981 //- BMethod overrides AMethod 982 //- BMethod overrides IMethod 983 public void method() {} 984 } 985 static interface I { 986 //- @method defines/binding IMethod 987 public void method(); 988 } 989 } 990 -------------------------------------------------------------------------------- 991 992 [[overridesroot]] 993 overrides/root 994 ~~~~~~~~~~~~~~ 995 996 Brief description:: 997 A *overrides/root* B if following all *overrides* edges from A would lead to 998 B. 999 Points from:: 1000 semantic nodes 1001 Points toward:: 1002 semantic nodes 1003 Ordinals are used:: 1004 never 1005 See also:: 1006 <<overrides>> 1007 1008 [kythe,C++,"Override roots"] 1009 -------------------------------------------------------------------------------- 1010 //- @f defines/binding CF 1011 class C { virtual void f() { } }; 1012 //- @f defines/binding DF 1013 class D : C { void f() override { } }; 1014 //- @f defines/binding EF 1015 class E : D { void f() override { } }; 1016 1017 //- !{CF overrides _} 1018 //- !{CF overrides/root _} 1019 //- DF overrides CF 1020 //- DF overrides/root CF 1021 //- EF overrides DF 1022 //- EF overrides/root CF 1023 -------------------------------------------------------------------------------- 1024 1025 [[overridestransitive]] 1026 overrides/transitive 1027 ~~~~~~~~~~~~~~~~~~~~ 1028 1029 Brief description:: 1030 A *overrides/transitive* B if A transitively overrides B, but the relationship 1031 A <<overrides>> B doesn't exist. 1032 Points from:: 1033 semantic nodes 1034 Points toward:: 1035 semantic nodes 1036 Ordinals are used:: 1037 never 1038 See also:: 1039 <<overrides>> 1040 1041 [kythe,Java,"Methods have overrides/transitive edges."] 1042 -------------------------------------------------------------------------------- 1043 package pkg; 1044 public class E { 1045 static class A { 1046 //- @method defines/binding AMethod 1047 public void method() {} 1048 } 1049 static class B extends A { 1050 //- @method defines/binding BMethod 1051 //- !{ BMethod overrides/transitive AMethod } 1052 public void method() {} 1053 } 1054 static class C extends B { 1055 //- @method defines/binding CMethod 1056 //- !{ CMethod overrides/transitive BMethod } 1057 //- CMethod overrides/transitive AMethod 1058 public void method() {} 1059 } 1060 } 1061 -------------------------------------------------------------------------------- 1062 1063 [[param]] 1064 param 1065 ~~~~~ 1066 1067 Brief description:: 1068 A *param.N* B if B is the Nth parameter of A. 1069 Commonly arises from:: 1070 ordered lists 1071 Points from:: 1072 semantic nodes 1073 Points toward:: 1074 semantic nodes 1075 Ordinals are used:: 1076 always 1077 1078 [kythe,C++,"Type applications have parameters."] 1079 -------------------------------------------------------------------------------- 1080 //- @T defines/binding AliasT 1081 //- AliasT aliases PtrInt 1082 //- PtrInt param.0 PointerConstructor 1083 //- PtrInt param.1 IntType 1084 using T = int*; 1085 -------------------------------------------------------------------------------- 1086 1087 [[propertyreads]] 1088 property/reads 1089 ~~~~~~~~~~~~~~ 1090 1091 Brief description:: 1092 A *property/reads* B if A is a reader of the property B 1093 Points from:: 1094 function nodes 1095 Points toward:: 1096 variable or property nodes 1097 Ordinals are used:: 1098 never 1099 See also:: 1100 <<propertywrites,[property/writes]>> 1101 1102 // TODO(schroederc): add support for AutoValue in schema examples 1103 1104 [[propertywrites]] 1105 property/writes 1106 ~~~~~~~~~~~~~~~ 1107 1108 Brief description:: 1109 A *property/writes* B if A is a writer of the property B 1110 Points from:: 1111 function nodes 1112 Points toward:: 1113 variable or property nodes 1114 Ordinals are used:: 1115 never 1116 See also:: 1117 <<propertyreads,[property/reads]>> 1118 1119 [[ref]] 1120 ref 1121 ~~~ 1122 1123 Brief description:: 1124 A *ref* B if A refers to some previously-defined B. 1125 Commonly arises from:: 1126 expressions, spelled-out types 1127 Points from:: 1128 anchors 1129 Points toward:: 1130 semantic nodes 1131 1132 [kythe,C++,"Mentions of variables are refs."] 1133 -------------------------------------------------------------------------------- 1134 //- @x defines/binding VariableX 1135 int x; 1136 //- @y defines/binding VariableY 1137 //- @x ref VariableX 1138 int y = x; 1139 -------------------------------------------------------------------------------- 1140 1141 [kythe,Go,"Mentions of variables are refs."] 1142 -------------------------------------------------------------------------------- 1143 package p 1144 1145 //- @x defines/binding VarX = vname(_,"kythe",_,"schema","go") 1146 //- VarX.node/kind variable 1147 var x int 1148 1149 //- @x ref VarX 1150 var y = x 1151 -------------------------------------------------------------------------------- 1152 1153 [[refimplicit]] 1154 ref/implicit 1155 ~~~~~~~~~~~~ 1156 1157 Brief description:: 1158 A *ref/implicit* B if A refers to some previously-defined B, and the 1159 expression spanned by A is implicit (e.g., the result of a template 1160 instantiation). 1161 Commonly arises from:: 1162 expressions, spelled-out types 1163 Points from:: 1164 anchors 1165 Points toward:: 1166 semantic nodes 1167 1168 [kythe,C++,"References inside template instantiations are implicit."] 1169 -------------------------------------------------------------------------------- 1170 template <typename T> class C { 1171 //- @foo ref/implicit SFoo 1172 int x = T::foo; 1173 }; 1174 //- @foo defines/binding SFoo 1175 struct S { static constexpr int foo = 1; }; 1176 C<S> cs; 1177 -------------------------------------------------------------------------------- 1178 1179 [[refcall]] 1180 ref/call 1181 ~~~~~~~~ 1182 1183 Brief description:: 1184 A *ref/call* F if A is an anchor that calls F. 1185 Points from:: 1186 anchors 1187 Points toward:: 1188 <<function,functions>> 1189 Ordinals are used:: 1190 never 1191 1192 [kythe,C++,"Anchors inside functions call functions."] 1193 -------------------------------------------------------------------------------- 1194 //- @A defines/binding FnA 1195 void A() { } 1196 //- @B defines/binding FnB 1197 //- ACall childof FnB 1198 //- ACall.node/kind anchor 1199 //- ACall ref/call FnA 1200 void B() { A(); } 1201 -------------------------------------------------------------------------------- 1202 1203 [[refcalldirect]] 1204 ref/call/direct 1205 ~~~~~~~~~~~~~~~ 1206 1207 Brief description:: 1208 A *ref/call/direct* F if A is an anchor that calls F and ignores indirect 1209 dispatch. 1210 Points from:: 1211 anchors 1212 Points toward:: 1213 <<function,functions>> 1214 Ordinals are used:: 1215 never 1216 1217 [kythe,C++,"A direct call to a base struct's function."] 1218 -------------------------------------------------------------------------------- 1219 //- @f defines/binding FnF 1220 struct A { virtual void f() {} }; 1221 //- @"A::f()" ref/call/direct FnF 1222 struct B : public A { void f() override { A::f(); }}; 1223 -------------------------------------------------------------------------------- 1224 1225 [[refcallimplicit]] 1226 ref/call/implicit 1227 ~~~~~~~~~~~~~~~~~ 1228 1229 Brief description:: 1230 A *ref/call/implicit* F if A is an anchor that calls F, and the calling 1231 expression spanned by A is implicit (e.g., the result of a template 1232 instantiation). 1233 Points from:: 1234 anchors 1235 Points toward:: 1236 <<function,functions>> 1237 Ordinals are used:: 1238 never 1239 1240 [kythe,C++,"Calls inside template instantiations are implicit."] 1241 -------------------------------------------------------------------------------- 1242 template <typename T> class C { 1243 //- @"T::foo()" ref/call/implicit SFoo 1244 int x = T::foo(); 1245 }; 1246 //- @foo defines/binding SFoo 1247 struct S { static int foo(); }; 1248 C<S> cs; 1249 -------------------------------------------------------------------------------- 1250 1251 [[refdoc]] 1252 ref/doc 1253 ~~~~~~~ 1254 1255 Brief description:: 1256 A *ref/doc* C if A is an anchor inside a block of documentation that refers 1257 to C. 1258 Points from:: 1259 anchors 1260 Points toward:: 1261 semantic nodes 1262 Ordinals are used:: 1263 never 1264 See also:: 1265 <<documents,documents>> 1266 1267 [kythe,C++,"Anchors in documentation can refer to semantic nodes."] 1268 -------------------------------------------------------------------------------- 1269 //- @param_a ref/doc FooParamA 1270 //- FnFoo param.0 FooParamA 1271 //- FnFoo.node/kind function 1272 /// `param_a` is the first parameter. 1273 void foo(int param_a) { } 1274 -------------------------------------------------------------------------------- 1275 1276 [[refexpands]] 1277 ref/expands 1278 ~~~~~~~~~~~ 1279 1280 Brief description:: 1281 A *ref/expands* M if A is an anchor that expands macro M. 1282 Points from:: 1283 anchors 1284 Points toward:: 1285 <<macro,macros>> 1286 Ordinals are used:: 1287 never 1288 Notes:: 1289 This edge is used only for first-level macro expansions (where the macro 1290 being expanded is spelled out in the source file). Subsequent expansions are 1291 recorded using the <<refexpandstransitive,[ref/expands/transitive]>> edge. 1292 1293 [kythe,C++,"Uttering the name of a macro expands it."] 1294 -------------------------------------------------------------------------------- 1295 //- @FOO defines/binding MacroFoo 1296 #define FOO BAR 1297 //- @FOO ref/expands MacroFoo 1298 int FOO; 1299 -------------------------------------------------------------------------------- 1300 1301 [[refexpandstransitive]] 1302 ref/expands/transitive 1303 ~~~~~~~~~~~~~~~~~~~~~~ 1304 1305 Brief description:: 1306 A *ref/expands/transitive* M if A is an anchor that expands macro M', which 1307 (after one or more additional expansions) expands macro M. 1308 Points from:: 1309 anchors 1310 Points toward:: 1311 <<macro,macros>> 1312 Ordinals are used:: 1313 never 1314 Notes:: 1315 First-level macro expansions (like those written down in the source file) 1316 are recorded with the <<refexpands,[ref/expands]>> edge. 1317 1318 [kythe,C++,"Macros can expand other macros."] 1319 -------------------------------------------------------------------------------- 1320 //- @MB defines/binding MacroB 1321 #define MB x 1322 //- @MA defines/binding MacroA 1323 #define MA MB 1324 //- @MA ref/expands/transitive MacroB 1325 //- @MA ref/expands MacroA 1326 //- !{ @MA ref/expands/transitive MacroA } 1327 int MA; 1328 -------------------------------------------------------------------------------- 1329 1330 [[reffile]] 1331 ref/file 1332 ~~~~~~~~ 1333 1334 Brief description:: 1335 A *ref/file* F if A is an anchor referencing a file F. This is distinct from 1336 <<refincludes,[ref/includes]>>, which indicates that the anchor causes the contents of 1337 `F` to be inserted into the surrounding file. *ref/file* should be used when the 1338 anchor refers explicitly to the identity of `F`, as in a hardcoded path in a test or 1339 build script. 1340 Points from:: 1341 <<anchor>> 1342 Points toward:: 1343 <<file>> 1344 Ordinals are used:: 1345 never 1346 1347 [[refimports]] 1348 ref/imports 1349 ~~~~~~~~~~~ 1350 1351 Brief description:: 1352 A *ref/imports* B if B is imported at the site of A. 1353 Points from:: 1354 anchors 1355 Points toward:: 1356 semantic nodes 1357 Ordinals are used:: 1358 never 1359 1360 [kythe,Java,"Import references a class."] 1361 -------------------------------------------------------------------------------- 1362 //- @LinkedList ref/imports LL 1363 import java.util.LinkedList; 1364 public class E { 1365 //- @LinkedList ref LL 1366 LinkedList field; 1367 } 1368 -------------------------------------------------------------------------------- 1369 1370 [[refid]] 1371 ref/id 1372 ~~~~~~ 1373 1374 Brief description:: 1375 A *ref/id* B if A does not otherwise *ref* or *define* B but the bytes of A's 1376 span are determined by the identifier of B. 1377 Points from:: 1378 anchors 1379 Points toward:: 1380 semantic nodes 1381 Ordinals are used:: 1382 never 1383 1384 A *ref/id* edge captures a relationship between multiple objects that are 1385 grammatically required to share a name, such as a class and its constructors. 1386 1387 Add a *ref/id* edge at a usage of the governed object (e.g., the constructor) 1388 pointing to the governing object (e.g., the class). This captures the fact that 1389 the two are linked, but allows a client to distinguish the cross-references of 1390 the constructor from those of the class. 1391 1392 1393 [kythe,C++,"Constructors and destructors are named after their classes."] 1394 -------------------------------------------------------------------------------- 1395 //- @C defines/binding ClassC 1396 struct C { 1397 //- @C defines/binding CtorC 1398 //- @C ref/id ClassC 1399 C(int i); 1400 }; 1401 1402 //- @"C(1)" ref/call CtorC 1403 //- @C ref CtorC 1404 //- @C ref/id ClassC 1405 void f() { auto c = C(1); } 1406 -------------------------------------------------------------------------------- 1407 1408 [[refincludes]] 1409 ref/includes 1410 ~~~~~~~~~~~~ 1411 1412 Brief description:: 1413 A *ref/includes* F if A is an anchor that inlines the text of file F. 1414 Points from:: 1415 anchors 1416 Points toward:: 1417 <<file,files>> 1418 Ordinals are used:: 1419 never 1420 1421 [kythe,C++,"Includes include files."] 1422 -------------------------------------------------------------------------------- 1423 //- @"\"test.h\"" ref/includes HeaderFile 1424 //- HeaderFile.node/kind file 1425 #include "test.h" 1426 1427 #example test.h 1428 // ... 1429 -------------------------------------------------------------------------------- 1430 1431 [[refinit]] 1432 ref/init 1433 ~~~~~~~~ 1434 1435 Brief description:: 1436 A *ref/init* B if A is an anchor attached to an expression that initializes B, 1437 typically a field or variable. 1438 Points from:: 1439 anchors 1440 Points toward:: 1441 semantic nodes 1442 Ordinals are used:: 1443 never 1444 1445 [kythe,Go,"Initializer expressions init their fields."] 1446 -------------------------------------------------------------------------------- 1447 package p 1448 1449 type S struct { 1450 //- @F defines/binding Field 1451 F int 1452 } 1453 1454 // Positional 1455 //- @"17" ref/init Field 1456 var _ = S{17} 1457 1458 // Key-value 1459 //- @F ref/writes Field 1460 //- @"101" ref/init Field 1461 var _ = S{F: 101} 1462 -------------------------------------------------------------------------------- 1463 1464 [[refinitimplicit]] 1465 ref/init/implicit 1466 ~~~~~~~~~~~~~~~~~ 1467 1468 Brief description:: 1469 A *ref/init/implicit* B if A is an anchor attached to an expression that 1470 initializes B, typically a field or variable, and the expression spanned by A 1471 is implicit (e.g., the result of a template instantiation). 1472 Points from:: 1473 anchors 1474 Points toward:: 1475 semantic nodes 1476 Ordinals are used:: 1477 never 1478 1479 [kythe,C++,"Initializers inside template instantiations are implicit."] 1480 -------------------------------------------------------------------------------- 1481 template<typename T> class C { 1482 //- @"1" ref/init/implicit MemberX 1483 T t = {.x = 1}; 1484 }; 1485 //- @x defines/binding MemberX 1486 struct S { int x; }; 1487 C<S> cs; 1488 -------------------------------------------------------------------------------- 1489 1490 [[refqueries]] 1491 ref/queries 1492 ~~~~~~~~~~~ 1493 1494 Brief description:: 1495 A *ref/queries* M if A is an anchor that queries whether macro M is bound. 1496 Points from:: 1497 anchors 1498 Points toward:: 1499 <<macro,macros>> 1500 Ordinals are used:: 1501 never 1502 1503 [kythe,C++,"Queries to bound macros are recorded."] 1504 -------------------------------------------------------------------------------- 1505 //- @FOO defines/binding MacroFoo 1506 #define FOO BAR 1507 //- @FOO ref/queries MacroFoo 1508 //- MacroFoo.node/kind macro 1509 #if defined(FOO) 1510 #endif 1511 //- !{@BAZ ref/queries _} 1512 #ifdef BAZ 1513 #endif 1514 -------------------------------------------------------------------------------- 1515 1516 [[refwrites]] 1517 ref/writes 1518 ~~~~~~~~~~ 1519 1520 Brief description:: 1521 A *ref/writes* B if A refers to B in an expression that is likely to update 1522 the value of B. 1523 Commonly arises from:: 1524 assignment, accessor functions 1525 Points from:: 1526 anchors 1527 Points toward:: 1528 semantic nodes 1529 Ordinals are used:: 1530 never 1531 1532 [kythe,C++,"Various assignment expressions are writes"] 1533 -------------------------------------------------------------------------------- 1534 void f() { 1535 //- @x defines/binding VarX 1536 int x = 0; 1537 //- @x ref/writes VarX 1538 x = 1; 1539 // Some special forms may be supported. 1540 //- @#0x ref/writes VarX 1541 //- @#1x ref VarX 1542 *(&x) = x; 1543 // Not all forms are supported. 1544 //- @x ref VarX 1545 *(&x + 1) = 1; 1546 } 1547 -------------------------------------------------------------------------------- 1548 1549 [[refwritesthunk]] 1550 ref/writes/thunk 1551 ~~~~~~~~~~~~~~~~ 1552 1553 Brief description:: 1554 A *ref/writes/thunk* B if A refers to B in an expression that is likely to 1555 cause a later update the value of B. 1556 Commonly arises from:: 1557 value uses of setter functions, alias passing 1558 Points from:: 1559 anchors 1560 Points toward:: 1561 semantic nodes 1562 Ordinals are used:: 1563 never 1564 See also:: 1565 <<refwrites,[ref/writes]>> 1566 Notes:: 1567 This is an experimental definition and is expected to undergo refinement. 1568 1569 [kythe,C++,"Various assignment expressions are thunkful writes"] 1570 -------------------------------------------------------------------------------- 1571 void f(int* x_out, int& y_out, const int& z); 1572 void g() { 1573 //- @x defines/binding VarX 1574 //- @y defines/binding VarY 1575 //- @z defines/binding VarZ 1576 int x, y, z; 1577 //- @x ref VarX 1578 //- @y ref VarY 1579 //- @z ref VarZ 1580 //- // @x ref/writes/thunk VarX -- currently unsupported 1581 //- // @y ref/writes/thunk VarY -- currently unsupported 1582 //- !{ @z ref/writes/thunk VarZ } 1583 f(&x, y, z); 1584 } 1585 -------------------------------------------------------------------------------- 1586 1587 [[satisfies]] 1588 satisfies 1589 ~~~~~~~~~ 1590 1591 Brief description:: 1592 A *satisfies* T if A is a type that implicitly satisfies a type T. 1593 Points from:: 1594 type nodes (<<record>>, <<tapp>>, etc.) 1595 Points toward:: 1596 type nodes (<<interface>>, <<tapp>>, etc.) 1597 Ordinals are used:: 1598 never 1599 1600 [kythe,Go,"Concrete types satisfy nearby interfaces."] 1601 -------------------------------------------------------------------------------- 1602 package sat 1603 1604 //- @Badger defines/binding Badger 1605 //- Badger.node/kind interface 1606 type Badger interface { HasBadge() bool } 1607 1608 //- @SB defines/binding StaticBadger 1609 //- StaticBadger satisfies Badger 1610 type SB bool 1611 1612 //- @HasBadge defines/binding HasBadge 1613 //- HasBadge childof StaticBadger 1614 func (s SB) HasBadge() bool { return bool(s) } 1615 -------------------------------------------------------------------------------- 1616 1617 [kythe,Go,"Types of overriding methods satisfy types of overridden interface methods."] 1618 -------------------------------------------------------------------------------- 1619 package sat 1620 1621 //- @HasBadge defines/binding HasBadgeI 1622 //- HasBadgeI typed HasBadgeIType 1623 type Badger interface { HasBadge() bool } 1624 1625 type SB bool 1626 1627 //- @HasBadge defines/binding HasBadge 1628 //- HasBadge typed HasBadgeType 1629 //- HasBadgeType satisfies HasBadgeIType 1630 //- ! { HasBadge typed HasBadgeIType } 1631 func (s SB) HasBadge() bool { return bool(s) } 1632 -------------------------------------------------------------------------------- 1633 1634 [[specializes]] 1635 specializes 1636 ~~~~~~~~~~~ 1637 1638 Brief description:: 1639 A *specializes* B if A provides a declaration of a type specialization B. 1640 Commonly arises from:: 1641 template total and partial specialization 1642 Points from:: 1643 semantic nodes 1644 Points toward:: 1645 semantic nodes (<<tapp>>) 1646 Ordinals are used:: 1647 never 1648 See also:: 1649 <<instantiates>>, <<instantiatesspeculative,[instantiates/speculative]>> 1650 1651 [kythe,C++,"Template specializations specialize."] 1652 -------------------------------------------------------------------------------- 1653 //- @C defines/binding TemplateClassC 1654 template <typename T> class C { }; 1655 //- @C defines/binding SpecializedClassC 1656 template <> class C<int> { }; 1657 //- SpecializedClassC specializes TAppCInt 1658 //- TAppCInt.node/kind tapp 1659 //- TAppCInt param.0 TemplateClassC 1660 -------------------------------------------------------------------------------- 1661 1662 [kythe,C++,"Function templates specialize."] 1663 -------------------------------------------------------------------------------- 1664 //- @id defines/binding IdFn 1665 template <typename T> T id(T x) { return x; } 1666 //- @id defines/binding IdSpecFn 1667 template <> bool id(bool x) { return !(!x); } 1668 //- IdSpecFn specializes TAppIdFnBool 1669 //- TAppIdFnBool.node/kind tapp 1670 //- TAppIdFnBool param.0 IdFn 1671 //- TAppIdFnBool param.1 vname("bool#builtin",_,_,_,_) 1672 -------------------------------------------------------------------------------- 1673 1674 1675 [[specializesspeculative]] 1676 specializes/speculative 1677 ~~~~~~~~~~~~~~~~~~~~~~~ 1678 1679 See <<instantiatesspeculative,[instantiates/speculative]>>. 1680 1681 1682 [[tagged]] 1683 tagged 1684 ~~~~~~ 1685 1686 Brief description:: 1687 A *tagged* B if B labels A with a <<diagnostic>> message. 1688 Commonly arises from:: 1689 build/analysis errors 1690 Points from:: 1691 <<anchor>>, <<file>> 1692 Points toward:: 1693 <<diagnostic>> 1694 Ordinals are used:: 1695 never 1696 1697 1698 [[tparam]] 1699 tparam 1700 ~~~~~~ 1701 1702 Brief description:: 1703 A *tparam.N* B if B is the Nth type/template parameter of A. 1704 Commonly arises from:: 1705 templates, generic types 1706 Points from:: 1707 semantic nodes 1708 Points toward:: 1709 <<tvar>> 1710 Ordinals are used:: 1711 always 1712 1713 [kythe,Go,"Generics have ordered tparam edges."] 1714 -------------------------------------------------------------------------------- 1715 package tparam 1716 1717 //- Func.node/kind function 1718 //- TVar.node/kind tvar 1719 //- UVar.node/kind tvar 1720 1721 //- Func tparam.0 TVar 1722 //- Func tparam.1 UVar 1723 1724 //- @Map defines/binding Func 1725 //- @#0T defines/binding TVar 1726 //- @#0U defines/binding UVar 1727 func Map[T any, U any](l []T, f func(T) U) []U { 1728 res := make([]U, len(l)) 1729 for i, t := range l { 1730 res[i] = f(t) 1731 } 1732 return res 1733 } 1734 -------------------------------------------------------------------------------- 1735 1736 [[typed]] 1737 typed 1738 ~~~~~ 1739 1740 Brief description:: 1741 A is *typed* B if A has the type B. 1742 Commonly arises from:: 1743 terms with types; definitions and declarations 1744 Points from:: 1745 semantic nodes 1746 Points toward:: 1747 types 1748 Ordinals are used:: 1749 never 1750 1751 [kythe,C++,"Enumerations can be ascribed types."] 1752 -------------------------------------------------------------------------------- 1753 //- @E defines/binding EnumE 1754 //- EnumE typed IntType 1755 enum E : int; 1756 -------------------------------------------------------------------------------- 1757 1758 [kythe,Java,"Java methods are type applications of the builtin fn type."] 1759 -------------------------------------------------------------------------------- 1760 //- @E defines/binding E 1761 public class E { 1762 //- @func defines/binding Func 1763 //- Func typed FuncType 1764 //- FuncType.node/kind tapp 1765 //- FuncType param.0 FnBuiltin=vname("fn#builtin","","","","java") 1766 //- FuncType param.1 IntBuiltin=vname("int#builtin","","","","java") 1767 //- FuncType param.2 E 1768 //- FuncType param.3 String 1769 //- @String ref String 1770 int func(String p) { return 0; } 1771 } 1772 -------------------------------------------------------------------------------- 1773 1774 [[undefines]] 1775 undefines 1776 ~~~~~~~~~ 1777 1778 Brief description:: 1779 A *undefines* M if A detaches M from M's binding. 1780 Commonly arises from:: 1781 macro undefinition 1782 Points from:: 1783 anchors 1784 Points toward:: 1785 <<macro,macros>> 1786 1787 [kythe,C++,"Undef undefines macros."] 1788 -------------------------------------------------------------------------------- 1789 //- @FOO defines/binding MacroFoo 1790 #define FOO BAR 1791 //- @FOO undefines MacroFoo 1792 #undef FOO 1793 //- @FOO defines/binding DifferentMacroFoo 1794 #define FOO BAZ 1795 -------------------------------------------------------------------------------- 1796 1797 Common node facts 1798 ----------------- 1799 1800 Some facts can be attached to many different kinds of nodes. A subset of these 1801 (called tags) are interesting even if they have no associated values. 1802 1803 [[nodekind]] 1804 node/kind 1805 ~~~~~~~~~ 1806 1807 Brief description:: 1808 A node's *node/kind* is a label describing the role of the node in the graph. 1809 The kind is the one fact every node must have in order to participate in the 1810 rest of the schema. 1811 Attached to:: 1812 all nodes 1813 1814 [[code]] 1815 code 1816 ~~~~ 1817 1818 Brief description:: 1819 A node's *code* is a serialized link:marked-source.html[MarkedSource] 1820 message that can be used to describe that node. 1821 1822 For indexers implemented through the proxy API, *code/json* is an extra 1823 supported fact. Its value will be interpreted as a JSON-encoded MarkedSource 1824 message and will be rewritted to the equivalent wire-encoded *code* fact. 1825 1826 Attached to:: 1827 semantic nodes 1828 1829 [[docuri]] 1830 doc/uri 1831 ~~~~~~~ 1832 1833 Brief description:: 1834 If this node's primary documentation exists outside the graph, this fact can 1835 hold a URI pointing to that documentation. For example, you may want to link 1836 builtin functions to their definitions in a language's reference manual. 1837 1838 Attached to:: 1839 semantic nodes 1840 1841 [[semanticgenerated]] 1842 semantic/generated 1843 ~~~~~~~~~~~~~~~~~~ 1844 1845 Brief description:: 1846 A node's *semantic/generated* fact identifies the effect it has on nodes that 1847 generate it. Values may include `set`, indicating that this node changes its 1848 generator; or `alias`, indicating that it takes an alias to its generator. 1849 Attached to:: 1850 semantic nodes 1851 See also:: 1852 <<generates>> 1853 1854 When a target language's indexer is processing code with attached metadata 1855 (e.g., code that was generated by another tool), it may come across definitions 1856 for which it should emit a `P generates D` edge. If the metadata indicates a 1857 nontrival semantic, the indexer should attach a `semantic/generated` fact to *D* 1858 with the relevant string value. 1859 1860 [[tagdeprecated]] 1861 tag/deprecated 1862 ~~~~~~~~~~~~~~ 1863 1864 Brief description:: 1865 If this node should no longer be used, it should be marked with 1866 `tag/deprecated`. If this fact has a nonempty value, that value should be 1867 set to a UTF8-encoded human-readable reason why the node was deprecated, 1868 and/or what should be done in the future. 1869 Attached to:: 1870 semantic nodes 1871 1872 1873 [[tagstatic]] 1874 tag/static 1875 ~~~~~~~~~~ 1876 1877 Brief description:: 1878 In languages which make a distinction between class-bound and instance-bound 1879 members, members which are bound to the class should be marked with `tag/static`. 1880 Attached to:: 1881 semantic nodes 1882 1883 [kythe,Java,"Static members are tagged."] 1884 -------------------------------------------------------------------------------- 1885 class Wrapper { 1886 //- @A defines/binding StaticField 1887 //- StaticField.tag/static _ 1888 public static int A = 1; 1889 //- @field defines/binding InstanceField 1890 //- !{ InstanceField.tag/static _ } 1891 public int field = 2; 1892 } 1893 -------------------------------------------------------------------------------- 1894 1895 1896 [[tagabstract]] 1897 tag/abstract 1898 ~~~~~~~~~~~~ 1899 1900 Brief description:: 1901 In languages which have the concept of a non-instantiable class or method 1902 which must be defined by subclasses, such classes and methods should be marked 1903 with `tag/abstract`. 1904 Attached to:: 1905 semantic nodes 1906 1907 1908 Node kinds 1909 ---------- 1910 1911 [[anchor]] 1912 anchor 1913 ~~~~~~ 1914 1915 Brief description:: 1916 An *anchor* connects concrete syntax to abstract syntax. 1917 An *anchor* is within the <<file>> with the same *Path*, *Root*, *Corpus* 1918 (<<file>>s do not have a *Language*, so it is not used for matching). 1919 Naming convention:: 1920 Path::: 1921 The *Path* of the <<file>> containing this anchor (or empty if there is no 1922 such file). 1923 Root::: 1924 The *Root* of the <<file>> containing this anchor. 1925 Corpus::: 1926 The *Corpus* of the <<file>> containing this anchor. 1927 Language::: 1928 The *Language* of the compilation producing this anchor. 1929 Expected out-edges:: 1930 <<defines>>, <<definesbinding,[defines/binding]>>, <<ref>>, 1931 <<refcall,[ref/call]>> 1932 Facts:: 1933 loc/start::: 1934 The starting byte offset (from 0) in the <<file>> containing this anchor. 1935 loc/end::: 1936 The ending byte offset (exclusive) in the <<file>> containing this anchor. 1937 If the `loc/start` and `loc/end` of an anchor are both 0, this anchor refers 1938 to the whole file (for example, if a file is the `defines/binding` site for 1939 a package or module). 1940 snippet/start::: 1941 The starting byte offset (from 0) of the snippet for this anchor (optional). 1942 snippet/end::: 1943 The ending byte offset (from 0) of the snippet for this anchor (optional). 1944 build/config::: 1945 A short name describing the build configuration or platform this anchor 1946 targets (optional). 1947 subkind:: 1948 If set to `implicit`, this anchor should not also have `loc/start` or 1949 `loc/end` facts. It is an artifact of some internal process that may still 1950 have important semantic effects. 1951 See also:: 1952 <<file>> 1953 1954 Anchor VNames are specified such that one may determine the VName of the 1955 <<file>> containing an anchor by dropping the anchor VName's *Language* and 1956 *Signature* fields. 1957 1958 [kythe,C++,"Anchors have byte offsets."] 1959 -------------------------------------------------------------------------------- 1960 int 錨; 1961 //- VarNameAnchor.loc/start 4 1962 //- VarNameAnchor.loc/end 7 1963 // Note that the glyph 錨 is encoded in UTF-8 as [e9 8c a8]. 1964 -------------------------------------------------------------------------------- 1965 1966 [kythe,C++,"Anchors have VName rules."] 1967 -------------------------------------------------------------------------------- 1968 //- @foo=vname(_,Corpus,Root,Path,"c++").node/kind anchor 1969 //- File=vname("",Corpus,Root,Path,"").node/kind file 1970 int foo; 1971 -------------------------------------------------------------------------------- 1972 1973 [kythe,Java,"Anchors can overlap."] 1974 -------------------------------------------------------------------------------- 1975 import java.util.Optional; 1976 public class E { 1977 //- @"Optional<String>" ref TSpecClass 1978 //- @Optional ref OptClass 1979 //- @String ref StrClass 1980 Optional<String> f; 1981 } 1982 -------------------------------------------------------------------------------- 1983 1984 [kythe,C++,"Implicit anchors arise from default constructors."] 1985 -------------------------------------------------------------------------------- 1986 //- @C defines/binding ClassC 1987 //- CCtor childof ClassC 1988 //- CCtor.subkind constructor 1989 //- CCtor.complete definition 1990 class C { }; 1991 //- @D defines/binding ClassD 1992 //- DCtor childof ClassD 1993 //- DCtor.subkind constructor 1994 //- DCtor.complete definition 1995 class D { C c; }; 1996 D d; 1997 //- ImplicitCallToCCtor.node/kind anchor 1998 //- ImplicitCallToCCtor.subkind implicit 1999 //- ImplicitCallToCCtor ref/call/implicit CCtor 2000 //- ImplicitCallToCCtor childof DCtor 2001 -------------------------------------------------------------------------------- 2002 2003 [kythe,Java,"Anchors have VName rules."] 2004 -------------------------------------------------------------------------------- 2005 public class E { 2006 //- @foo=vname(_,Corpus,Root,Path,"java").node/kind anchor 2007 int foo; 2008 } 2009 //- File=vname("",Corpus,Root,Path,"").node/kind file 2010 -------------------------------------------------------------------------------- 2011 2012 [kythe,Go,"Anchors have VName rules."] 2013 -------------------------------------------------------------------------------- 2014 //- @anchor=vname(_,Corpus,Root,Path,"go").node/kind anchor 2015 //- File=vname("",Corpus,Root,Path,"").node/kind file 2016 package anchor 2017 -------------------------------------------------------------------------------- 2018 2019 [[constant]] 2020 constant 2021 ~~~~~~~~ 2022 2023 Brief description:: 2024 A *constant* is a value that can be statically determined. 2025 Facts:: 2026 text::: 2027 A string representation of the constant. 2028 See also:: 2029 <<sum>> 2030 2031 [kythe,C++,"Enumerators are constants."] 2032 -------------------------------------------------------------------------------- 2033 enum E { 2034 //- @EM defines/binding Enumerator 2035 EM = 42 2036 }; 2037 //- Enumerator.node/kind constant 2038 //- Enumerator.text 42 2039 -------------------------------------------------------------------------------- 2040 2041 [kythe,Java,"Enumeration values are constants."] 2042 -------------------------------------------------------------------------------- 2043 public enum E { 2044 //- @A defines/binding A 2045 //- A.node/kind constant 2046 A; 2047 } 2048 -------------------------------------------------------------------------------- 2049 2050 [[diagnostic]] 2051 diagnostic 2052 ~~~~~~~~~~ 2053 2054 Brief description:: 2055 A *diagnostic* is a node with a message concerning some aspect of the related 2056 <<file>> or <<anchor>>. These can often result from errors while building or 2057 analyzing a compilation and allow an analyzer to surface errors to end-users. 2058 Each diagnostic is linked to the related <<file>> or <<anchor>> using a 2059 <<tagged>> edge (where the diagnostic node is the target of the edge). 2060 In principle, a diagnostic could also be related to a semantic node; 2061 but that a user-facing UI might not be able to display anything meaningful 2062 without a concrete anchor. 2063 Facts:: 2064 message::: 2065 A relatively short, one-line, human-readable string explaining the 2066 diagnostic. The encoding must be UTF-8. 2067 details::: 2068 Longer form of the message that exposes more detail concerning the 2069 diagnostic. This could be very specialized to the particular diagnostic, 2070 possibly even containing stack traces or build system logs (optional). 2071 context/url::: 2072 URL leading to more detailed information concerning this diagnostic or a 2073 related group of diagnostics (optional). 2074 2075 [[doc]] 2076 doc 2077 ~~~ 2078 2079 Brief description:: 2080 A *doc* is text that documents a node. 2081 Facts:: 2082 text::: 2083 The text of the document. The encoding must be UTF-8. 2084 Notes:: 2085 Embedded references inside a *doc* node's *text* are delimited using `[` 2086 and `]`. Ordinary brackets are escaped as `\[` and `\[`; backslash is escaped 2087 as `\\`. Targets of embedded references are stored as *param* edges on the 2088 document, where the nth opening bracket is matched with the nth *param*. 2089 Indexers should strip off comment delimiters. 2090 2091 See also:: 2092 <<documents>> 2093 2094 In the following example, the `\n` in the assertion about `DocNode.text` is 2095 stored as a newline in the graph. The escape is there for the verifier. 2096 2097 [kythe,C++,"Doc nodes contain documentation text."] 2098 -------------------------------------------------------------------------------- 2099 /// A function. 2100 /// It sums its parameters `x` and `y`. 2101 int f(int x, int y) { 2102 return x + y; 2103 } 2104 //- DocNode documents FnF 2105 //- DocNode.node/kind doc 2106 //- DocNode.text " A function.\n It sums its parameters `[x]` and `[y]`." 2107 //- DocNode param.0 VarX 2108 //- DocNode param.1 VarY 2109 //- FnF param.0 VarX 2110 //- FnF param.1 VarY 2111 -------------------------------------------------------------------------------- 2112 2113 [[file]] 2114 file 2115 ~~~~ 2116 2117 Brief description:: 2118 A *file* is an array of bytes with a significant external name. 2119 Naming convention:: 2120 Language::: 2121 *empty* 2122 Path::: 2123 *External path to this file (or some other unique ID if this file is 2124 virtual)* 2125 Signature::: 2126 *empty* 2127 Facts:: 2128 language::: 2129 The source language, as used in <<_vname_conventions,VName>> 2130 `language`. This fact is optional; it is intended for use by 2131 source browsers, for things like source colorization. 2132 text::: 2133 Uninterpreted content as an array of bytes. 2134 text/encoding::: 2135 Encoding of the text fact. See 2136 http://www.w3.org/TR/encoding/#names-and-labels for standard values. If 2137 empty, "UTF-8" is assumed. 2138 See also:: 2139 <<anchor>>, <<refincludes,[ref/includes]>> 2140 2141 [kythe,C++,"File tickets are related to anchor tickets."] 2142 -------------------------------------------------------------------------------- 2143 int x; 2144 //- XAnchor=vname(_,Corpus,Root,Path,"c++").node/kind anchor 2145 //- XAnchor.loc/start 4 2146 //- XAnchor.loc/end 5 2147 //- SourceFile=vname("",Corpus,Root,Path,"").node/kind file 2148 -------------------------------------------------------------------------------- 2149 2150 [[flag]] 2151 flag 2152 ~~~~ 2153 2154 Brief description:: 2155 A *flag* is a named parameter usually passed to a program from the command 2156 line. 2157 Notes:: 2158 Indexers can support various common flag libraries. Flag nodes from different 2159 libraries are given different kind labels. For example, the Abseil/Google 2160 flag libraries will produce *flag/google* nodes. The name and default value 2161 of a flag can be derived from its <<code>> fact. 2162 2163 [[interface]] 2164 interface 2165 ~~~~~~~~~ 2166 2167 Brief description:: 2168 An *interface* defines an implementable type. 2169 2170 [kythe,Java,"Interfaces are interfaces."] 2171 -------------------------------------------------------------------------------- 2172 public class E { 2173 //- @I defines/binding Interface 2174 //- Interface.node/kind interface 2175 public static interface I {} 2176 } 2177 -------------------------------------------------------------------------------- 2178 2179 [[function]] 2180 function 2181 ~~~~~~~~ 2182 2183 Brief description:: 2184 A *function* binds zero or more parameters and returns a result. 2185 Facts:: 2186 complete::: 2187 `incomplete` if this is only a declaration; `definition` if it is a 2188 definition. 2189 subkind::: 2190 `constructor` for constructors; `destructor` for destructors; 2191 `none` or unspecified for normal or member functions. 2192 2193 [kythe,C++,"Functions are functions."] 2194 -------------------------------------------------------------------------------- 2195 //- @F defines/binding FnF 2196 //- FnF.node/kind function 2197 //- FnF.complete incomplete 2198 //- @X defines/binding VarX 2199 //- VarX.complete incomplete 2200 //- FnF param.0 VarX 2201 void F(int X); 2202 -------------------------------------------------------------------------------- 2203 2204 [[lookup]] 2205 lookup 2206 ~~~~~~~ 2207 2208 Brief description:: 2209 A *lookup* is a structured name whose resolution cannot be completed 2210 without additional context. 2211 Facts:: 2212 text::: 2213 The deferred name to be resolved. 2214 Notes:: 2215 Name resolution can be a complicated problem. In $$C++$$ templates, the 2216 meaning of a dependent name cannot be determined until the template 2217 parameters it depends upon are supplied. Similarly, in dynamic languages 2218 like Python, name resolution may depend on the runtime context. 2219 Nevertheless, when we are unable to come up with a semantic representation 2220 of one or more nodes in a path-structured name, we record this name as 2221 a collection of *lookup* nodes. Each *lookup* node has some *text* (the 2222 'dynamic' lookup done at that node) as well as some *params* (to record the 2223 semantic object into which *text* is being used as a key). 2224 2225 [kythe,C++,"Dependent names are lookups."] 2226 -------------------------------------------------------------------------------- 2227 template 2228 //- @T defines/binding DepT 2229 <template <typename> class T> 2230 struct C { 2231 //- @D ref DepTIntD 2232 using S = typename T<int>::D; 2233 }; 2234 //- DepTIntD.text D 2235 //- DepTIntD.node/kind lookup 2236 //- DepTIntD param.0 DepTInt 2237 //- DepTInt.node/kind tapp 2238 //- DepTInt param.0 DepT 2239 //- DepTInt param.1 Int 2240 -------------------------------------------------------------------------------- 2241 2242 [kythe,C++,"Lookups record paths."] 2243 -------------------------------------------------------------------------------- 2244 template 2245 <template <typename> class T> 2246 struct C { 2247 //- @F ref DepTIntDEF 2248 //- DepTIntDEF.text F 2249 //- @E ref DepTIntDE 2250 //- DepTIntDE.text E 2251 //- @D ref DepTIntD 2252 //- DepTIntD.text D 2253 using S = typename T<int>::D::E::F; 2254 }; 2255 //- DepTIntDEF param.0 DepTIntDE 2256 //- DepTIntDE param.0 DepTIntD 2257 -------------------------------------------------------------------------------- 2258 2259 [[macro]] 2260 macro 2261 ~~~~~ 2262 2263 Brief description:: 2264 A *macro* is a metaprogram that operates on source text. 2265 Notes:: 2266 Macros are distinct from <<abs,abs>> because they do not 2267 participate in the programming language proper. Instead, they are evaluated 2268 separately, usually before semantic analysis takes place. 2269 See also:: 2270 <<refexpands,[ref/expands]>>, <<refexpandstransitive,[ref/expands/transitive]>>, 2271 <<refqueries,[ref/queries]>>, <<undefines,[undefines]>> 2272 2273 [kythe,C++,"Defines define macros."] 2274 -------------------------------------------------------------------------------- 2275 //- @FOO defines/binding MacroFoo 2276 //- MacroFoo.node/kind macro 2277 #define FOO BAR 2278 -------------------------------------------------------------------------------- 2279 2280 [[meta]] 2281 meta 2282 ~~~~ 2283 2284 Brief description:: 2285 A *meta* is a node that describes details about a particular language. 2286 Naming convention:: 2287 Signature::: 2288 *kythe-node-name*#meta 2289 Language::: 2290 See <<lsr,Language-specific rules>> for language identifiers. 2291 2292 [kythe,C++,"C++ defines a meta node for tapps."] 2293 -------------------------------------------------------------------------------- 2294 //- vname("tapp#meta","","","","c++").node/kind meta 2295 -------------------------------------------------------------------------------- 2296 2297 [[name]] 2298 name 2299 ~~~~ 2300 2301 Brief description:: 2302 A *name* specifies an external identifier for a node, typically used for linking. 2303 Naming convention:: 2304 Signature::: 2305 The name string. 2306 Language::: 2307 The namespace to which the name belongs. 2308 Path::: 2309 *empty* 2310 Root::: 2311 *empty* 2312 Corpus::: 2313 *empty* 2314 Notes:: 2315 The namespace is some domain in which the names are expected to be unique at linkage 2316 time and/or runtime, such as the Itanium C++ ABI. 2317 2318 [[package]] 2319 package 2320 ~~~~~~ 2321 2322 Brief description:: 2323 A *package* defines a module containing declarations. 2324 Notes:: 2325 Languages in which a module is implicitly defined based on the file name 2326 should emit a `defines/implicit` edge from a zero-width anchor at offset 0 in 2327 that file to the corresponding package node. 2328 2329 [kythe,Java,"Top-level declarations are children of package nodes."] 2330 -------------------------------------------------------------------------------- 2331 //- @pkg ref Pkg 2332 //- Pkg.node/kind package 2333 package pkg; 2334 //- @E defines/binding ClassE 2335 //- ClassE childof Pkg 2336 public class E {} 2337 -------------------------------------------------------------------------------- 2338 2339 [kythe,Go,"Files belonging to a package are children of that package."] 2340 -------------------------------------------------------------------------------- 2341 //- @foo defines/binding Pkg 2342 //- Pkg.node/kind package 2343 package foo 2344 2345 //- File = vname("", _, _, "schema/example.go", "").node/kind file 2346 //- File childof Pkg 2347 -------------------------------------------------------------------------------- 2348 2349 [[process]] 2350 process 2351 ~~~~~~~ 2352 2353 Brief description:: 2354 A *process* describes an abstract processing action in a workflow. 2355 Facts:: 2356 label::: 2357 A string label used to identify the process (optional). 2358 See also:: 2359 <<depends>> 2360 2361 A *process* defines a processing action such as a step in a build or the 2362 execution of a continuous integration workflow. For workflows that assign 2363 identifying labels to processing steps (such as target names), the `label` 2364 should carry the name so assigned. 2365 2366 [[record]] 2367 record 2368 ~~~~~~ 2369 2370 Brief description:: 2371 A *record* defines a type composed of a collection of elements. 2372 Facts:: 2373 subkind::: 2374 <<lsr,Language-specific subkind>> for this record. 2375 complete::: 2376 `incomplete` if this is only a declaration; `definition` if it is a 2377 definition. 2378 Notes:: 2379 This node is a nominal record such that two records with the same 2380 children but different names should always be considered to be distinct. 2381 2382 [kythe,C++,"Classes are records."] 2383 -------------------------------------------------------------------------------- 2384 //- @C defines/binding ClassCDecl 2385 //- ClassCDecl.node/kind record 2386 //- ClassCDecl.complete incomplete 2387 class C; 2388 2389 //- @C defines/binding ClassCDefn 2390 //- ClassCDefn.node/kind record 2391 //- ClassCDefn.complete definition 2392 class C { }; 2393 -------------------------------------------------------------------------------- 2394 2395 [kythe,Java,"Classes are records."] 2396 -------------------------------------------------------------------------------- 2397 package pkg; 2398 //- @E defines/binding ClassE 2399 //- ClassE.node/kind record 2400 //- ClassE.subkind class 2401 public class E { 2402 } 2403 -------------------------------------------------------------------------------- 2404 2405 [[sum]] 2406 sum 2407 ~~~ 2408 2409 Brief description:: 2410 A *sum* defines a type whose instances must choose one out of a set of 2411 possible representations. 2412 Facts:: 2413 subkind::: 2414 <<lsr,Language-specific subkind>> for this record. 2415 complete::: 2416 * `incomplete` if this is only a declaration. 2417 * `complete` if this is a declaration that is considered usable by value. 2418 * `definition` if this provides a full description of the type. 2419 2420 [kythe,C++,"Enums are sums."] 2421 -------------------------------------------------------------------------------- 2422 //- @CE defines/binding EnumCE 2423 //- EnumCE.node/kind sum 2424 //- EnumCE.complete definition 2425 enum CE { }; 2426 2427 //- @E defines/binding EnumE 2428 //- EnumE.node/kind sum 2429 //- EnumE.complete incomplete 2430 enum class E; 2431 2432 //- @E defines/binding EnumETyped 2433 //- EnumETyped.node/kind sum 2434 //- EnumETyped.complete complete 2435 enum class E : int; 2436 2437 //- @E defines/binding EnumEDefn 2438 //- EnumEDefn.node/kind sum 2439 //- EnumEDefn.complete definition 2440 enum class E : int { }; 2441 -------------------------------------------------------------------------------- 2442 2443 [kythe,Java,"Enums are sum/enumClasses."] 2444 -------------------------------------------------------------------------------- 2445 //- @E defines/binding EnumE 2446 //- E.node/kind sum 2447 //- E.subkind enumClass 2448 public enum E {} 2449 -------------------------------------------------------------------------------- 2450 2451 [[symbol]] 2452 symbol 2453 ~~~~~~ 2454 2455 Brief description:: 2456 A *symbol* is a common name used by tools to refer to a set of objects. 2457 The spelling of a symbol is defined per language, and should be constructible by 2458 tools that do not necessarily have direct access to the compiler. 2459 The rules for binding a symbol to a particular object from this set may depend on 2460 external configuration (such as the list of libraries being linked together to produce 2461 an executable). 2462 Naming convention:: 2463 Path::: 2464 *empty* 2465 Root::: 2466 *empty* 2467 Corpus::: 2468 *empty* 2469 2470 [[talias]] 2471 talias 2472 ~~~~~~ 2473 2474 Brief description:: 2475 A *talias* gives a new name to an existing type. 2476 Expected out-edges:: 2477 <<aliases>> 2478 Notes:: 2479 A *talias* may be virtually removed from the graph. Some languages may have 2480 additional reduction rules. 2481 2482 [kythe,C++,"Type aliases are taliases."] 2483 -------------------------------------------------------------------------------- 2484 //- @Counter defines/binding TAlias 2485 //- TAlias.node/kind talias 2486 using Counter = int; 2487 -------------------------------------------------------------------------------- 2488 2489 [[tapp]] 2490 tapp 2491 ~~~~ 2492 2493 Brief description:: 2494 A *tapp* applies a type constructor or <<abs>> to zero or more parameters. 2495 Expected out-edges:: 2496 <<param>> (at least ordinal 0) 2497 2498 [kythe,C++,"Pointers are type constructors."] 2499 -------------------------------------------------------------------------------- 2500 //- @PtrInt defines/binding PtrIntAlias 2501 //- PtrIntAlias aliases IntPtrType 2502 using PtrInt = int*; 2503 //- IntPtrType.node/kind tapp 2504 //- IntPtrType param.0 vname("ptr#builtin",_,_,_,"c++") 2505 //- IntPtrType param.1 vname("int#builtin",_,_,_,"c++") 2506 -------------------------------------------------------------------------------- 2507 2508 [kythe,Java,"Generic classes are type constructors."] 2509 -------------------------------------------------------------------------------- 2510 import java.util.Optional; 2511 public class E { 2512 //- @f defines/binding Field 2513 //- Field typed TSpecClass 2514 //- TSpecClass.node/kind tapp 2515 //- TSpecClass param.0 OptClass 2516 //- TSpecClass param.1 StrClass 2517 Optional<String> f; 2518 } 2519 -------------------------------------------------------------------------------- 2520 2521 [[tbuiltin]] 2522 tbuiltin 2523 ~~~~~~~~ 2524 2525 Brief description:: 2526 A *tbuiltin* is a type that is supplied by the language itself. 2527 Naming convention:: 2528 Signature::: 2529 *language-specific-string*#builtin 2530 Notes:: 2531 See the <<lsr,Language-specific rules>> section below for enumerations of 2532 these builtin types. 2533 2534 [kythe,C++,"Int is a builtin."] 2535 -------------------------------------------------------------------------------- 2536 //- @int ref TInt 2537 //- TInt.node/kind tbuiltin 2538 using Int = int; 2539 -------------------------------------------------------------------------------- 2540 2541 [[tnominal]] 2542 tnominal 2543 ~~~~~~~~ 2544 2545 Brief description:: 2546 A *tnominal* is a type that may be purely identified by its name. 2547 Notes:: 2548 When a `tnominal`'s definition is known, some <<lsr,language-specific rules>> 2549 dictate that the definition node be used instead of a `tnominal` in the 2550 type graph. 2551 2552 [kythe,C++,"Forward-declared classes are tnominals."] 2553 -------------------------------------------------------------------------------- 2554 //- @C defines/binding ClassC 2555 //- ClassC.node/kind record 2556 class C; 2557 //- @Alias defines/binding Alias 2558 //- Alias aliases PtrC 2559 //- PtrC param.1 NominalC 2560 //- NominalC.node/kind tnominal 2561 using Alias = C*; 2562 -------------------------------------------------------------------------------- 2563 2564 2565 [[tsigma]] 2566 tsigma 2567 ~~~~ 2568 2569 Brief description:: 2570 A *tsigma* is an ordered list of types that is unpacked on substitution. 2571 Expected out-edges:: 2572 <<param>> (at least ordinal 0) 2573 2574 [kythe,C++,"Parameter packs unpack tsigmas."] 2575 -------------------------------------------------------------------------------- 2576 template <typename... Ts> 2577 //- @f defines/binding FnTF 2578 void f(Ts... ts) { } 2579 2580 //- @int ref IntType 2581 //- @double ref DoubleType 2582 //- @f ref AppFnTFSigma 2583 int g(double x) { f(1, x); } 2584 2585 //- FnF instantiates AppFnTFSigma 2586 //- FnF.node/kind function 2587 //- AppFnTFSigma param.0 FnTF 2588 //- AppFnTFSigma param.1 Sigma 2589 //- Sigma.node/kind tsigma 2590 //- Sigma param.0 IntType 2591 //- Sigma param.1 DoubleType 2592 -------------------------------------------------------------------------------- 2593 2594 2595 [[tvar]] 2596 tvar 2597 ~~~~ 2598 2599 Brief description:: 2600 A *tvar* is a type/template parameter and bound to a semantic node with a 2601 <<tparam>> edge. 2602 See also:: 2603 <<tapp>>, <<tparam>>, <<specializes>> 2604 2605 [kythe,Go,"Type parameters are tvars."] 2606 -------------------------------------------------------------------------------- 2607 package tvar 2608 2609 //- Container.node/kind record 2610 //- TVar.node/kind tvar 2611 2612 //- Container tparam.0 TVar 2613 2614 //- @Container defines/binding Container 2615 //- @T defines/binding TVar 2616 type Container[T any] struct { 2617 //- @T ref TVar 2618 Element T 2619 } 2620 -------------------------------------------------------------------------------- 2621 2622 [kythe,C++,"Type variables are tvars."] 2623 -------------------------------------------------------------------------------- 2624 //- @C defines/binding TemplateC 2625 //- @T defines/binding TVarT 2626 //- TVarT.node/kind tvar 2627 //- TemplateC tparam.0 TVarT 2628 template <typename T> class C { 2629 //- @T ref TVarT 2630 using S = T; 2631 }; 2632 -------------------------------------------------------------------------------- 2633 2634 [[variable]] 2635 variable 2636 ~~~~~~~~ 2637 2638 Brief description:: 2639 A *variable* is a location for storing data. 2640 Facts:: 2641 complete::: 2642 * `incomplete` if this is only a declaration. 2643 * `definition` if this is a variable definition. 2644 Subkinds:: 2645 * `local` for variables in function scope. 2646 * `local/parameter` for variables passed into functions. 2647 * `field` for variables that are data members of some record. 2648 * `import` for variables that reference objects in other modules. 2649 2650 [kythe,C++,"Variables are variables."] 2651 -------------------------------------------------------------------------------- 2652 //- @x defines/binding VariableX 2653 //- VariableX.node/kind variable 2654 int x; 2655 -------------------------------------------------------------------------------- 2656 2657 [kythe,Java,"Fields are variables."] 2658 -------------------------------------------------------------------------------- 2659 import java.util.Optional; 2660 public class E { 2661 //- @f defines/binding Field 2662 //- Field.node/kind variable 2663 //- Field.subkind field 2664 Optional<String> f; 2665 } 2666 -------------------------------------------------------------------------------- 2667 2668 [kythe,Java,"Parameters are variables."] 2669 -------------------------------------------------------------------------------- 2670 public class E { 2671 //- @arg defines/binding Param 2672 //- Param.node/kind variable 2673 //- Param.subkind local/parameter 2674 void f(String arg) {} 2675 } 2676 -------------------------------------------------------------------------------- 2677 2678 [kythe,Java,"Locals are variables."] 2679 -------------------------------------------------------------------------------- 2680 public class E { 2681 void f() { 2682 //- @var defines/binding Local 2683 //- Local.node/kind variable 2684 //- Local.subkind local 2685 String var; 2686 } 2687 } 2688 -------------------------------------------------------------------------------- 2689 2690 2691 [[vcs]] 2692 vcs 2693 ~~~ 2694 2695 Brief description:: 2696 A *vcs* is a reference to a particular revision stored in a version control 2697 system. 2698 Facts:: 2699 vcs/id::: 2700 A stable identifier for a revision in the repository. For example, a 2701 Git repository uses commit hashes as identifiers. 2702 vcs/type::: 2703 * `darcs`: this is a Darcs repository. 2704 * `git`: this is a Git repository. 2705 * `hg`: this is a Mercurial repository. 2706 * `perforce`: this is a Perforce repository. 2707 * `svn`: this is a Subversion repository. 2708 vcs/uri::: 2709 A URI that points to the repository root. Acceptable values for this fact 2710 depend on the `vcs/type`. 2711 Naming convention:: 2712 When naming a `vcs` node, it is a good idea to use only the `corpus` field 2713 of a VName. You can then use that `corpus` value in the VNames of all nodes 2714 that are generated from that revision. 2715 Notes:: 2716 It is important that the `vcs` uses a stable reference to a revision. For 2717 example, using the name of a Git branch would not be a good idea, since 2718 Git branches point to different commits over time. It is better to use the 2719 (full) hash of the commit. 2720 2721 [[variance]] 2722 Variance 2723 -------- 2724 2725 Some languages (like Objective C) allow you to specify the variance of a 2726 type argument as it relates to the typing relationship of the class it is a 2727 parameter for. This is different than the bounds that may be placed on a type 2728 variable. The bounds are represented with <<bounded>> edges. Variance is 2729 stored as a fact in the node for the type variable. 2730 2731 For example, `@interface G1<__covariant Type : P1*> : Root` states that `G1` is a 2732 generic type, `G1` takes a single type parameter that has an upper bound of `P1*`, 2733 and `G1<T>` is a subtype of `G1<U>` if and only if `T` is a subtype of `U`. 2734 2735 Specifically for Objective C, the default variance is invariant, so 2736 `@interface G1<Type : P1*> : Root` states that `G1<T>` is a subtype of `G2<U>` 2737 if and only if T == U. 2738 2739 The variance fact can be omitted, in which case covariance is assumed. 2740 2741 [kythe,ObjC,"Variance for a generic type"] 2742 -------------------------------------------------------------------------------- 2743 @interface Root 2744 @end 2745 2746 @interface P1 : Root 2747 @end 2748 2749 @interface P2 : P1 2750 @end 2751 2752 //- @Type defines/binding TypeVar1 2753 //- @G1 defines/binding G1Abs 2754 //- TypeVar1.node/kind tvar 2755 //- TypeVar1.variance covariant 2756 //- G1Abs tparam.0 TypeVar1 2757 @interface G1<__covariant Type> : Root 2758 @end 2759 2760 //- @Type defines/binding TypeVar2 2761 //- @G2 defines/binding G2Abs 2762 //- TypeVar2.node/kind tvar 2763 //- TypeVar2.variance contravariant 2764 //- G2Abs tparam.0 TypeVar2 2765 @interface G2<__contravariant Type> : Root 2766 @end 2767 2768 int main(int argc, char **argv) { 2769 // Example of variance in action. 2770 G1<P2*> *g1var = [[G1 alloc] init]; 2771 G1<P1*> *g1var2 = g1var; 2772 2773 G2<P1*> *g2var = [[G1 alloc] init]; 2774 G2<P2*> *g2var2 = g2var; 2775 2776 return 0; 2777 } 2778 -------------------------------------------------------------------------------- 2779 2780 2781 [[lsr]] 2782 Language-specific rules 2783 ----------------------- 2784 2785 $$C++$$ 2786 ~~~~~~~ 2787 2788 $$C++$$'s source language is spelled "`c++`". 2789 2790 Builtin types 2791 ^^^^^^^^^^^^^ 2792 2793 $$C++$$ supplies the following <<tbuiltin>> nodes by default: 2794 2795 [kythe,C++,"Builtin type nodes"] 2796 -------------------------------------------------------------------------------- 2797 //- @"void" ref vname("void#builtin","","","","c++") 2798 using Void = void; 2799 2800 //- @PtrVoid defines/binding AliasTappPtrVoid 2801 //- AliasTappPtrVoid aliases TappPtrVoid 2802 //- TappPtrVoid param.0 vname("ptr#builtin","","","","c++") 2803 using PtrVoid = void*; 2804 2805 //- @"int" ref vname("int#builtin","","","","c++") 2806 using Int = int; 2807 2808 //- @ConstVoid defines/binding TappConstVoidAlias 2809 //- TappConstVoidAlias aliases TAppConstVoid 2810 //- TAppConstVoid param.0 vname("const#builtin","","","","c++") 2811 using ConstVoid = const void; 2812 2813 //- @VolatileVoid defines/binding TappVolatileVoidAlias 2814 //- TappVolatileVoidAlias aliases TAppVolatileVoid 2815 //- TAppVolatileVoid param.0 vname("volatile#builtin","","","","c++") 2816 using VolatileVoid = volatile void; 2817 2818 ///- @RestrictPtrVoid defines/binding TappRestrictPtrVoidAlias 2819 ///- TappRestrictPtrVoidAlias aliases TAppRestrictPtrVoid 2820 ///- TAppRestrictPtrVoid param.0 vname("restrict#builtin","","","","c++") 2821 using RestrictPtrVoid = void * __restrict__; 2822 -------------------------------------------------------------------------------- 2823 2824 Record and sum subkinds 2825 ^^^^^^^^^^^^^^^^^^^^^^^ 2826 2827 $$C++$$ defines the following subkinds for <<record>> nodes: 2828 2829 [kythe,C++,"Record subkinds"] 2830 -------------------------------------------------------------------------------- 2831 //- @C defines/binding ClassC 2832 //- C.subkind class 2833 class C; 2834 2835 //- @S defines/binding StructS 2836 //- S.subkind struct 2837 struct S; 2838 2839 //- @U defines/binding UnionU 2840 //- U.subkind union 2841 union U; 2842 -------------------------------------------------------------------------------- 2843 2844 $$C++$$ defines the following subkinds for <<sum>> nodes: 2845 2846 [kythe,C++,"Sum subkinds"] 2847 -------------------------------------------------------------------------------- 2848 //- @E defines/binding EnumE 2849 //- E.subkind enum 2850 enum E { }; 2851 2852 //- @EC defines/binding EnumClassEC 2853 //- EnumClassEC.subkind enumClass 2854 enum class EC; 2855 -------------------------------------------------------------------------------- 2856 2857 References to definitions and declarations of types 2858 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2859 2860 If the indexer has available a *definition* of a $$C++$$ node, edges should 2861 be drawn directly to that node: 2862 2863 [kythe,C++,"Refer to definitions directly."] 2864 -------------------------------------------------------------------------------- 2865 //- @C defines/binding ClassCDefn 2866 class C { }; 2867 //- @Alias defines/binding CAlias 2868 //- CAlias aliases ClassCDefn 2869 using Alias = C; 2870 -------------------------------------------------------------------------------- 2871 2872 If the indexer only has a *complete* $$C++$$ node, or if the node is 2873 *incomplete*, edges should be drawn to a <<tnominal>> node: 2874 2875 [kythe,C++,"Refer to complete or incomplete declarations indirectly."] 2876 -------------------------------------------------------------------------------- 2877 //- @E defines/binding CompleteEnumE 2878 enum class E : int; 2879 //- @Alias defines/binding EAlias 2880 //- EAlias aliases EnumETNominal 2881 //- EnumETNominal.node/kind tnominal 2882 using Alias = E; 2883 -------------------------------------------------------------------------------- 2884 2885 When generating the name of a $$C++$$ type that requires looking down some 2886 edge, the following should be kept in mind. If there are multiple possible 2887 nodes connected by *edge*, consistently prefer one that has a `complete` 2888 fact set to `definition`; failing that, prefer one that has a `complete` 2889 fact set to `complete`; failing that, consistently prefer an arbitrary 2890 node from the *edge*-connected set (see <<record>>, <<sum>>). 2891 2892 Qualifiers on types 2893 ^^^^^^^^^^^^^^^^^^^ 2894 2895 The `const`, `restrict`, and `volatile` qualifiers may be applied to types. 2896 These are represented as type constructors. The indexer always applies them 2897 in the same order (`const` innermost, then `restrict`, then `volatile`) and 2898 collapses redundant qualifiers should they arise (`const const` becomes 2899 `const`). Tools should optimally canonicalize types according to these rules 2900 (for instance, after removing a <<talias>> node). 2901 2902 [kythe,C++,"Qualifiers have canonical order."] 2903 -------------------------------------------------------------------------------- 2904 //- @U defines/binding VRCAlias 2905 //- VRCAlias aliases VRCInt 2906 using U = int * __restrict__ const volatile; 2907 //- @V defines/binding AnotherAlias 2908 //- AnotherAlias aliases VRCInt 2909 using V = int * volatile __restrict__ const; 2910 -------------------------------------------------------------------------------- 2911 2912 [kythe,C++,"Redundant CVR-qualifiers are dropped."] 2913 -------------------------------------------------------------------------------- 2914 #arguments -Wno-duplicate-decl-specifier 2915 //- @U defines/binding CIAlias 2916 //- CIAlias aliases CIType 2917 using U = const const int; 2918 //- @V defines/binding AnotherCIAlias 2919 //- AnotherCIAlias aliases CIType 2920 using V = const int; 2921 -------------------------------------------------------------------------------- 2922 2923 Function types 2924 ^^^^^^^^^^^^^^ 2925 2926 The `fn#builtin` type constructor is used to represent function types. Its 2927 first parameter is the return type; its second parameter is the receiver type; 2928 subsequent parameters are arguments. Functions without an explicit return type 2929 will return a language-specific "void" type. Functions without a receiver type 2930 will use a language-specific "empty" receiver type. 2931 2932 [kythe,C++,"C++ function types use a builtin type constructor."] 2933 -------------------------------------------------------------------------------- 2934 //- @U defines/binding UAlias 2935 //- UAlias aliases TAppFn 2936 //- TAppFn param.0 vname("fn#builtin",_,_,_,_) 2937 //- TAppFn param.1 vname("int#builtin",_,_,_,_) 2938 //- TAppFn param.2 vname("short#builtin",_,_,_,_) 2939 //- TAppFn param.3 vname("float#builtin",_,_,_,_) 2940 using U = int(short, float); 2941 // TODO(#3613): add receiver type to C++ function types 2942 -------------------------------------------------------------------------------- 2943 2944 For K&R-style prototypes in C, the indexer will use the `knrfn#builtin` type. 2945 2946 [kythe,Go,"Function types use a builtin type constructor."] 2947 -------------------------------------------------------------------------------- 2948 package foo 2949 2950 //- @fn defines/binding Func 2951 //- Func typed FuncType 2952 //- FuncType.node/kind tapp 2953 //- FuncType param.0 FnBuiltin=vname("fn#builtin",_,_,_,_) 2954 //- FnBuiltin.node/kind tbuiltin 2955 func fn() {} 2956 -------------------------------------------------------------------------------- 2957 2958 [kythe,Go,"Go void functions return the empty tuple type."] 2959 -------------------------------------------------------------------------------- 2960 package foo 2961 2962 //- @fn defines/binding Func 2963 //- Func typed FuncType 2964 //- FuncType param.1 EmptyTuple 2965 //- EmptyTuple.node/kind tapp 2966 //- EmptyTuple param.0 TupleBuiltin=vname("tuple#builtin",_,_,_,_) 2967 //- TupleBuiltin.node/kind tbuiltin 2968 //- ! { EmptyTuple param.1 _ } 2969 func fn() {} 2970 -------------------------------------------------------------------------------- 2971 2972 [kythe,Go,"Go functions have an empty tuple type receiver."] 2973 -------------------------------------------------------------------------------- 2974 package foo 2975 2976 //- @fn defines/binding Func 2977 //- Func typed FuncType 2978 //- FuncType param.2 EmptyTuple 2979 //- EmptyTuple.node/kind tapp 2980 //- EmptyTuple param.0 TupleBuiltin=vname("tuple#builtin",_,_,_,_) 2981 //- TupleBuiltin.node/kind tbuiltin 2982 //- ! { EmptyTuple param.1 _ } 2983 func fn() {} 2984 -------------------------------------------------------------------------------- 2985 2986 [kythe,Go,"Go methods have a non-empty receiver type."] 2987 -------------------------------------------------------------------------------- 2988 package foo 2989 2990 //- @S defines/binding S 2991 type S struct {} 2992 2993 //- @Method defines/binding Method 2994 //- Method typed MethodType 2995 //- MethodType param.2 S 2996 func (S) Method() {} 2997 2998 //- @PMethod defines/binding PMethod 2999 //- PMethod typed PMethodType 3000 //- PMethodType param.2 SPointer 3001 //- SPointer.node/kind tapp 3002 //- SPointer param.0 vname("pointer#builtin",_,_,_,_) 3003 //- SPointer param.1 S 3004 func (*S) PMethod() {} 3005 -------------------------------------------------------------------------------- 3006 3007 [kythe,Java,"Java constructors have their parent class as a return/receiver type."] 3008 -------------------------------------------------------------------------------- 3009 //- @E defines/binding E 3010 public class E { 3011 //- @E defines/binding ECtor 3012 //- ECtor typed FnType 3013 //- FnType.node/kind tapp 3014 //- FnType param.0 vname("fn#builtin",_,_,_,_) 3015 //- FnType param.1 E 3016 //- FnType param.2 E 3017 public E() {} 3018 } 3019 -------------------------------------------------------------------------------- 3020 3021 [kythe,Java,"Java static methods have a void receiver type."] 3022 -------------------------------------------------------------------------------- 3023 public class E { 3024 //- @f defines/binding F 3025 //- F typed FnType 3026 //- FnType.node/kind tapp 3027 //- FnType param.0 vname("fn#builtin",_,_,_,_) 3028 //- FnType param.1 vname("int#builtin",_,_,_,_) 3029 //- FnType param.2 vname("void#builtin",_,_,_,_) 3030 public static int f() { return 0; } 3031 } 3032 -------------------------------------------------------------------------------- 3033 3034 Structural hashes 3035 ^^^^^^^^^^^^^^^^^ 3036 3037 <<record>> and <<sum>> definitions are given vnames with `signatures` composed 3038 of their lexical names and their *structural hash*, which unifies equivalent 3039 definitions that appear across distinct and unrelated translation units. 3040 3041 Template template parameters 3042 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3043 3044 Template template parameters are represented from the outside in. In this 3045 example, the top-level template C's first <<tparam>> is the template template 3046 parameter B. This is stored as a <<tvar>>. Then the ordinary template 3047 parameter A is B's first <<tparam>>. 3048 3049 [kythe,C++,"We do not represent higher kinds"] 3050 -------------------------------------------------------------------------------- 3051 //- @A defines/binding TvarA 3052 //- @B defines/binding TvarB 3053 //- @C defines/binding TemplateC 3054 template <template <typename A> class B> class C; 3055 //- TemplateC tparam.0 TvarB 3056 //- TvarB tparam.0 TvarA 3057 -------------------------------------------------------------------------------- 3058 3059 Special values for dependent lookups 3060 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3061 3062 Sometimes, the indexer must synthesize a <<lookup>> node to a constructor or 3063 destructor without knowing the name of the type being constructed or destroyed. 3064 In this case, the constructor (or destructor) is named `#ctor` (or `#dtor`): 3065 3066 [kythe,C++,"Dependent ctors and dtors"] 3067 -------------------------------------------------------------------------------- 3068 //- @T defines/binding TyvarT 3069 template <typename T> 3070 class C : T { 3071 //- @"T()" ref/call LookupTCtor 3072 //- LookupTCtor.node/kind lookup 3073 //- LookupTCtor param.0 TyvarT 3074 //- LookupTCtor.text "#ctor" 3075 C() : T() { } 3076 3077 T *t; 3078 //- @"delete t" ref/call LookupTDtor 3079 //- LookupTDtor.node/kind lookup 3080 //- LookupTDtor param.0 TyvarT 3081 //- LookupTDtor.text "#dtor" 3082 void f() { delete t; } 3083 }; 3084 -------------------------------------------------------------------------------- 3085 3086 Go 3087 ~~ 3088 3089 The source language for Go is spelled "`go`". 3090 3091 Type Definitions 3092 ^^^^^^^^^^^^^^^^ 3093 3094 A Go type definition like `type Foo Bar` creates a new named type `Foo` with 3095 the same structure as `Bar` but with a distinct method set. In the Kythe schema 3096 we model `Foo` as a <<record>> node. If the underlying type is not already a 3097 struct this node is given the subkind `type`. 3098 3099 [kythe,Go,"Type definitions"] 3100 -------------------------------------------------------------------------------- 3101 package tdef 3102 3103 //- @Foo defines/binding Foo 3104 //- Foo.node/kind record 3105 //- Foo.subkind type 3106 type Foo int 3107 3108 type bar struct { z int } 3109 3110 //- @Bar defines/binding Bar 3111 //- Bar.node/kind record 3112 //- Bar.subkind struct 3113 type Bar bar 3114 3115 //- @Pbar defines/binding Pbar 3116 //- Pbar.node/kind record 3117 //- Pbar.subkind type 3118 type Pbar []bar 3119 -------------------------------------------------------------------------------- 3120 3121 Java 3122 ~~~~ 3123 3124 Java's source language is spelled "`java`". 3125 3126 Builtin types 3127 ^^^^^^^^^^^^^ 3128 3129 Java supplies the following <<tbuiltin>> nodes by default: 3130 3131 [kythe,Java,"Builtin type nodes"] 3132 -------------------------------------------------------------------------------- 3133 public class E { 3134 //- @f defines/binding F 3135 //- F typed FnType 3136 //- FnType.node/kind tapp 3137 //- FnType param.0 FnBuiltin = vname("fn#builtin","","","","java") 3138 //- FnType param.1 VoidBuiltin = vname("void#builtin","","","","java") 3139 public static void f( 3140 //- FnType param.3 BooleanBuiltin = vname("boolean#builtin","","","","java") 3141 boolean bool, 3142 //- FnType param.4 ByteBuiltin = vname("byte#builtin","","","","java") 3143 byte b, 3144 //- FnType param.5 ShortBuiltin = vname("short#builtin","","","","java") 3145 short s, 3146 //- FnType param.6 IntBuiltin = vname("int#builtin","","","","java") 3147 int i, 3148 //- FnType param.7 LongBuiltin = vname("long#builtin","","","","java") 3149 long l, 3150 //- FnType param.8 CharBuiltin = vname("char#builtin","","","","java") 3151 char c, 3152 //- FnType param.9 FloatBuiltin = vname("float#builtin","","","","java") 3153 float f, 3154 //- FnType param.10 DoubleBuiltin = vname("double#builtin","","","","java") 3155 double d, 3156 //- FnType param.11 StrArray 3157 //- StrArray.node/kind tapp 3158 //- StrArray param.0 ArrayBuiltin = vname("array#builtin","","","","java") 3159 //- StrArray param.1 String 3160 String[] arry) {} 3161 } 3162 -------------------------------------------------------------------------------- 3163 3164 3165 Node Subkinds 3166 ^^^^^^^^^^^^^ 3167 3168 Classes and Enums 3169 +++++++++++++++++ 3170 3171 In Java, classes are [[record]] nodes with a subkind of 'class'. Likewise, enum 3172 classes are [[sum]] nodes with a subkind of 'enumClass'. 3173 3174 [kythe,Java,"Classes and enums"] 3175 -------------------------------------------------------------------------------- 3176 //- @E defines/binding EClass 3177 //- EClass.node/kind record 3178 //- EClass.subkind class 3179 public class E { 3180 3181 //- @Enum defines/binding Enum 3182 //- Enum.node/kind sum 3183 //- Enum.subkind enumClass 3184 static enum Enum {} 3185 } 3186 -------------------------------------------------------------------------------- 3187 3188 Functions 3189 +++++++++ 3190 3191 All methods are [[function]] nodes, including class constructors. To 3192 differentiate between constructors and other methods, [[function]] nodes for 3193 constructors have the subkind 'constructor'. 3194 3195 [kythe,Java,"Methods and constructors"] 3196 -------------------------------------------------------------------------------- 3197 public class E { 3198 3199 //- @E defines/binding ECtor 3200 //- ECtor.node/kind function 3201 //- ECtor.subkind constructor 3202 public E() {} 3203 3204 //- @staticMethod defines/binding StaticMethod 3205 //- StaticMethod.node/kind function 3206 public static void staticMethod() {} 3207 3208 //- @instanceMethod defines/binding InstanceMethod 3209 //- InstanceMethod.node/kind function 3210 public void instanceMethod() {} 3211 } 3212 -------------------------------------------------------------------------------- 3213 3214 Variables 3215 +++++++++ 3216 3217 Java has 5 types of [[variable]] nodes, each with a distinct subkind: 3218 3219 Fields:: 'field' subkind 3220 Locals:: 'local' subkind 3221 Exception Variables (see http://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html[catch blocks]):: 'local/exception' subkind 3222 Parameters:: 'local/parameter' subkind 3223 Resource Variables (see the http://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html[try-with-resources statement]):: 'local/resource' subkind 3224 3225 [kythe,Java,"Variables"] 3226 -------------------------------------------------------------------------------- 3227 import java.io.IOException; 3228 import java.io.OutputStream; 3229 3230 public class E { 3231 3232 //- @field defines/binding Field 3233 //- Field.node/kind variable 3234 //- Field.subkind field 3235 private final Object field = null; 3236 3237 //- @param defines/binding Parameter 3238 //- Parameter.node/kind variable 3239 //- Parameter.subkind local/parameter 3240 public static void m(String param) throws IOException { 3241 3242 //- @local defines/binding Local 3243 //- Local.node/kind variable 3244 //- Local.subkind local 3245 int local = 42; 3246 3247 //- @resource defines/binding ResourceVar 3248 //- ResourceVar.node/kind variable 3249 //- ResourceVar.subkind local/resource 3250 try (OutputStream resource = System.out) { 3251 resource.write("hello".getBytes()); 3252 3253 //- @exception defines/binding ExceptionVar 3254 //- ExceptionVar.node/kind variable 3255 //- ExceptionVar.subkind local/exception 3256 } catch (IOException exception) {} 3257 } 3258 } 3259 -------------------------------------------------------------------------------- 3260 3261 Protocol Buffers 3262 ~~~~~~~~~~~~~~~~ 3263 3264 The source language for Protocol Buffers is spelled `"protobuf"`. 3265 3266 Common Lisp 3267 ~~~~~~~~~~~ 3268 3269 The source language for Common Lisp is spelled "`lisp`".