└── readme.md


/readme.md:
--------------------------------------------------------------------------------
  1 | This document has tips for getting started using the language in its current beta version,
  2 | that aren't currently covered in the official distributed documentation.
  3 | The distributed README.txt and the core programs in the how_to/ folder should be read first!
  4 | 
  5 | Also check out the [Jai-Community-Library wiki](https://github.com/Jai-Community/Jai-Community-Library/wiki).
  6 | 
  7 | Last updated 2021-10-21
  8 | 
  9 | 
 10 | 
 11 | # Getting started info
 12 | 
 13 | ## Navigating and finding functionality
 14 | 
 15 | * Read the names of all the included modules in the distributed modules/ folder,
 16 | to get a sense of what's available.
 17 | 
 18 | * Check out this [Jai Awesome List](https://github.com/Jai-Community/awesome-jai)
 19 | which has community-made modules.
 20 | 
 21 | * Using grep-like tools to search the distributed code is a useful and common way to "get around"
 22 | and find what you're looking for in the language. Some examples:
 23 | 
 24 |     * If I want to find where the string-related functions are, I might search for "string_".
 25 |     * If I want to find some example usage of a certain module, function, or keyword, I might search for "#import "Module\_Name"" or "function\_name" or "keyword".
 26 |     * If I want to find the definition of a function, I might search for "function_name ::".
 27 | 
 28 | * These are some grep-like tools:
 29 | 
 30 |     * [ripgrep (Windows, Mac, Linux)](https://github.com/BurntSushi/ripgrep)
 31 |     * [BareGrep (Windows)](https://www.baremetalsoft.com/baregrep)
 32 | 
 33 | * These are modules I recommend looking at when starting out:
 34 | 
 35 |     * Basic
 36 |     * String
 37 |     * Hash_Table
 38 |     * Math
 39 |     * File
 40 |     * Compiler
 41 | 
 42 | ## Directory organization and custom modules
 43 | 
 44 | You can organize your directories however you like. One format some people use is:
 45 | 
 46 |     jai/
 47 |         jai/            - The distributed compiler folder. For compiler updates, just replace this folder.
 48 |             bin/
 49 |             examples/
 50 |             ...
 51 |         jai_modules/    - Downloaded modules and your own modules. Use the compiler's -import_dir command line flag for it to find your custom modules folder.
 52 |         my_project_1/
 53 |         my_project_2/
 54 |         ...
 55 | 
 56 | ## Debugging
 57 | 
 58 | You can use a debugger with an exe and the generated .pdb file.
 59 | For example, in Visual Studio, open the .exe file using File -> Open -> Projects/Solution, and you can set breakpoints and run.
 60 | 
 61 | ## Crashes
 62 | 
 63 | If your program crashes, as of the time of this writing, the program will stop
 64 | and nothing will be printed out. This can be confusing!
 65 | You can use the Debug module to print the stack trace on crashes:
 66 | 
 67 |     Debug :: #import "Debug";
 68 | 
 69 |     main :: () {
 70 |         Debug.init();
 71 | 
 72 |         a := 0;
 73 |         b := 1 / a; // Cause a crash
 74 | 
 75 |         write_string("done\n"); // The execution will not reach this point
 76 |     }
 77 | 
 78 | ## Pointer operators
 79 | 
 80 |     a: int;
 81 |     b: *int = *a; // address-of
 82 |     c: int = <<b; // dereference
 83 | 
 84 | 
 85 | 
 86 | # Non getting started info
 87 | 
 88 | The following information is misc. things not covered in the documentation currently,
 89 | but is also not especially useful when getting started with the language.
 90 | 
 91 | ## Auto-cast
 92 | 
 93 | The xx operator (syntax may be changed) is a shortcut to auto-cast to the required type.
 94 | 
 95 |     a: s64;
 96 |     b: s32 = xx a;
 97 | 
 98 | ## Uninitialized variable
 99 | 
100 |     a: Vector3 = ---; // This variable will be uninitialized
101 | 
102 | ## Anonymous structs
103 | 
104 | This can be a useful grouping for data that only has one copy:
105 | 
106 |     state: struct {
107 |         a, b: int;
108 |     };
109 |     some_function :: () {
110 |         state.a = 4;
111 |     }
112 | 
113 | ## Anonymous enum
114 | This can be useful for an enum that only has one copy:
115 | 
116 |     state: enum {
117 |         A;
118 |         B;
119 |     };
120 |     some_function :: () {
121 |         state = .B;
122 |     }
123 | 
124 | ## Struct "using base"
125 | 
126 | It can be useful for a struct to have a 'parent" struct as its first member,
127 | so that you can treat a pointer to one as a pointer to its parent.
128 | This is also described in the types how\_to.
129 | 
130 |     Entity :: struct {
131 |         type: Type;
132 |         x, y: float;
133 |     }
134 | 
135 |     Player :: struct {
136 |         using #as base: Entity;
137 |         player_index: int;
138 |     }
139 | 
140 |     entities: [..]*Entity;
141 |     p := New(Player);
142 |     p.type = Player;
143 |     p.player_index = 1;
144 |     array_add(*entities, p);
145 | 
146 |     for entities {
147 |         if it.type == Player {
148 |             player := cast(*Player) it;
149 |             print("%\n", p.player_index);
150 |         }
151 |     }
152 | 
153 | ## Compiler directives
154 | 
155 | This list is very rough, may miss some important ones, and descriptions are just rudimentary.
156 | The ones with descriptions are the ones I use / see used most commonly.
157 | Search the modules/ and examples/ folders for example usage.
158 | 
159 |     #add_context        Add a declaration to the context
160 |     #align
161 |     #assert
162 |     #bake
163 |     #c_call
164 |     #caller_location
165 |     #char               Character literal
166 |     #code
167 |     #compiler
168 |     #complete           Ensure an if-case satement checks all values of the enum
169 |     #define
170 |     #else
171 |     #endif
172 |     #expand
173 |     #file
174 |     #filepath           The directory of the running executable
175 |     #foreign
176 |     #foreign_library
177 |     #foreign_system_library
178 |     #if
179 |     #ifdef
180 |     #ifndef
181 |     #import             Import a module
182 |     #insert
183 |     #insert_internal
184 |     #intrinsic
185 |     #load               Load source code, as if it were placed right here (very commonly used)
186 |     #modify
187 |     #module_parameters
188 |     #must               Require a return value to be assigned to a variable
189 |     #no_abc
190 |     #no_alias
191 |     #no_padding
192 |     #place
193 |     #placeholder
194 |     #program_export
195 |     #run                Run this code right now (compile time)
196 |     #run_and_insert
197 |     #runtime_support
198 |     #scope_export       Set the scope for future declarations to be accessible by code that imports this module
199 |     #scope_file         Set the scope for foture declarations to just this file
200 |     #scope_module       Set the scope for foture declarations to just this module
201 |     #specified          Declare intention of maintaining enum values compatibility over time
202 |     #string             String literal with delimiter
203 |     #symmetric
204 |     #through
205 |     #type               Type literal, e.g. for function types
206 |     #type_info_none
207 |     #type_info_procedures_are_void_pointers
208 | 


--------------------------------------------------------------------------------