1 # Namespacing
   2 
   3 In order to work with C's namespace limitations, I've designed the following
   4 system, which makes use of a C language extension `-fdollars-in-identifiers`
   5 that lets you use dollar signs in identifiers. This extension is supported by
   6 GCC, TinyCC, and Clang.
   7 
   8 ## Unique File Suffixes
   9 
  10 Each file gets a unique suffix with the format `$<filename>_XXXXXXXX`, where the
  11 Xs are 8 randomly chosen identifier characters and `<filename>` includes only
  12 valid identifier characters up to the first period.
  13 
  14 For example, in a file called `hello-world.tm`, a variable like `foo` would
  15 become `foo$helloworld_VEDjfzDs`. This helps avoid namespace conflicts between
  16 two files that define the same symbol.
  17 
  18 ## Namespaces
  19 
  20 Dollar signs in identifiers provide a way to have compiled C code which segments
  21 its imports into different namespaces. For example `Foo$Baz` would be the
  22 identifier `Baz` in the namespace `Foo`, and would be guaranteed to not collide
  23 with a user-chosen name like `FooBaz` or `Foo_Baz`.
  24 
  25 ## Example
  26 
  27 For this Tomo code:
  28 
  29 ```tomo
  30 // File: foo.tm
  31 my_var := 123
  32 
  33 struct Baz(x:Int)
  34     member := 5
  35     func frob(b:Baz -> Int)
  36         return b.x
  37 
  38 func main() pass
  39 ```
  40 
  41 The generated C source code will look like this:
  42 
  43 ```C
  44 // File: .build/foo.tm.h
  45 ...
  46 typedef struct Baz$$struct$foo_VEDjfzDs Baz$$type$foo_VEDjfzDs;
  47 struct Baz$$struct$foo_VEDjfzDs {
  48     Int_t x;
  49 };
  50 DEFINE_OPTIONAL_TYPE(struct Baz$$struct$foo_VEDjfzDs, 8,$OptionalBaz$$type$foo_VEDjfzDs);
  51 extern const TypeInfo_t Baz$$info$foo_VEDjfzDs;
  52 extern Int_t Baz$member$foo_VEDjfzDs;
  53 Int_t Baz$frob$foo_VEDjfzDs(struct Baz$$struct$foo_VEDjfzDs _$b);
  54 extern Int_t my_var$foo_VEDjfzDs;
  55 void main$foo_VEDjfzDs();
  56 ...
  57 ```
  58 
  59 ```C
  60 // File: .build/foo.tm.c
  61 ...
  62 public Int_t my_var$foo_VEDjfzDs = I_small(123);
  63 public const TypeInfo_t Baz$$info$foo_VEDjfzDs = {...};
  64 public Int_t Baz$member$foo_VEDjfzDs = I_small(5);
  65 
  66 public Int_t Baz$frob$foo_VEDjfzDs(struct Baz$$struct$foo_VEDjfzDs _$b) {
  67     return (_$b).x;
  68 }
  69 
  70 public void main$foo_VEDjfzDs() {
  71 }
  72 ...
  73 ```