/* To search for a function, type or string library function, search for: doc_ If you want to search for an exact match just add a space at the end. In addition you can search for: doc_functions doc_types doc_strings doc_lexer to jump to those parts of the documentation. */ /* 4cpp Lexing Library Table of Contents 1 Introduction 2 4coder Systems 3 Types and Functions 4 String Library 5 Lexer Library 1 Introduction This is the documentation for alpha 4.0.11 The documentation is still under construction so some of the links are linking to sections that have not been written yet. What is here should be correct and I suspect useful even without some of the other sections. If you have questions or discover errors please contact editor@4coder.net or to get help from community members you can post on the 4coder forums hosted on handmade.network at 4coder.handmade.network 2 4coder Systems Coming Soon 3 Types and Functions 3.1 Function List exec_command exec_system_command clipboard_post clipboard_count clipboard_index get_buffer_count get_buffer_first get_buffer_next get_buffer get_buffer_by_name buffer_read_range buffer_replace_range buffer_compute_cursor buffer_batch_edit buffer_set_setting buffer_token_count buffer_read_tokens buffer_get_token_index create_buffer save_buffer kill_buffer get_view_first get_view_next get_view get_active_view open_view close_view set_active_view view_set_setting view_set_split_proportion view_compute_cursor view_set_cursor view_set_scroll view_set_mark view_set_highlight view_set_buffer view_post_fade get_user_input get_command_input get_mouse_state start_query_bar end_query_bar print_message change_theme change_font buffer_set_font set_theme_colors get_theme_colors directory_get_hot get_file_list free_file_list memory_allocate memory_set_protection memory_free file_exists directory_cd get_4ed_path show_mouse_cursor toggle_fullscreen is_fullscreen send_exit_signal 3.2 Type List bool32 int_color Key_Code Buffer_ID View_ID Key_Modifier Key_Modifier_Flag Command_ID Memory_Protect_Flags User_Input_Type_ID Event_Message_Type_ID Buffer_Setting_ID View_Setting_ID Buffer_Create_Flag Buffer_Kill_Flag Access_Flag Dirty_State Seek_Boundary_Flag Command_Line_Interface_Flag Auto_Indent_Flag Set_Buffer_Flag Input_Type_Flag Mouse_Cursor_Show_Type Buffer_Seek_Type View_Split_Position Generic_Command Key_Event_Data Mouse_State Range File_Info File_List Buffer_Identifier GUI_Scroll_Vars Full_Cursor Partial_Cursor Buffer_Seek Buffer_Edit Buffer_Summary View_Summary User_Input Query_Bar Event_Message Theme_Color Buffer_Batch_Edit_Type Buffer_Batch_Edit 3.3 Function Descriptions */ /* doc_functions */ /* doc_exec_command */ bool32 app->exec_command( Application_Links *app, Command_ID command_id ) /* Parameters command_id The command_id parameter specifies which internal command to execute. Return This call returns non-zero if command_id named a valid internal command. Description A call to exec_command executes an internal command. If command_id is invalid a warning is posted to *messages*. See Also Command_ID */ /* doc_exec_system_command */ bool32 app->exec_system_command( Application_Links *app, View_Summary *view, Buffer_Identifier buffer, char *path, int32_t path_len, char *command, int32_t command_len, Command_Line_Interface_Flag flags ) /* Parameters view If the view parameter is non-null it specifies a view to display the command's output buffer. buffer The buffer the command will output to is specified by the buffer parameter. See Buffer_Identifier for information on how this type specifies a buffer. path The path parameter specifies the path in which the command shall be executed. The string need not be null terminated. path_len The parameter path_len specifies the length of the path string. command The command parameter specifies the command that shall be executed. The string need not be null terminated. command_len The parameter command_len specifies the length of the command string. flags Flags for the behavior of the call are specified in the flags parameter. Return This call returns non-zero on success. Description A call to exec_system_command executes a command as if called from the command line, and sends the output to a buffer. The buffer identifier can either name a new buffer that does not exist, name a buffer that does exist, or provide the id of a buffer that does exist. If the buffer is not already in an open view and the view parameter is not NULL, then the provided view will display the output buffer. If the view parameter is NULL, no view will switch to the output. See Also Buffer_Identifier Command_Line_Input_Flag */ /* doc_clipboard_post */ void app->clipboard_post( Application_Links *app, int32_t clipboard_id, char *str, int32_t len ) /* Parameters clipboard_id This parameter is set up to prepare for future features, it should always be 0 for now. str The str parameter specifies the string to be posted to the clipboard, it need not be null terminated. len The len parameter specifies the length of the str string. Description Stores the string str in the clipboard initially with index 0. Also reports the copy to the operating system, so that it may be pasted into other applications. See Also The_4coder_Clipboard */ /* doc_clipboard_count */ int32_t app->clipboard_count( Application_Links *app, int32_t clipboard_id ) /* Parameters clipboard_id This parameter is set up to prepare for future features, it should always be 0 for now. Description This call returns the number of items in the clipboard. See Also The_4coder_Clipboard */ /* doc_clipboard_index */ int32_t app->clipboard_index( Application_Links *app, int32_t clipboard_id, int32_t item_index, char *out, int32_t len ) /* Parameters clipboard_id This parameter is set up to prepare for future features, it should always be 0 for now. item_index This parameter specifies which item to read, 0 is the most recent copy, 1 is the second most recent copy, etc. out This parameter provides a buffer where the clipboard contents are written. This parameter may be NULL. len This parameter specifies the length of the out buffer. Return This call returns the size of the item associated with item_index. Description This function always returns the size of the item even if the output buffer is NULL. If the output buffer is too small to contain the whole string, it is filled with the first len character of the clipboard contents. The output string is not null terminated. See Also The_4coder_Clipboard */ /* doc_get_buffer_count */ int32_t app->get_buffer_count( Application_Links *app ) /* Description TODO */ /* doc_get_buffer_first */ Buffer_Summary app->get_buffer_first( Application_Links *app, Access_Flag access ) /* Parameters access The access parameter determines what levels of protection this call can access. Return This call returns the summary of the first buffer in a buffer loop. Description This call begins a loop across all the buffers. If the buffer returned does not exist, the loop is finished. Buffers should not be killed durring a buffer loop. See Also Buffer_Summary Access_Flag get_buffer_next */ /* doc_get_buffer_next */ void app->get_buffer_next( Application_Links *app, Buffer_Summary *buffer, Access_Flag access ) /* Parameters buffer The Buffer_Summary pointed to by buffer is iterated to the next buffer or to a null summary if this is the last buffer. access The access parameter determines what levels of protection this call can access. The buffer outputted will be the next buffer that is accessible. Description This call steps a Buffer_Summary to the next buffer in the global buffer order. The global buffer order is kept roughly in the order of most recently used to least recently used. If the buffer outputted does not exist, the loop is finished. Buffers should not be killed or created durring a buffer loop. See Also Buffer_Summary Access_Flag get_buffer_first */ /* doc_get_buffer */ Buffer_Summary app->get_buffer( Application_Links *app, Buffer_ID buffer_id, Access_Flag access ) /* Parameters buffer_id The parameter buffer_id specifies which buffer to try to get. access The access parameter determines what levels of protection this call can access. Return This call returns a summary that describes the indicated buffer if it exists and is accessible. See Also Buffer_Summary Access_Flag Buffer_ID */ /* doc_get_buffer_by_name */ Buffer_Summary app->get_buffer_by_name( Application_Links *app, char *name, int32_t len, Access_Flag access ) /* Parameters name The name parameter specifies the buffer name to try to get. The string need not be null terminated. len The len parameter specifies the length of the name string. access The access parameter determines what levels of protection this call can access. Return This call returns a summary that describes the indicated buffer if it exists and is accessible. See Also Buffer_Summary Access_Flag */ /* doc_buffer_read_range */ bool32 app->buffer_read_range( Application_Links *app, Buffer_Summary *buffer, int32_t start, int32_t end, char *out ) /* Parameters buffer This parameter specifies the buffer to read. start This parameter specifies absolute position of the first character in the read range. end This parameter specifies the absolute position of the the character one past the end of the read range. out This paramter provides the output character buffer to fill with the result of the read. Return This call returns non-zero if the read succeeds. Description The output buffer must have a capacity of at least (end - start). The output is not null terminated. This call fails if the buffer does not exist, or if the read range is not within the bounds of the buffer. See Also 4coder_Buffer_Positioning_System */ /* doc_buffer_replace_range */ bool32 app->buffer_replace_range( Application_Links *app, Buffer_Summary *buffer, int32_t start, int32_t end, char *str, int32_t len ) /* Parameters buffer This parameter specifies the buffer to edit. start This parameter specifies absolute position of the first character in the replace range. end This parameter specifies the absolute position of the the character one past the end of the replace range. str This parameter specifies the the string to write into the range; it need not be null terminated. len This parameter specifies the length of the str string. Return This call returns non-zero if the replacement succeeds. Description If this call succeeds it deletes the range from start to end and writes str in the same position. If end == start then this call is equivalent to inserting the string at start. If len == 0 this call is equivalent to deleteing the range from start to end. This call fails if the buffer does not exist, or if the replace range is not within the bounds of the buffer. See Also 4coder_Buffer_Positioning_System */ /* doc_buffer_compute_cursor */ bool32 app->buffer_compute_cursor( Application_Links *app, Buffer_Summary *buffer, Buffer_Seek seek, Partial_Cursor *cursor_out ) /* Parameters buffer The buffer parameter specifies the buffer on which to run the cursor computation. seek The seek parameter specifies the target position for the seek. cursor_out On success this struct is filled with the result of the seek. Return This call returns non-zero on success. This call can fail if the buffer summary provided does not summarize an actual buffer in 4coder, or if the provided seek format is invalid. The valid seek types are seek_pos and seek_line_char. Description Computes a Partial_Cursor for the given seek position with no side effects. The seek position must be one of the types supported by Partial_Cursor. Those types are absolute position and line,column position. See Also Buffer_Seek Partial_Cursor */ /* doc_buffer_batch_edit */ bool32 app->buffer_batch_edit( Application_Links *app, Buffer_Summary *buffer, char *str, int32_t str_len, Buffer_Edit *edits, int32_t edit_count, Buffer_Batch_Edit_Type type ) /* Parameters str This parameter provides all of the source string for the edits in the batch. str_len This parameter specifies the length of the str string. edits This parameter provides about the source string and destination range of each edit as an array. edit_count This parameter specifies the number of Buffer_Edit structs in edits. type This prameter specifies what type of batch edit to execute. Return This call returns non-zero if the batch edit succeeds. This call can fail if the provided buffer summary does not refer to an actual buffer in 4coder. Description TODO See Also Buffer_Edit Buffer_Batch_Edit_Type */ /* doc_buffer_set_setting */ bool32 app->buffer_set_setting( Application_Links *app, Buffer_Summary *buffer, Buffer_Setting_ID setting, int32_t value ) /* Parameters buffer The buffer parameter specifies the buffer on which to set a setting. setting The setting parameter identifies the setting that shall be changed. value The value parameter specifies the value to which the setting shall be changed. See Also Buffer_Setting_ID */ /* doc_buffer_token_count */ int32_t app->buffer_token_count( Application_Links *app, Buffer_Summary *buffer ) /* Parameters buffer Specifies the buffer from which to read the token count. Return If tokens are available for the buffer, the number of tokens on the buffer is returned. If the buffer does not exist or if it is not a lexed buffer, the return is zero. */ /* doc_buffer_read_tokens */ bool32 app->buffer_read_tokens( Application_Links *app, Buffer_Summary *buffer, int32_t start_token, int32_t end_token, Cpp_Token *tokens_out ) /* Parameters buffer Specifies the buffer from which to read tokens. first_token Specifies the index of the first token to read. end_token Specifies the token to stop reading at. tokens_out The memory that will store the tokens read from the buffer. Return Returns non-zero on success. This call can fail if the buffer doesn't exist or doesn't have tokens ready, or if either the first or last index is out of bounds. Description Puts the data for the tokens with the indices [first_token,last_token */ /* doc_buffer_get_token_index */ bool32 app->buffer_get_token_index( Application_Links *app, Buffer_Summary *buffer, int32_t pos, Cpp_Get_Token_Result *get_result ) /* Parameters buffer The buffer from which to get a token. pos The position in the buffer in absolute coordinates. get_result The output struct specifying which token contains pos. Return Returns non-zero on success. This call can fail if the buffer doesn't exist, or if the buffer doesn't have tokens ready. Description This call finds the token that contains a particular position, or if the position is in between tokens it finds the index of the token to the left of the position. See Also Cpp_Get_Token_Result cpp_get_token */ /* doc_create_buffer */ Buffer_Summary app->create_buffer( Application_Links *app, char *filename, int32_t filename_len, Buffer_Create_Flag flags ) /* Parameters filename The filename parameter specifies the name of the file to be opened or created; it need not be null terminated. filename_len The filename_len parameter spcifies the length of the filename string. flags The flags parameter specifies behaviors for buffer creation. Return This call returns the summary of the created buffer. Description Tries to create a new buffer and associate it to the given filename. If such a buffer already exists the existing buffer is returned in the Buffer_Summary and no new buffer is created. If the buffer does not exist a new buffer is created and named after the given filename. If the filename corresponds to a file on the disk that file is loaded and put into buffer, if the filename does not correspond to a file on disk the buffer is created empty. See Also Buffer_Summary Buffer_Create_Flag */ /* doc_save_buffer */ bool32 app->save_buffer( Application_Links *app, Buffer_Summary *buffer, char *filename, int32_t filename_len, uint32_t flags ) /* Parameters buffer The buffer parameter specifies the buffer to save to a file. filename The filename parameter specifies the name of the file to associated to the buffer; it need not be null terminated. filename_len The filename_len parameter specifies the length of the filename string. flags This parameter is not currently used and should be set to 0 for now. Return This call returns non-zero on success. */ /* doc_kill_buffer */ bool32 app->kill_buffer( Application_Links *app, Buffer_Identifier buffer, View_ID view_id, Buffer_Kill_Flag flags ) /* Parameters buffer The buffer parameter specifies the buffer to try to kill. view_id The view_id parameter specifies the view that will contain the "are you sure" dialogue if the buffer is dirty. flags The flags parameter specifies behaviors for the buffer kill. Return This call returns non-zero if the buffer is killed. Description Tries to kill the idenfied buffer. If the buffer is dirty and the "are you sure" dialogue needs to be displayed the provided view is used to show the dialogue. If the view is not open the kill fails. See Also Buffer_Kill_Flag Buffer_Identifier */ /* doc_get_view_first */ View_Summary app->get_view_first( Application_Links *app, Access_Flag access ) /* Parameters access The access parameter determines what levels of protection this call can access. Return This call returns the summary of the first view in a view loop. Description This call begins a loop across all the open views. If the View_Summary returned is a null summary, the loop is finished. Views should not be closed or opened durring a view loop. See Also Access_Flag get_view_next */ /* doc_get_view_next */ void app->get_view_next( Application_Links *app, View_Summary *view, Access_Flag access ) /* Parameters view The View_Summary pointed to by view is iterated to the next view or to a null summary if this is the last view. access The access parameter determines what levels of protection this call can access. The view outputted will be the next view that is accessible. Description This call steps a View_Summary to the next view in the global view order. If the view outputted does not exist, the loop is finished. Views should not be closed or opened durring a view loop. See Also Access_Flag get_view_first */ /* doc_get_view */ View_Summary app->get_view( Application_Links *app, View_ID view_id, Access_Flag access ) /* Parameters view_id The view_id specifies the view to try to get. access The access parameter determines what levels of protection this call can access. Return This call returns a summary that describes the indicated view if it is open and accessible. See Also Access_Flag */ /* doc_get_active_view */ View_Summary app->get_active_view( Application_Links *app, Access_Flag access ) /* Parameters access The access parameter determines what levels of protection this call can access. Return This call returns a summary that describes the active view. See Also set_active_view Access_Flag */ /* doc_open_view */ View_Summary app->open_view( Application_Links *app, View_Summary *view_location, View_Split_Position position ) /* Parameters view_location The view_location parameter specifies the view to split to open the new view. position The position parameter specifies how to split the view and where to place the new view. Return If this call succeeds it returns a View_Summary describing the newly created view, if it fails it returns a null summary. Description 4coder is built with a limit of 16 views. If 16 views are already open when this is called the call will fail. See Also View_Split_Position */ /* doc_close_view */ bool32 app->close_view( Application_Links *app, View_Summary *view ) /* Parameters view The view parameter specifies which view to close. Return This call returns non-zero on success. Description If the given view is open and is not the last view, it will be closed. If the given view is the active view, the next active view in the global order of view will be made active. If the given view is the last open view in the system, the call will fail. */ /* doc_set_active_view */ bool32 app->set_active_view( Application_Links *app, View_Summary *view ) /* Parameters view The view parameter specifies which view to make active. Return This call returns non-zero on success. Description If the given view is open, it is set as the active view, and takes subsequent commands and is returned from get_active_view. See Also get_active_view */ /* doc_view_set_setting */ bool32 app->view_set_setting( Application_Links *app, View_Summary *view, View_Setting_ID setting, int32_t value ) /* Parameters view The view parameter specifies the view on which to set a setting. setting The setting parameter identifies the setting that shall be changed. value The value parameter specifies the value to which the setting shall be changed. Return This call returns non-zero on success. See Also View_Setting_ID */ /* doc_view_set_split_proportion */ bool32 app->view_set_split_proportion( Application_Links *app, View_Summary *view, float t ) /* Parameters view The view parameter specifies which view shall have it's size adjusted. t The t parameter specifies the proportion of the containing box that the view should occupy. t should be in [0,1]. Return This call returns non-zero on success. */ /* doc_view_compute_cursor */ bool32 app->view_compute_cursor( Application_Links *app, View_Summary *view, Buffer_Seek seek, Full_Cursor *cursor_out ) /* Parameters view The view parameter specifies the view on which to run the cursor computation. seek The seek parameter specifies the target position for the seek. cursor_out On success this struct is filled with the result of the seek. Return This call returns non-zero on success. Description Computes a Full_Cursor for the given seek position with no side effects. See Also Buffer_Seek Full_Cursor */ /* doc_view_set_cursor */ bool32 app->view_set_cursor( Application_Links *app, View_Summary *view, Buffer_Seek seek, bool32 set_preferred_x ) /* Parameters view The view parameter specifies the view in which to set the cursor. seek The seek parameter specifies the target position for the seek. set_preferred_x If this parameter is true the preferred x is updated to match the new cursor x. Return This call returns non-zero on success. Description This call sets the the view's cursor position. set_preferred_x should usually be true unless the change in cursor position is is a vertical motion that tries to keep the cursor in the same column or x position. See Also Buffer_Seek */ /* doc_view_set_scroll */ bool32 app->view_set_scroll( Application_Links *app, View_Summary *view, GUI_Scroll_Vars scroll ) /* Description TODO See Also GUI_Scroll_Vars */ /* doc_view_set_mark */ bool32 app->view_set_mark( Application_Links *app, View_Summary *view, Buffer_Seek seek ) /* Parameters view The view parameter specifies the view in which to set the mark. seek The seek parameter specifies the target position for the seek. Return This call returns non-zero on success. Description This call sets the the view's mark position. See Also Buffer_Seek */ /* doc_view_set_highlight */ bool32 app->view_set_highlight( Application_Links *app, View_Summary *view, int32_t start, int32_t end, bool32 turn_on ) /* Parameters view The view parameter specifies the view in which to set the highlight. start This parameter specifies the absolute position of the first character of the highlight range. end This parameter specifies the absolute position of the character one past the end of the highlight range. turn_on This parameter indicates whether the highlight is being turned on or off. Return This call returns non-zero on success. Description The highlight is mutually exclusive to the cursor. When the turn_on parameter is set to true the highlight will be shown and the cursor will be hidden. After that either setting the cursor with view_set_cursor or calling view_set_highlight and the turn_on set to false, will switch back to showing the cursor. */ /* doc_view_set_buffer */ bool32 app->view_set_buffer( Application_Links *app, View_Summary *view, Buffer_ID buffer_id, Set_Buffer_Flag flags ) /* Parameters view The view parameter specifies the view in which to display the buffer. buffer_id The buffer_id parameter specifies which buffer to show in the view. flags The flags parameter specifies behaviors for setting the buffer. Return This call returns non-zero on success. Description On success view_set_buffer sets the specified view's current buffer and cancels and dialogue shown in the view and displays the file. See Also Set_Buffer_Flag */ /* doc_view_post_fade */ bool32 app->view_post_fade( Application_Links *app, View_Summary *view, float seconds, int32_t start, int32_t end, int_color color ) /* Parameters view The view parameter specifies the view onto which the fade effect shall be posted. seconds This parameter specifies the number of seconds the fade effect should last. start This parameter specifies the absolute position of the first character of the fade range. end This parameter specifies the absolute position of the character one past the end of the fdae range. color The color parameter specifies the initial color of the text before it fades to it's natural color. Return This call returns non-zero on success. See Also int_color */ /* doc_get_user_input */ User_Input app->get_user_input( Application_Links *app, Input_Type_Flag get_type, Input_Type_Flag abort_type ) /* Parameters get_type The get_type parameter specifies the set of input types that should be returned. abort_type The get_type parameter specifies the set of input types that should trigger an abort signal. Return This call returns a User_Input that describes a user input event. Description This call preempts the command. The command is resumed if either a get or abort condition is met, or if another command is executed. If either the abort condition is met or another command is executed an abort signal is returned. If an abort signal is ever returned the command should finish execution without any more calls that preempt the command. If a get condition is met the user input is returned. See Also Input_Type_Flag User_Input */ /* doc_get_command_input */ User_Input app->get_command_input( Application_Links *app ) /* Return This call returns the input that triggered the currently executing command. See Also User_Input */ /* doc_get_mouse_state */ Mouse_State app->get_mouse_state( Application_Links *app ) /* Return This call returns the current mouse state as of the beginning of the frame. See Also Mouse_State */ /* doc_start_query_bar */ bool32 app->start_query_bar( Application_Links *app, Query_Bar *bar, uint32_t flags ) /* Parameters bar This parameter provides a Query_Bar that should remain in valid memory until end_query_bar or the end of the command. It is commonly a good idea to make this a pointer to a Query_Bar stored on the stack. flags This parameter is not currently used and should be 0 for now. Return This call returns non-zero on success. Description This call tells the active view to begin displaying a "Query_Bar" which is a small GUI element that can overlap a buffer or other 4coder GUI. The contents of the bar can be changed after the call to start_query_bar and the query bar shown by 4coder will reflect the change. Since the bar stops showing when the command exits the only use for this call is in an interactive command that makes calls to get_user_input. */ /* doc_end_query_bar */ void app->end_query_bar( Application_Links *app, Query_Bar *bar, uint32_t flags ) /* Parameters bar This parameter should be a bar pointer of a currently active query bar. flags This parameter is not currently used and should be 0 for now. Description Stops showing the particular query bar specified by the bar parameter. */ /* doc_print_message */ void app->print_message( Application_Links *app, char *str, int32_t len ) /* Parameters str The str parameter specifies the string to post to *messages*; it need not be null terminated. len The len parameter specifies the length of the str string. Description This call posts a string to the *messages* buffer. */ /* doc_change_theme */ void app->change_theme( Application_Links *app, char *name, int32_t len ) /* Parameters name The name parameter specifies the name of the theme to begin using; it need not be null terminated. len The len parameter specifies the length of the name string. Description This call changes 4coder's color pallet to one of the built in themes. */ /* doc_change_font */ void app->change_font( Application_Links *app, char *name, int32_t len, bool32 apply_to_all_files ) /* Parameters name The name parameter specifies the name of the font to begin using; it need not be null terminated. len The len parameter specifies the length of the name string. apply_to_all_files If this is set all open files change to this font. Usually this should be true durring the start hook because several files already exist at that time. Description This call changes 4coder's default font to one of the built in fonts. */ /* doc_buffer_set_font */ void app->buffer_set_font( Application_Links *app, Buffer_Summary *buffer, char *name, int32_t len ) /* Parameters buffer This parameter the buffer that shall have it's font changed name The name parameter specifies the name of the font to begin using; it need not be null terminated. len The len parameter specifies the length of the name string. Description This call sets the display font of a particular buffer. */ /* doc_set_theme_colors */ void app->set_theme_colors( Application_Links *app, Theme_Color *colors, int32_t count ) /* Parameters colors The colors pointer provides an array of color structs pairing differet style tags to color codes. count The count parameter specifies the number of Theme_Color structs in the colors array. Description For each struct in the array, the slot in the main color pallet specified by the struct's tag is set to the color code in the struct. If the tag value is invalid no change is made to the color pallet. */ /* doc_get_theme_colors */ void app->get_theme_colors( Application_Links *app, Theme_Color *colors, int32_t count ) /* Parameters colors an array of color structs listing style tags to get color values for count the number of color structs in the colors array Description For each struct in the array, the color field of the struct is filled with the color from the slot in the main color pallet specified by the tag. If the tag value is invalid the color is filled with black. */ /* doc_directory_get_hot */ int32_t app->directory_get_hot( Application_Links *app, char *out, int32_t capacity ) /* Parameters out This parameter provides a character buffer that receives the 4coder 'hot directory'. capacity This parameter specifies the maximum size to be output to the out buffer. Return This call returns the size of the string written into the buffer. Description 4coder has a concept of a 'hot directory' which is the directory most recently accessed in the GUI. Whenever the GUI is opened it shows the hot directory. In the future this will be deprecated and eliminated in favor of more flexible directories controlled on the custom side. */ /* doc_get_file_list */ File_List app->get_file_list( Application_Links *app, char *dir, int32_t len ) /* Parameters dir This parameter specifies the directory whose files will be enumerated in the returned list; it need not be null terminated. len This parameter the length of the dir string. Return This call returns a File_List struct containing pointers to the names of the files in the specified directory. The File_List returned should be passed to free_file_list when it is no longer in use. */ /* doc_free_file_list */ void app->free_file_list( Application_Links *app, File_List list ) /* Parameters list This parameter provides the file list to be freed. Description After this call the file list passed in should not be read or written to. */ /* doc_memory_allocate */ void* app->memory_allocate( Application_Links *app, int32_t size ) /* Parameters size The size in bytes of the block that should be returned. Description This calls to a low level OS allocator which means it is best used for infrequent, large allocations. The size of the block must be remembered if it will be freed or if it's mem protection status will be changed. See Also memory_free */ /* doc_memory_set_protection */ bool32 app->memory_set_protection( Application_Links *app, void *ptr, int32_t size, Memory_Protect_Flags flags ) /* Parameters ptr The base of the block on which to set memory protection flags. size The size that was originally used to allocate this block. flags The new memory protection flags. Description This call sets the memory protection flags of a block of memory that was previously allocate by memory_allocate. See Also memory_allocate Memory_Protect_Flags */ /* doc_memory_free */ void app->memory_free( Application_Links *app, void *ptr, int32_t size ) /* Parameters mem The base of a block to free. size The size that was originally used to allocate this block. Description This call frees a block of memory that was previously allocated by memory_allocate. See Also memory_allocate */ /* doc_file_exists */ bool32 app->file_exists( Application_Links *app, char *filename, int32_t len ) /* Parameters filename This parameter specifies the full path to a file; it need not be null terminated. len This parameter specifies the length of the filename string. Return This call returns non-zero if and only if the file exists. */ /* doc_directory_cd */ bool32 app->directory_cd( Application_Links *app, char *dir, int32_t *len, int32_t capacity, char *rel_path, int32_t rel_len ) /* Parameters dir This parameter provides a character buffer that stores a directory; it need not be null terminated. len This parameter specifies the length of the dir string. capacity This parameter specifies the maximum size of the dir string. rel_path This parameter specifies the path to change to, may include '.' or '..'; it need not be null terminated. rel_len This parameter specifies the length of the rel_path string. Return This call returns non-zero if the call succeeds. Description This call succeeds if the new directory exists and the it fits inside the dir buffer. If the call succeeds the dir buffer is filled with the new directory and len is overwritten with the length of the new string in the buffer. For instance if dir contains "C:/Users/MySelf" and rel is "Documents" the buffer will contain "C:/Users/MySelf/Documents" and len will contain the length of that string. This call can also be used with rel set to ".." to traverse to parent folders. */ /* doc_get_4ed_path */ bool32 app->get_4ed_path( Application_Links *app, char *out, int32_t capacity ) /* Parameters out This parameter provides a character buffer that receives the path to the 4ed executable file. capacity This parameter specifies the maximum capacity of the out buffer. Return This call returns non-zero on success. */ /* doc_show_mouse_cursor */ void app->show_mouse_cursor( Application_Links *app, Mouse_Cursor_Show_Type show ) /* Parameters show This parameter specifies the new state of the mouse cursor. See Also Mouse_Cursor_Show_Type */ /* doc_toggle_fullscreen */ void app->toggle_fullscreen( Application_Links *app ) /* Description This call tells 4coder to switch into or out of full screen mode. The changes of full screen mode do not take effect until the end of the current frame. On Windows this call will not work unless 4coder was started in "stream mode". Stream mode can be enabled with -S or -F flags on the command line to 4ed. */ /* doc_is_fullscreen */ bool32 app->is_fullscreen( Application_Links *app ) /* Description This call returns true if the 4coder is in full screen mode. This call takes toggles that have already occured this frame into account. So it may return true even though the frame has not ended and actually put 4coder into full screen. If it returns true though, 4coder will definitely be full screen by the beginning of the next frame if the state is not changed. */ /* doc_send_exit_signal */ void app->send_exit_signal( Application_Links *app ) /* Description This call sends a signal to 4coder to attempt to exit. If there are unsaved files this triggers a dialogue ensuring you're okay with closing. */ /* 3.4 Type Descriptions */ /* doc_types */ /* doc_bool32 */ typedef int32_t bool32; /* Description bool32 is an alias name to signal that an integer parameter or field is for true/false vales. */ /* doc_int_color */ typedef uint32_t int_color; /* Description int_color is an alias name to signal that an integer parameter or field is for a color value, colors are specified as 24 bit integers in 3 channels: 0xRRGGBB. */ /* doc_Key_Code */ typedef unsigned char Key_Code; /* Description Key_Code is the alias for key codes including raw codes and codes translated to textual input that takes modifiers into account. */ /* doc_Buffer_ID */ typedef int32_t Buffer_ID; /* Description Buffer_ID is used to name a 4coder buffer. Each buffer has a unique id but when a buffer is closed it's id may be recycled by future, different buffers. */ /* doc_View_ID */ typedef int32_t View_ID; /* Description View_ID is used to name a 4coder view. Each view has a unique id in the interval [1,16]. */ /* doc_Key_Modifier */ enum Key_Modifier; /* Description A Key_Modifier acts as an index for specifying modifiers in arrays. Values MDFR_SHIFT_INDEX MDFR_CONTROL_INDEX MDFR_ALT_INDEX MDFR_CAPS_INDEX MDFR_HOLD_INDEX MDFR_INDEX_COUNT MDFR_INDEX_COUNT is used to specify the number of modifiers supported. */ /* doc_Key_Modifier_Flag */ enum Key_Modifier_Flag; /* Description A Key_Modifier_Flag field is used to specify a specific state of modifiers. Flags can be combined with bit or to specify a state with multiple modifiers. Values MDFR_NONE = 0x0 MDFR_NONE specifies that no modifiers are pressed. MDFR_CTRL = 0x1 MDFR_ALT = 0x2 MDFR_SHIFT = 0x4 */ /* doc_Command_ID */ enum Command_ID; /* Description A Command_ID is used as a name for commands implemented internally in 4coder. Values cmdid_null cmdid_null is set aside to always be zero and is not associated with any command. cmdid_undo cmdid_undo performs a standard undo behavior. cmdid_redo cmdid_redo reperforms an edit that was undone. cmdid_history_backward cmdid_history_backward performs a step backwards through the file history, which includes previously lost redo branches. cmdid_history_forward cmdid_history_forward unperforms the previous cmdid_history_backward step if possib.e cmdid_interactive_new cmdid_interactive_new begins an interactive dialogue to create a new buffer. cmdid_interactive_open cmdid_interactive_open begins an interactive dialogue to open a file into a buffer. cmdid_save_as cmdid_save_as does not currently work and is likely to be removed rather that fixed. cmdid_interactive_switch_buffer cmdid_interactive_switch_buffer begins an interactive dialogue to choose an open buffer to swap into the active view. cmdid_interactive_kill_buffer cmdid_interactive_kill_buffer begins an interactive dialogue to choose an open buffer to kill. cmdid_reopen cmdid_reopen reloads the active buffer's associated file and discards the old buffer contents for the reloaded file. cmdid_save cmdid_save saves the buffer's contents into the associated file. cmdid_kill_buffer cmdid_kill_buffer tries to kill the active buffer. cmdid_open_color_tweaker cmdid_open_color_tweaker opens the theme editing GUI. cmdid_open_config cmdid_open_config opens the configuration menu. cmdid_open_menu cmdid_open_menu opens the top level menu. cmdid_open_debug cmdid_open_debug opens the debug information viewer mode. cmdid_count */ /* doc_Memory_Protect_Flags */ enum Memory_Protect_Flags; /* Description TODO Values MemProtect_Read = 0x1 TODO MemProtect_Write = 0x2 TODO MemProtect_Execute = 0x4 TODO */ /* doc_User_Input_Type_ID */ enum User_Input_Type_ID; /* Description User_Input_Type_ID specifies a type of user input event. Values UserInputNone UserInputNone indicates that no event has occurred. UserInputKey UserInputKey indicates an event which can be described by a Key_Event_Data struct. UserInputMouse UserInputMouse indicates an event which can be described by a Mouse_State struct. */ /* doc_Event_Message_Type_ID */ enum Event_Message_Type_ID; /* Description Event_Message_Type_ID is a part of an unfinished feature. Values EventMessage_NoMessage TODO. EventMessage_OpenView TODO. EventMessage_Frame TODO. EventMessage_CloseView TODO. */ /* doc_Buffer_Setting_ID */ enum Buffer_Setting_ID; /* Description A Buffer_Setting_ID names a setting in a buffer. Values BufferSetting_Null BufferSetting_Null is not a valid setting, it is reserved to detect errors. BufferSetting_Lex The BufferSetting_Lex setting is used to determine whether to store C++ tokens from with the buffer. BufferSetting_WrapLine The BufferSetting_WrapLine setting is used to determine whether a buffer prefers to be viewed with wrapped lines, individual views can be set to override this value after being tied to the buffer. BufferSetting_MapID The BufferSetting_MapID setting specifies the id of the command map that should be active when a buffer is active. BufferSetting_Eol The BufferSetting_Eol setting specifies how line ends should be saved to the backing file. A 1 indicates dos endings "\r\n" and a 0 indicates nix endings "\n". BufferSetting_Unimportant The BufferSetting_Unimportant setting marks a buffer so that it's dirty state will be completely ignored. This means the "dirty" star is hidden and the buffer can be closed without presenting an "are you sure" dialogue screen. BufferSetting_ReadOnly The BufferSetting_ReadOnly setting marks a buffer so that it can only be returned from buffer access calls that include an AccessProtected flag. */ /* doc_View_Setting_ID */ enum View_Setting_ID; /* Description A View_Setting_ID names a setting in a view. Values ViewSetting_Null ViewSetting_Null is not a valid setting, it is reserved to detect errors. ViewSetting_WrapLine The ViewSetting_WrapLine setting determines whether the view applies line wrapping at the border of the panel for long lines. Whenever the view switches to a new buffer it will reset this setting to match the 'preferred' line wrapping setting of the buffer. ViewSetting_ShowWhitespace The ViewSetting_ShowWhitespace setting determines whether the view highlights whitespace in a file. Whenever the view switches to a new buffer this setting is turned off. ViewSetting_ShowScrollbar The ViewSetting_ShowScrollbar setting determines whether a scroll bar is attached to a view in it's scrollable section. */ /* doc_Buffer_Create_Flag */ enum Buffer_Create_Flag; /* Description A Buffer_Create_Flag field specifies how a buffer should be created. Values BufferCreate_Background = 0x1 BufferCreate_Background is not currently implemented. BufferCreate_AlwaysNew = 0x2 When BufferCreate_AlwaysNew is set it indicates the buffer should be cleared to empty even if it's associated file already has content. BufferCreate_NeverNew = 0x4 When BufferCreate_NeverNew is set it indicates that the buffer should only be created if it is an existing file or if a buffer with the given name is already open. */ /* doc_Buffer_Kill_Flag */ enum Buffer_Kill_Flag; /* Description A Buffer_Kill_Flag field specifies how a buffer should be killed. Values BufferKill_Background = 0x1 BufferKill_Background is not currently implemented. BufferKill_AlwaysKill = 0x2 When BufferKill_AlwaysKill is set it indicates the buffer should be killed without asking, even when the buffer is dirty. */ /* doc_Access_Flag */ enum Access_Flag; /* Description An Access_Flag field specifies what sort of permission you grant to an access call. An access call is usually one the returns a summary struct. If a 4coder object has a particular protection flag set and the corresponding bit is not set in the access field, that 4coder object is hidden. On the other hand if a protection flag is set in the access parameter and the object does not have that protection flag, the object is still returned from the access call. Values AccessOpen = 0x0 AccessOpen does not include any bits, it indicates that the access should only return objects that have no protection flags set. AccessProtected = 0x1 AccessProtected is set on buffers and views that are "read only" such as the output from an app->exec_system_command call such as *build*. This is to prevent the user from accidentally editing output that they might prefer to keep in tact. AccessHidden = 0x2 AccessHidden is set on any view that is not currently showing it's file, for instance because it is navigating the file system to open a file. AccessAll = 0xFF AccessAll is a catchall access for cases where an access call should always return an object no matter what it's protection flags are. */ /* doc_Dirty_State */ enum Dirty_State; /* Description A Dirty_State value describes whether changes have been made to a buffer or to an underlying file since the last sync time between the two. Saving a buffer to it's file or loading the buffer from the file both act as sync points. Values DirtyState_UpToDate = 0 DirtyState_UpToDate indicates that there are no unsaved changes and the underlying system file still agrees with the buffer's state. DirtyState_UnsavedChanges = 1 DirtyState_UnsavedChanges indicates that there have been changes in the buffer since the last sync point. DirtyState_UnloadedChanges = 2 DirtyState_UnsavedChanges indicates that the underlying file has been edited since the last sync point with the buffer. */ /* doc_Seek_Boundary_Flag */ enum Seek_Boundary_Flag; /* Description A Seek_Boundary_Flag field specifies a set of "boundary" types used in seeks for the beginning or end of different types of words. Values BoundaryWhitespace = 0x1 BoundaryToken = 0x2 BoundaryAlphanumeric = 0x4 BoundaryCamelCase = 0x8 */ /* doc_Command_Line_Interface_Flag */ enum Command_Line_Interface_Flag; /* Description A Command_Line_Interface_Flag field specifies the behavior of a call to a command line interface. Values CLI_OverlapWithConflict = 0x1 If CLI_OverlapWithConflict is set if output buffer of the new command is already in use by another command which is still executing, the older command relinquishes control of the buffer and both operate simultaneously with only the newer command outputting to the buffer. CLI_AlwaysBindToView = 0x2 If CLI_AlwaysBindToView is set the output buffer will always be set in the active view even if it is already set in another open view. CLI_CursorAtEnd = 0x4 If CLI_CursorAtEnd is set the cursor will be kept at the end of the output buffer, otherwise the cursor is kept at the beginning. */ /* doc_Auto_Indent_Flag */ enum Auto_Indent_Flag; /* Description An Auto_Indent_Flag field specifies the behavior of an auto indentation operation. Values AutoIndent_ClearLine = 0x1 If AutoIndent_ClearLine is set, then any line that is only whitespace will be cleared to contain nothing at all. otherwise the line is filled with whitespace to match the nearby indentation. AutoIndent_UseTab = 0x2 If AutoIndent_UseTab is set, then when putting in leading whitespace to align code, as many tabs will be used as possible until the fine grained control of spaces is needed to finish the alignment. AutoIndent_ExactAlignBlock = 0x4 If AutoIndent_ExactAlignBlock is set, then block comments are indented by putting the first non-whitespace character of the line in line with the beginning of the comment. AutoIndent_FullTokens = 0x8 If AutoIndent_FullTokens is set, then the set of lines that are indented is automatically expanded so that any token spanning multiple lines gets entirely indented. */ /* doc_Set_Buffer_Flag */ enum Set_Buffer_Flag; /* Description A Set_Buffer_Flag field specifies the behavior of an operation that sets the buffer of a view. Values SetBuffer_KeepOriginalGUI = 0x1 If SetBuffer_KeepOriginalGUI then when the file is set, the view will not switch to it if some other GUI was currently up, otherwise any GUI that is up is closed and the view switches to the file. */ /* doc_Input_Type_Flag */ enum Input_Type_Flag; /* Description A Input_Type_Flag field specifies a set of input event types. Values EventOnAnyKey = 0x1 If EventOnAnyKey is set, all keyboard events are included in the set. EventOnEsc = 0x2 If EventOnEsc is set, any press of the escape key is included in the set. EventOnLeftButton = 0x4 If EventOnLeftButton is set, left clicks are included in the set. EventOnRightButton = 0x8 If EventOnRightButton is set, right clicks are included in the set. EventOnWheel = 0x10 If EventOnWheel is set, any wheel movement is included in the set. EventOnMouseMove = 0x20 This is not totally implemented yet. EventOnButton = (EventOnLeftButton | EventOnRightButton | EventOnWheel) If EventOnButton is set, all mouse button events are included in the set. EventOnMouse = (EventOnButton | EventOnMouseMove) This is not totally implemented yet. EventAll = 0xFF EventAll is a catch all name for including all possible events in the set. */ /* doc_Mouse_Cursor_Show_Type */ enum Mouse_Cursor_Show_Type; /* Description A Mouse_Cursor_Show_Type value specifes a mode for 4coder to handle the mouse cursor. Values MouseCursorShow_Never The MouseCursorShow_Never mode never shows the cursor. MouseCursorShow_Always The MouseCursorShow_Never mode always shows the cursor. */ /* doc_Buffer_Seek_Type */ enum Buffer_Seek_Type; /* Description The Buffer_Seek_Type is is used in a Buffer_Seek to identify which coordinates are suppose to be used for the seek. Values buffer_seek_pos This value indicates absolute positioning where positions are measured as the number of bytes from the start of the file. buffer_seek_wrapped_xy This value indicates xy positioning with wrapped lines where the x and y values are in pixels. buffer_seek_unwrapped_xy This value indicates xy positioning with unwrapped lines where the x and y values are in pixels. buffer_seek_line_char This value indicates line-character, or line-column positioning. These coordinates are 1 based to match standard line numbering. See Also Buffer_Seek 4coder_Buffer_Positioning_System */ /* doc_View_Split_Position */ enum View_Split_Position; /* Description A View_Split_Position specifies where a new view should be placed as a result of a view split operation. Values ViewSplit_Top This value indicates that the new view should be above the existing view. ViewSplit_Bottom This value indicates that the new view should be below the existing view. ViewSplit_Left This value indicates that the new view should be left of the existing view. ViewSplit_Right This value indicates that the new view should be right of the existing view. */ /* doc_Generic_Command */ union Generic_Command { Command_ID cmdid; Custom_Command_Function * command; }; /* Description Generic_Command acts as a name for a command, and can name an internal command or a custom command. Fields cmdid If this Generic_Command represents an internal command the cmdid field will have a value less than cmdid_count, and this field is the command id for the command. command If this Generic_Command does not represent an internal command the command field is the pointer to the custom command.. */ /* doc_Key_Event_Data */ struct Key_Event_Data { Key_Code keycode; Key_Code character; Key_Code character_no_caps_lock; char modifiers[MDFR_INDEX_COUNT]; }; /* Description Key_Event_Data describes a key event, including the translation to a character, the translation to a character ignoring the state of caps lock, and an array of all the modifiers that were pressed at the time of the event. Fields keycode This field is the raw keycode which is always non-zero in valid key events. character This field is the keycode after translation to a character, this is 0 if there is no translation. character_no_caps_lock This field is like the field character, except that the state of caps lock is ignored in the translation. modifiers This field is an array indicating the state of modifiers at the time of the key press. The array is indexed using the values of Key_Modifier. A 1 indicates that the corresponding modifier was held, and a 0 indicates that it was not held. */ /* doc_Mouse_State */ struct Mouse_State { char l; char r; char press_l; char press_r; char release_l; char release_r; char wheel; char out_of_window; int32_t x; int32_t y; }; /* Description Mouse_State describes an entire mouse state complete with the position, left and right button states, the wheel state, and whether or not the mouse if in the window. Fields l This field indicates that the left button is held. r This field indicates that the right button is held. press_l This field indicates that the left button was pressed this frame. press_r This field indicates that the right button was pressed this frame. release_l This field indicates that the left button was released this frame. release_r This field indicates that the right button was released this frame. wheel This field is 0 when the wheel has not moved, it is 1 for a downward motion and -1 for an upward motion. out_of_window This field indicates that the mouse is outside of the window. x This field contains the x position of the mouse relative to the window where the left side is 0. y This field contains the y position of the mouse relative to the window where the top side is 0. */ /* doc_Range */ union Range { struct { int32_t min; int32_t max; }; struct { int32_t start; int32_t end; }; }; /* Description Range describes an integer range typically used for ranges within a buffer. Ranges tend are usually not passed as a Range struct into the API, but this struct is used to return ranges.Throughout the API ranges are thought of in the form [min,max Fields min This is the smaller value in the range, it is also the 'start'. max This is the larger value in the range, it is also the 'end'. start This is the start of the range, it is also the 'min'. end This is the end of the range, it is also the 'max'. */ /* doc_File_Info */ struct File_Info { char * filename; int32_t filename_len; int32_t folder; }; /* Description File_Info describes the name and type of a file. Fields filename This field is a null terminated string specifying the name of the file. filename_len This field specifies the length of the filename string not counting the null terminator. folder This field indicates that the description is for a folder not a file. See Also File_List */ /* doc_File_List */ struct File_List { void * block; File_Info * infos; int32_t count; int32_t block_size; }; /* Description File_List is a list of File_Info structs. Fields block This field is for inernal use. infos This field is an array of File_Info structs. count This field specifies the number of struts in the info array. block_size This field is for internal use. */ /* doc_Buffer_Identifier */ struct Buffer_Identifier { char * name; int32_t name_len; int32_t id; }; /* Description Buffer_Identifier acts as a loosely typed description of a buffer that can either be a name or an id. If the Fields name This field is the name of the buffer; it need not be null terminated. If id is specified this pointer should be NULL. name_len This field specifies the length of the name string. id This field is the id of the buffer. If name is specified this should be 0. */ /* doc_GUI_Scroll_Vars */ struct GUI_Scroll_Vars { float scroll_y; int32_t target_y; int32_t prev_target_y; float scroll_x; int32_t target_x; int32_t prev_target_x; }; /* Description This struct is a part of an incomplete feature. Fields scroll_y TODO target_y TODO prev_target_y TODO scroll_x TODO target_x TODO prev_target_x TODO */ /* doc_Full_Cursor */ struct Full_Cursor { int32_t pos; int32_t line; int32_t character; float unwrapped_x; float unwrapped_y; float wrapped_x; float wrapped_y; }; /* Description Full_Cursor describes the position of a cursor in every buffer coordinate system supported by 4coder. This cursor type requires that the buffer is associated with a view to give the x/y values meaning. Fields pos This field contains the cursor's position in absolute positioning. line This field contains the number of the line where the cursor is located. This field is one based. character This field contains the number of the column where the cursor is located. This field is one based. unwrapped_x This field contains the x position measured with unwrapped lines. unwrapped_y This field contains the y position measured with unwrapped lines. wrapped_x This field contains the x position measured with wrapped lines. wrapped_y This field contains the y position measured with wrapped lines. See Also 4coder_Buffer_Positioning_System */ /* doc_Partial_Cursor */ struct Partial_Cursor { int32_t pos; int32_t line; int32_t character; }; /* Description Partial_Cursor describes the position of a cursor in all of the coordinate systems that a invariant to the View. In other words the coordinate systems available here can be used on a buffer that is not currently associated with a View. Fields pos This field contains the cursor's position in absolute positioning. line This field contains the number of the line where the cursor is located. This field is one based. character This field contains the number of the column where the cursor is located. This field is one based. See Also 4coder_Buffer_Positioning_System */ /* doc_Buffer_Seek */ struct Buffer_Seek { Buffer_Seek_Type type; union { struct { int32_t pos; }; struct { bool32 round_down; float x; float y; }; struct { int32_t line; int32_t character; }; }; }; /* Description Buffer_Seek describes the destination of a seek operation. There are helpers for concisely creating Buffer_Seek structs. They can be found in 4coder_buffer_types.h. Fields type The type field determines the coordinate system of the seek operation. pos The pos field specified the pos when the seek is in absolute position. round_down For xy coordinate seeks, rounding down means that any x in the box of the character lands on that character. For instance when clicking rounding down is the user's expected behavior. Not rounding down means that the right hand portion of the character's box, which is closer to the next character, will land on that next character. The unrounded behavior is the expected behavior when moving vertically and keeping the preferred x. x The x coordinate for xy type seeks. y The y coordinate for xy type seeks. line The line number of a line-character type seek. character The character number of a line-character type seek. See Also Buffer_Seek_Type 4coder_Buffer_Positioning_System */ /* doc_Buffer_Edit */ struct Buffer_Edit { int32_t str_start; int32_t len; int32_t start; int32_t end; }; /* Description Buffer_Edit describes a range of a buffer and string to replace that range. A Buffer_Edit has to be paired with a string that contains the actual text that will be replaced into the buffer. Fields str_start The str_start field specifies the first character in the accompanying string that corresponds with this edit. len The len field specifies the length of the string being written into the buffer. start The start field specifies the start of the range in the buffer to replace in absolute position. end The end field specifies one past the end of the range in the buffer to replace in absolute position. */ /* doc_Buffer_Summary */ struct Buffer_Summary { bool32 exists; bool32 ready; int32_t buffer_id; Access_Flag lock_flags; int32_t size; int32_t line_count; char * file_name; int32_t file_name_len; char * buffer_name; int32_t buffer_name_len; Dirty_State dirty; bool32 is_lexed; bool32 tokens_are_ready; int32_t map_id; bool32 unwrapped_lines; }; /* Description Buffer_Summary acts as a handle to a buffer and describes the state of the buffer. Fields exists This field indicates whether the Buffer_Summary describes a buffer that is open in 4coder. When this field is false the summary is referred to as a "null summary". ready If this is not a null summary, this field indicates whether the buffer has finished loading. buffer_id If this is not a null summary this field is the id of the associated buffer. If this is a null summary then buffer_id is 0. lock_flags If this is not a null summary, this field contains flags describing the protection status of the buffer. size If this is not a null summary, this field specifies the size of the text in the buffer. line_count If this is not a null summary, this field specifies the number of lines in the buffer. file_name If this is not a null summary, this field specifies the file name associated to this buffer. file_name_len This field specifies the length of the file_name string. buffer_name If this is not a null summary, this field specifies the name of the buffer. buffer_name_len This field specifies the length of the buffer_name string. dirty This field indicates the dirty state of the buffer. is_lexed If this is not a null summary, this field indicates whether the buffer is set to lex tokens. tokens_are_ready If this is not a null summary, this field indicates whether the buffer has up to date tokens available. If this field is false, it may simply mean the tokens are still being generated in a background task and will be available later. If that is the case, is_lexed will be true to indicate that the buffer is trying to get it's tokens up to date. map_id If this is not a null summary, this field specifies the id of the command map for this buffer. unwrapped_lines If this is not a null summary, this field indicates whether the buffer 'prefers' wrapped lines. See Also Access_Flag Dirty_State */ /* doc_View_Summary */ struct View_Summary { bool32 exists; int32_t view_id; int32_t buffer_id; Access_Flag lock_flags; Full_Cursor cursor; Full_Cursor mark; float preferred_x; float line_height; bool32 unwrapped_lines; bool32 show_whitespace; i32_Rect file_region; GUI_Scroll_Vars scroll_vars; }; /* Description View_Summary acts as a handle to a view and describes the state of the view. Fields exists This field indicates whether the View_Summary describes a view that is open in 4coder. When this field is false the summary is referred to as a "null summary". view_id If this is not a null summary, this field is the id of the associated view. If this is a null summary then view_id is 0. buffer_id If this is not a null summary, then this is the id of the buffer this view currently sees. lock_flags If this is not a null summary, this field contains flags describing the protection status of the view. cursor If this is not a null summary, this describes the position of the cursor. mark If this is not a null summary, this describes the position of the mark. preferred_x If this is not a null summary, this is the x position that is maintained in vertical navigation. line_height If this is not a null summary, this specifies the height of a line rendered in the view. unwrapped_lines If this is not a null summary, this indicates that the view is set to render with unwrapped lines. show_whitespace If this is not a null summary, this indicates that the view is set to highlight white space. file_region If this is not a null summary, this describes the screen position in which this view's buffer is displayed. scroll_vars If this is not a null summary, this describes the scrolling position inside the view. See Also Access_Flag Full_Cursor */ /* doc_User_Input */ struct User_Input { User_Input_Type_ID type; bool32 abort; union { Key_Event_Data key; Mouse_State mouse; }; Generic_Command command; }; /* Description User_Input describes a user input event which can be either a key press or mouse event. Fields type This field specifies whether the event was a key press or mouse event. abort This field indicates that an abort event has occurred and the command needs to shut down. key This field describes a key press event. mouse This field describes a mouse input event. command If this event would trigger a command, this field specifies what the command would be. See Also User_Input_Type_ID Generic_Command */ /* doc_Query_Bar */ struct Query_Bar { String prompt; String string; }; /* Description Query_Bar is a struct used to store information in the user's control that will be displayed as a drop down bar durring an interactive command. Fields prompt This specifies the prompt portion of the drop down bar. string This specifies the main string portion of the drop down bar. */ /* doc_Event_Message */ struct Event_Message { int32_t type; }; /* Description This feature is not implemented. Fields type This feature is not implemented. */ /* doc_Theme_Color */ struct Theme_Color { Style_Tag tag; int_color color; }; /* Description Theme_Color stores a style tag/color pair, for the purpose of setting and getting colors in the theme. Fields tag The style slot in the style palette. color The color in the slot. See Also Style_Tag int_color */ /* doc_Buffer_Batch_Edit_Type */ enum Buffer_Batch_Edit_Type; /* Description A Buffer_Batch_Edit_Type is a type of batch operation. Values BatchEdit_Normal The BatchEdit_Normal operation is always correct but does the most work if there are tokens to correct. BatchEdit_PreserveTokens The BatchEdit_PreserveTokens operation is one in which none of the edits add, delete, or change any tokens. This usually applies when whitespace is being replaced with whitespace. */ /* doc_Buffer_Batch_Edit */ struct Buffer_Batch_Edit { char * str; int32_t str_len; Buffer_Edit * edits; int32_t edit_count; }; /* Description This struct is used to bundle the parameters of the buffer_batch_edit function. It is convenient for a few functions that return a batch edit to the user. Fields str The pointer to the edit string buffer. str_len The length of the edit string buffer. edits The array of edits to be applied. edit_count The number of edits in the array. See Also buffer_batch_edit */ /* 4 String Library 4.1 String Intro Coming Soon 4.2 String Function List char_is_slash char_is_upper char_is_lower char_to_upper char_to_lower char_is_whitespace char_is_alpha_numeric char_is_alpha_numeric_true char_is_alpha char_is_alpha_true char_is_hex char_is_numeric make_string_cap make_string make_lit_string make_fixed_width_string expand_str str_size make_string_slowly substr_tail substr skip_whitespace chop_whitespace skip_chop_whitespace tailstr match_cc match_sc match_cs match_ss match_part_ccl match_part_scl match_part_cc match_part_sc match_part_cs match_part_ss match_insensitive_cc match_insensitive_sc match_insensitive_cs match_insensitive_ss match_part_insensitive_ccl match_part_insensitive_scl match_part_insensitive_cc match_part_insensitive_sc match_part_insensitive_cs match_part_insensitive_ss compare_cc compare_sc compare_cs compare_ss find_c_char find_s_char rfind_s_char find_c_chars find_s_chars find_substr_c find_substr_s rfind_substr_s find_substr_insensitive_c find_substr_insensitive_s has_substr_c has_substr_s has_substr_insensitive_c has_substr_insensitive_s copy_fast_unsafe_cc copy_fast_unsafe_cs copy_checked_ss copy_partial_sc copy_partial_ss copy_cc copy_ss copy_sc append_checked_ss append_partial_sc append_partial_ss append_s_char append_ss append_sc terminate_with_null append_padding replace_char to_lower_cc to_lower_ss to_lower_s to_upper_cc to_upper_ss to_upper_s to_camel_cc int_to_str_size int_to_str append_int_to_str u64_to_str_size u64_to_str append_u64_to_str float_to_str_size append_float_to_str float_to_str str_is_int_c str_is_int_s str_to_int_c str_to_int_s hexchar_to_int int_to_hexchar hexstr_to_int color_to_hexstr hexstr_to_color reverse_seek_slash_pos reverse_seek_slash front_of_directory path_of_directory set_last_folder_sc set_last_folder_ss file_extension remove_extension remove_last_folder string_set_match_table string_set_match 4.3 String Function Descriptions */ /* doc_strings */ /* doc_char_is_slash */ fstr_bool char_is_slash( char c ) /* Description This call returns non-zero if c is \ or /. */ /* doc_char_is_upper */ fstr_bool char_is_upper( char c ) /* Description If c is an uppercase letter this call returns true. */ /* doc_char_is_lower */ fstr_bool char_is_lower( char c ) /* Description If c is a lower letter this call returns true. */ /* doc_char_to_upper */ char char_to_upper( char c ) /* Description If c is a lowercase letter this call returns the uppercase equivalent, otherwise it returns c. */ /* doc_char_to_lower */ char char_to_lower( char c ) /* Description If c is an uppercase letter this call returns the lowercase equivalent, otherwise it returns c. */ /* doc_char_is_whitespace */ fstr_bool char_is_whitespace( char c ) /* Description This call returns non-zero if c is whitespace. */ /* doc_char_is_alpha_numeric */ fstr_bool char_is_alpha_numeric( char c ) /* Description This call returns non-zero if c is any alphanumeric character including underscore. */ /* doc_char_is_alpha_numeric_true */ fstr_bool char_is_alpha_numeric_true( char c ) /* Description This call returns non-zero if c is any alphanumeric character no including underscore. */ /* doc_char_is_alpha */ fstr_bool char_is_alpha( char c ) /* Description This call returns non-zero if c is any alphabetic character including underscore. */ /* doc_char_is_alpha_true */ fstr_bool char_is_alpha_true( char c ) /* Description This call returns non-zero if c is any alphabetic character. */ /* doc_char_is_hex */ fstr_bool char_is_hex( char c ) /* Description This call returns non-zero if c is any valid hexadecimal digit. */ /* doc_char_is_numeric */ fstr_bool char_is_numeric( char c ) /* Description This call returns non-zero if c is any valid decimal digit. */ /* doc_make_string_cap */ String make_string_cap( void *str, int32_t size, int32_t mem_size ) /* Parameters str The str parameter provides the of memory with which the string shall operate. size The size parameter expresses the initial size of the string. If the memory does not already contain a useful string this should be zero. mem_size The mem_size parameter expresses the full size of the memory provided by str. Description This call returns the String created from the parameters. */ /* doc_make_string */ String make_string( void *str, int32_t size ) /* Parameters str The str parameter provides the of memory with which the string shall operate. size The size parameter expresses the initial size of the string. If the memory does not already contain a useful string this should be zero. Since this version does not specify the size of the memory it is also assumed that this size is the maximum size of the memory. Description This call returns the String created from the parameters. */ /* doc_make_lit_string */ #define make_lit_string(s) /* Description This macro takes a literal string in quotes and uses it to create a String with the correct size and memory size. Strings created this way should usually not be mutated. */ /* doc_make_fixed_width_string */ #define make_fixed_width_string(s) /* Description This macro takes a local char array with a fixed width and uses it to create an empty String with the correct size and memory size to operate on the array. */ /* doc_expand_str */ #define expand_str(s) /* Description This macro is a helper for any calls that take a char*,integer pair to specify a string. This macro expands to both of those parameters from one String struct. */ /* doc_str_size */ int32_t str_size( char *str ) /* Description This call returns the number of bytes before a null terminator starting at str. */ /* doc_make_string_slowly */ String make_string_slowly( void *str ) /* Description This call makes a string by counting the number of bytes before a null terminator and treating that as the size and memory size of the string. */ /* doc_substr_tail */ String substr_tail( String str, int32_t start ) /* Description This call creates a substring of str that starts with an offset from str's base. The new string uses the same underlying memory so both strings will see changes. Usually strings created this way should only go through immutable calls. */ /* doc_substr */ String substr( String str, int32_t start, int32_t size ) /* Description This call creates a substring of str that starts with an offset from str's base, and has a fixed size. The new string uses the same underlying memory so both strings will see changes. Usually strings created this way should only go through immutable calls. */ /* doc_skip_whitespace */ String skip_whitespace( String str ) /* Description This call creates a substring that starts with the first non-whitespace character of str. Like other substr calls, the new string uses the underlying memory and so should usually be considered immutable. See Also substr */ /* doc_chop_whitespace */ String chop_whitespace( String str ) /* Description This call creates a substring that ends with the last non-whitespace character of str. Like other substr calls, the new string uses the underlying memory and so should usually be considered immutable. See Also substr */ /* doc_skip_chop_whitespace */ String skip_chop_whitespace( String str ) /* Description This call is equivalent to calling skip_whitespace and chop_whitespace together. See Also skip_whitespace chop_whitespace */ /* doc_tailstr */ String tailstr( String str ) /* Description This call returns an empty String with underlying memory taken from the portion of str's memory that is not used. */ /* doc_match_cc */ fstr_bool match_cc( char *a, char *b ) /* Description This call returns non-zero if a and b are equivalent. */ /* doc_match_sc */ fstr_bool match_sc( String a, char *b ) /* Description This call returns non-zero if a and b are equivalent. */ /* doc_match_cs */ fstr_bool match_cs( char *a, String b ) /* Description This call returns non-zero if a and b are equivalent. */ /* doc_match_ss */ fstr_bool match_ss( String a, String b ) /* Description This call returns non-zero if a and b are equivalent. */ /* doc_match_part_ccl */ fstr_bool match_part_ccl( char *a, char *b, int32_t *len ) /* Parameters len If this call returns non-zero this parameter is used to output the length of b. Description This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a. */ /* doc_match_part_scl */ fstr_bool match_part_scl( String a, char *b, int32_t *len ) /* Parameters len If this call returns non-zero this parameter is used to output the length of b. Description This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a. */ /* doc_match_part_cc */ fstr_bool match_part_cc( char *a, char *b ) /* Parameters len If this call returns non-zero this parameter is used to output the length of b. Description This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a. */ /* doc_match_part_sc */ fstr_bool match_part_sc( String a, char *b ) /* Description This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a. */ /* doc_match_part_cs */ fstr_bool match_part_cs( char *a, String b ) /* Description This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a. */ /* doc_match_part_ss */ fstr_bool match_part_ss( String a, String b ) /* Description This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a. */ /* doc_match_insensitive_cc */ fstr_bool match_insensitive_cc( char *a, char *b ) /* Description This call returns non-zero if a and b are equivalent under case insensitive comparison. */ /* doc_match_insensitive_sc */ fstr_bool match_insensitive_sc( String a, char *b ) /* Description This call returns non-zero if a and b are equivalent under case insensitive comparison. */ /* doc_match_insensitive_cs */ fstr_bool match_insensitive_cs( char *a, String b ) /* Description This call returns non-zero if a and b are equivalent under case insensitive comparison. */ /* doc_match_insensitive_ss */ fstr_bool match_insensitive_ss( String a, String b ) /* Description This call returns non-zero if a and b are equivalent under case insensitive comparison. */ /* doc_match_part_insensitive_ccl */ fstr_bool match_part_insensitive_ccl( char *a, char *b, int32_t *len ) /* Parameters len If this call returns non-zero this parameter is used to output the length of b. Description This call performs the same partial matching rule as match_part under case insensitive comparison. See Also match_part */ /* doc_match_part_insensitive_scl */ fstr_bool match_part_insensitive_scl( String a, char *b, int32_t *len ) /* Parameters len If this call returns non-zero this parameter is used to output the length of b. Description This call performs the same partial matching rule as match_part under case insensitive comparison. See Also match_part */ /* doc_match_part_insensitive_cc */ fstr_bool match_part_insensitive_cc( char *a, char *b ) /* Description This call performs the same partial matching rule as match_part under case insensitive comparison. See Also match_part */ /* doc_match_part_insensitive_sc */ fstr_bool match_part_insensitive_sc( String a, char *b ) /* Description This call performs the same partial matching rule as match_part under case insensitive comparison. See Also match_part */ /* doc_match_part_insensitive_cs */ fstr_bool match_part_insensitive_cs( char *a, String b ) /* Description This call performs the same partial matching rule as match_part under case insensitive comparison. See Also match_part */ /* doc_match_part_insensitive_ss */ fstr_bool match_part_insensitive_ss( String a, String b ) /* Description This call performs the same partial matching rule as match_part under case insensitive comparison. See Also match_part */ /* doc_compare_cc */ int32_t compare_cc( char *a, char *b ) /* Description This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically. */ /* doc_compare_sc */ int32_t compare_sc( String a, char *b ) /* Description This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically. */ /* doc_compare_cs */ int32_t compare_cs( char *a, String b ) /* Description This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically. */ /* doc_compare_ss */ int32_t compare_ss( String a, String b ) /* Description This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically. */ /* doc_find_c_char */ int32_t find_c_char( char *str, int32_t start, char character ) /* Parameters str The str parameter provides a null terminated string to search. start The start parameter provides the index of the first character in str to search. character The character parameter provides the character for which to search. Description This call returns the index of the first occurance of character, or the size of the string if the character is not found. */ /* doc_find_s_char */ int32_t find_s_char( String str, int32_t start, char character ) /* Parameters str The str parameter provides a string to search. start The start parameter provides the index of the first character in str to search. character The character parameter provides the character for which to search. Description This call returns the index of the first occurance of character, or the size of the string if the character is not found. */ /* doc_rfind_s_char */ int32_t rfind_s_char( String str, int32_t start, char character ) /* Parameters str The str parameter provides a string to search. start The start parameter provides the index of the first character in str to search. character The character parameter provides the character for which to search. Description This call looks for the largest index less than or equal to the start position where the given character occurs. If the index is found it is returned otherwise -1 is returned. */ /* doc_find_c_chars */ int32_t find_c_chars( char *str, int32_t start, char *characters ) /* Parameters str The str parameter provides a null terminated string to search. start The start parameter provides the index of the first character in str to search. character The characters parameter provides a null terminated array of characters for which to search. Description This call returns the index of the first occurance of a character in the characters array, or the size of the string if no such character is not found. */ /* doc_find_s_chars */ int32_t find_s_chars( String str, int32_t start, char *characters ) /* Parameters str The str parameter provides a string to search. start The start parameter provides the index of the first character in str to search. character The characters parameter provides a null terminated array of characters for which to search. Description This call returns the index of the first occurance of a character in the characters array, or the size of the string if no such character is not found. */ /* doc_find_substr_c */ int32_t find_substr_c( char *str, int32_t start, String seek ) /* Parameters str The str parameter provides a null terminated string to search. start The start parameter provides the index of the first character in str to search. seek The seek parameter provides a string to find in str. Description This call returns the index of the first occurance of the seek substring in str or the size of str if no such substring in str is found. */ /* doc_find_substr_s */ int32_t find_substr_s( String str, int32_t start, String seek ) /* Parameters str The str parameter provides a string to search. start The start parameter provides the index of the first character in str to search. seek The seek parameter provides a string to find in str. Description This call returns the index of the first occurance of the seek substring in str or the size of str if no such substring in str is found. */ /* doc_rfind_substr_s */ int32_t rfind_substr_s( String str, int32_t start, String seek ) /* Parameters str The str parameter provides a string to search. start The start parameter provides the index of the first character in str to search. seek The seek parameter provides a string to find in str. Description This call returns the index of the last occurance of the seek substring in str or -1 if no such substring in str is found. */ /* doc_find_substr_insensitive_c */ int32_t find_substr_insensitive_c( char *str, int32_t start, String seek ) /* Parameters str The str parameter provides a null terminated string to search. start The start parameter provides the index of the first character in str to search. seek The seek parameter provides a string to find in str. Description This call acts as find_substr under case insensitive comparison. See Also find_substr */ /* doc_find_substr_insensitive_s */ int32_t find_substr_insensitive_s( String str, int32_t start, String seek ) /* Parameters str The str parameter provides a string to search. start The start parameter provides the index of the first character in str to search. seek The seek parameter provides a string to find in str. Description This call acts as find_substr under case insensitive comparison. See Also find_substr */ /* doc_has_substr_c */ fstr_bool has_substr_c( char *s, String seek ) /* Description This call returns non-zero if the string s contains a substring equivalent to seek. */ /* doc_has_substr_s */ fstr_bool has_substr_s( String s, String seek ) /* Description This call returns non-zero if the string s contains a substring equivalent to seek. */ /* doc_has_substr_insensitive_c */ fstr_bool has_substr_insensitive_c( char *s, String seek ) /* Description This call returns non-zero if the string s contains a substring equivalent to seek under case insensitive comparison. */ /* doc_has_substr_insensitive_s */ fstr_bool has_substr_insensitive_s( String s, String seek ) /* Description This call returns non-zero if the string s contains a substring equivalent to seek under case insensitive comparison. */ /* doc_copy_fast_unsafe_cc */ int32_t copy_fast_unsafe_cc( char *dest, char *src ) /* Description This call performs a copy from the src buffer to the dest buffer. The copy does not stop until a null terminator is found in src. There is no safety against overrun so dest must be large enough to contain src. The null terminator is not written to dest. This call returns the number of bytes coppied to dest. */ /* doc_copy_fast_unsafe_cs */ int32_t copy_fast_unsafe_cs( char *dest, String src ) /* Description This call performs a copy from the src string to the dest buffer. The copy does not stop until src.size characters are coppied. There is no safety against overrun so dest must be large enough to contain src. The null terminator is not written to dest. This call returns the number of bytes coppied to dest. */ /* doc_copy_checked_ss */ fstr_bool copy_checked_ss( String *dest, String src ) /* Description This call performs a copy from the src string to the dest string. The memory_size of dest is checked before any coppying is done. This call returns non-zero on a successful copy. */ /* doc_copy_partial_sc */ fstr_bool copy_partial_sc( String *dest, char *src ) /* Description This call performs a copy from the src buffer to the dest string. The memory_size of dest is checked if the entire copy cannot be performed, as many bytes as possible are coppied to dest. This call returns non-zero if the entire string is coppied to dest. */ /* doc_copy_partial_ss */ fstr_bool copy_partial_ss( String *dest, String src ) /* Description This call performs a copy from the src string to the dest string. The memory_size of dest is checked if the entire copy cannot be performed, as many bytes as possible are coppied to dest. This call returns non-zero if the entire string is coppied to dest. */ /* doc_copy_cc */ int32_t copy_cc( char *dest, char *src ) /* Description This call performs a copy from src to dest equivalent to copy_fast_unsafe. See Also copy_fast_unsafe */ /* doc_copy_ss */ void copy_ss( String *dest, String src ) /* Description This call performs a copy from src to dest equivalent to copy_checked. See Also copy_checked */ /* doc_copy_sc */ void copy_sc( String *dest, char *src ) /* Description This call performs a copy from src to dest equivalent to copy_partial. See Also copy_partial */ /* doc_append_checked_ss */ fstr_bool append_checked_ss( String *dest, String src ) /* Description This call checks if there is enough space in dest's underlying memory to append src onto dest. If there is src is appended and the call returns non-zero. */ /* doc_append_partial_sc */ fstr_bool append_partial_sc( String *dest, char *src ) /* Description This call attemps to append as much of src into the space in dest's underlying memory as possible. If the entire string is appended the call returns non-zero. */ /* doc_append_partial_ss */ fstr_bool append_partial_ss( String *dest, String src ) /* Description This call attemps to append as much of src into the space in dest's underlying memory as possible. If the entire string is appended the call returns non-zero. */ /* doc_append_s_char */ fstr_bool append_s_char( String *dest, char c ) /* Description This call attemps to append c onto dest. If there is space left in dest's underlying memory the character is appended and the call returns non-zero. */ /* doc_append_ss */ fstr_bool append_ss( String *dest, String src ) /* Description This call is equivalent to append_partial. See Also append_partial */ /* doc_append_sc */ fstr_bool append_sc( String *dest, char *src ) /* Description This call is equivalent to append_partial. See Also append_partial */ /* doc_terminate_with_null */ fstr_bool terminate_with_null( String *str ) /* Description This call attemps to append a null terminator onto str without effecting the size of str. This is usually called when the time comes to pass the the string to an API that requires a null terminator. This call returns non-zero if there was a spare byte in the strings underlying memory. */ /* doc_append_padding */ fstr_bool append_padding( String *dest, char c, int32_t target_size ) /* Description This call pads out dest so that it has a size of target_size by appending the padding character c until the target size is achieved. This call returns non-zero if dest does not run out of space in the underlying memory. */ /* doc_replace_char */ void replace_char( String *str, char replace, char with ) /* Parameters str The str parameter provides the string in which replacement shall be performed. replace The replace character specifies which character should be replaced. with The with character specifies what to write into the positions where replacement occurs. Description This call replaces all occurances of character in str with another character. */ /* doc_to_lower_cc */ void to_lower_cc( char *src, char *dst ) /* Parameters src The source string to conver to lowercase. This string must be null terminated. dst The destination buffer to receive the converted string. This must be large enough to contain all of src and a null terminator. Description Rewrites the string in src into dst with all letters lowercased. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place. */ /* doc_to_lower_ss */ void to_lower_ss( String *dst, String src ) /* Parameters dst The destination buffer to receive the converted string. This must have a capacity of at least the size of src. src The source string to conver to lowercase. Description Rewrites the string in src into dst. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place. */ /* doc_to_lower_s */ void to_lower_s( String *str ) /* Parameters str The string to be converted to all lowercase. Description This version of to_lower converts str to lowercase in place. */ /* doc_to_upper_cc */ void to_upper_cc( char *src, char *dst ) /* Parameters src The source string to convert to uppercase. This string must be null terminated. dst The destination buffer to receive the converted string. This must be large enough to contain all of src and a null terminator. Description Rewrites the string in src into dst. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place. */ /* doc_to_upper_ss */ void to_upper_ss( String *dst, String src ) /* Parameters dst The destination buffer to receive the converted string. This must have a capacity of at least the size of src. src The source string to convert to uppercase. Description Rewrites the string in src into dst. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place. */ /* doc_to_upper_s */ void to_upper_s( String *str ) /* Parameters str The string to be converted to all uppercase. Description This version of to_upper converts str to uppercase in place. */ /* doc_to_camel_cc */ void to_camel_cc( char *src, char *dst ) /* Parameters src The source string to convert to camel case. dst The destination buffer to receive the converted string. This must be large enough to contain all of src and a null terminator. Description Rewrites the string in src into dst. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place. */ /* doc_int_to_str_size */ int32_t int_to_str_size( int32_t x ) /* Description This call returns the number of bytes required to represent x as a string. */ /* doc_int_to_str */ fstr_bool int_to_str( String *dest, int32_t x ) /* Description This call writes a string representation of x into dest. If there is enough space in dest this call returns non-zero. */ /* doc_append_int_to_str */ fstr_bool append_int_to_str( String *dest, int32_t x ) /* Description This call appends a string representation of x onto dest. If there is enough space in dest this call returns non-zero. */ /* doc_u64_to_str_size */ int32_t u64_to_str_size( uint64_t x ) /* Description This call returns the number of bytes required to represent x as a string. */ /* doc_u64_to_str */ fstr_bool u64_to_str( String *dest, uint64_t x ) /* Description This call writes a string representation of x into dest. If there is enough space in dest this call returns non-zero. */ /* doc_append_u64_to_str */ fstr_bool append_u64_to_str( String *dest, uint64_t x ) /* Description This call appends a string representation of x onto dest. If there is enough space in dest this call returns non-zero. */ /* doc_float_to_str_size */ int32_t float_to_str_size( float x ) /* Description This call returns the number of bytes required to represent x as a string. */ /* doc_append_float_to_str */ fstr_bool append_float_to_str( String *dest, float x ) /* Description This call writes a string representation of x into dest. If there is enough space in dest this call returns non-zero. */ /* doc_float_to_str */ fstr_bool float_to_str( String *dest, float x ) /* Description This call appends a string representation of x onto dest. If there is enough space in dest this call returns non-zero. */ /* doc_str_is_int_c */ int32_t str_is_int_c( char *str ) /* Description If str is a valid string representation of an integer, this call returns non-zero */ /* doc_str_is_int_s */ fstr_bool str_is_int_s( String str ) /* Description If str is a valid string representation of an integer, this call returns non-zero. */ /* doc_str_to_int_c */ int32_t str_to_int_c( char *str ) /* Description If str is a valid string representation of an integer, this call will return the integer represented by the string. Otherwise this call returns zero. */ /* doc_str_to_int_s */ int32_t str_to_int_s( String str ) /* Description If str represents a valid string representation of an integer, this call will return the integer represented by the string. Otherwise this call returns zero. */ /* doc_hexchar_to_int */ int32_t hexchar_to_int( char c ) /* Description If c is a valid hexadecimal digit [0-9a-fA-F] this call returns the value of the integer value of the digit. Otherwise the return is some nonsense value. */ /* doc_int_to_hexchar */ char int_to_hexchar( int32_t x ) /* Description If x is in the range [0,15] this call returns the equivalent lowercase hexadecimal digit. Otherwise the return is some nonsense value. */ /* doc_hexstr_to_int */ uint32_t hexstr_to_int( String str ) /* Description This call interprets str has a hexadecimal representation of an integer and returns the represented integer value. */ /* doc_color_to_hexstr */ fstr_bool color_to_hexstr( String *s, uint32_t color ) /* Description This call fills s with the hexadecimal representation of the color. If there is enough memory in s to represent the color this call returns non-zero. */ /* doc_hexstr_to_color */ fstr_bool hexstr_to_color( String s, uint32_t *out ) /* Description This call interprets s as a color and writes the 32-bit integer representation into out. */ /* doc_reverse_seek_slash_pos */ int32_t reverse_seek_slash_pos( String str, int32_t pos ) /* Description This call searches for a slash in str by starting pos bytes from the end and going backwards. */ /* doc_reverse_seek_slash */ int32_t reverse_seek_slash( String str ) /* Description This call searches for a slash in str by starting at the end and going backwards. */ /* doc_front_of_directory */ String front_of_directory( String dir ) /* Description This call returns a substring of dir containing only the file name or folder name furthest to the right in the directory. See Also substr */ /* doc_path_of_directory */ String path_of_directory( String dir ) /* Description This call returns a substring of dir containing the whole path except for the final file or folder name. See Also substr */ /* doc_set_last_folder_sc */ fstr_bool set_last_folder_sc( String *dir, char *folder_name, char slash ) /* Parameters dir The dir parameter is the directory string in which to set the last folder in the directory. folder_name The folder_name parameter is a null terminated string specifying the name to set at the end of the directory. slash The slash parameter specifies what slash to use between names in the directory. Description This call deletes the last file name or folder name in the dir string and appends the new provided one. If there is enough memory in dir this call returns non-zero. */ /* doc_set_last_folder_ss */ fstr_bool set_last_folder_ss( String *dir, String folder_name, char slash ) /* Parameters dir The dir parameter is the directory string in which to set the last folder in the directory. folder_name The folder_name parameter is a string specifying the name to set at the end of the directory. slash The slash parameter specifies what slash to use between names in the directory. Description This call deletes the last file name or folder name in the dir string and appends the new provided one. If there is enough memory in dir this call returns non-zero. */ /* doc_file_extension */ String file_extension( String str ) /* Description This call returns a substring containing only the file extension of the provided filename. See Also substr */ /* doc_remove_extension */ fstr_bool remove_extension( String *str ) /* Description This call attemps to delete a file extension off the end of a filename. This call returns non-zero on success. */ /* doc_remove_last_folder */ fstr_bool remove_last_folder( String *str ) /* Description This call attemps to delete a folder or filename off the end of a path string. This call returns non-zero on success. */ /* doc_string_set_match_table */ fstr_bool string_set_match_table( void *str_set, int32_t item_size, int32_t count, String str, int32_t *match_index ) /* Parameters str_set The str_set parameter may be an array of any type. It should point at the String in the first element of the array. count The item_size parameter should describe the "stride" from one String to the next, in other words it should be the size of one element of the array. count The count parameter specifies the number of elements in the str_set array. str The str parameter specifies the string to match against the str_set. match_index If this call succeeds match_index is filled with the index into str_set where the match occurred. Description This call tries to see if str matches any of the strings in str_set. If there is a match the call succeeds and returns non-zero. The matching rule is equivalent to the matching rule for match. See Also match */ /* doc_string_set_match */ fstr_bool string_set_match( String *str_set, int32_t count, String str, int32_t *match_index ) /* Parameters str_set The str_set parameter is an array of String structs specifying matchable strings. count The count parameter specifies the number of String structs in the str_set array. str The str parameter specifies the string to match against the str_set. match_index If this call succeeds match_index is filled with the index into str_set where the match occurred. Description This call tries to see if str matches any of the strings in str_set. If there is a match the call succeeds and returns non-zero. The matching rule is equivalent to the matching rule for match. See Also match */ /* 5 Lexer Library 5.1 Lexer Intro The 4cpp lexer system provides a polished, fast, flexible system that takes in C/C++ and outputs a tokenization of the text data. There are two API levels. One level is setup to let you easily get a tokenization of the file. This level manages memory for you with malloc to make it as fast as possible to start getting your tokens. The second level enables deep integration by allowing control over allocation, data chunking, and output rate control. To use the quick setup API you simply include 4cpp_lexer.h and read the documentation at cpp_lex_file. To use the the fancier API include 4cpp_lexer.h and read the documentation at cpp_lex_step. If you want to be absolutely sure you are not including malloc into your program you can define FCPP_FORBID_MALLOC before the include and the "step" API will continue to work. There are a few more features in 4cpp that are not documented yet. You are free to try to use these, but I am not totally sure they are ready yet, and when they are they will be documented. 5.2 Lexer Function List cpp_get_token cpp_lex_step cpp_lex_data_init cpp_lex_data_temp_size cpp_lex_data_temp_read cpp_lex_data_new_temp cpp_make_token_array cpp_free_token_array cpp_resize_token_array cpp_lex_file 5.3 Lexer Types List Cpp_Token_Type Cpp_Token Cpp_Token_Flag Cpp_Token_Array Cpp_Get_Token_Result Cpp_Lex_Data Cpp_Lex_Result 5.4 Lexer Function Descriptions */ /* doc_lexer */ /* doc_cpp_get_token */ Cpp_Get_Token_Result cpp_get_token( Cpp_Token_Array *token_array_in, int32_t pos ) /* Parameters token_array The array of tokens from which to get a token. pos The position, measured in bytes, to get the token for. Return A Cpp_Get_Token_Result struct is returned containing the index of a token and a flag indicating whether the pos is contained in the token or in whitespace after the token. Description This call performs a binary search over all of the tokens looking for the token that contains the specified position. If the position is in whitespace between the tokens, the returned token index is the index of the token immediately before the provided position. The returned index can be -1 if the position is before the first token. See Also Cpp_Get_Token_Result */ /* doc_cpp_lex_step */ Cpp_Lex_Result cpp_lex_step( Cpp_Lex_Data *S_ptr, char *chunk, int32_t size, int32_t full_size, Cpp_Token_Array *token_array_out, int32_t max_tokens_out ) /* Parameters S_ptr The lexer state. Go to the Cpp_Lex_Data section to see how to initialize the state. chunk The first or next chunk of the file being lexed. size The number of bytes in the chunk including the null terminator if the chunk ends in a null terminator. If the chunk ends in a null terminator the system will interpret it as the end of the file. full_size If the final chunk is not null terminated this parameter should specify the length of the file in bytes. To rely on an eventual null terminator use HAS_NULL_TERM for this parameter. token_array_out The token array structure that will receive the tokens output by the lexer. max_tokens_out The maximum number of tokens to be output to the token array. To rely on the max built into the token array pass NO_OUT_LIMIT here. Description This call is the primary interface of the lexing system. It is quite general so it can be used in a lot of different ways. I will explain the general rules first, and then give some examples of common ways it might be used. First a lexing state, Cpp_Lex_Data, must be initialized. The file to lex must be read into N contiguous chunks of memory. An output Cpp_Token_Array must be allocated and initialized with the appropriate count and max_count values. Then each chunk of the file must be passed to cpp_lex_step in order using the same lexing state for each call. Every time a call to cpp_lex_step returns LexResult_NeedChunk, the next call to cpp_lex_step should use the next chunk. If the return is some other value, the lexer hasn't finished with the current chunk and it sopped for some other reason, so the same chunk should be used again in the next call. If the file chunks contain a null terminator the lexer will return LexResult_Finished when it finds this character. At this point calling the lexer again with the same state will result in an error. If you do not have a null terminated chunk to end the file, you may instead pass the exact size in bytes of the entire file to the full_size parameter and it will automatically handle the termination of the lexing state when it has read that many bytes. If a full_size is specified and the system terminates for having seen that many bytes, it will return LexResult_Finished. If a full_size is specified and a null character is read before the total number of bytes have been read the system will still terminate as usual and return LexResult_Finished. If the system has filled the entire output array it will return LexResult_NeedTokenMemory. When this happens if you want to continue lexing the file you can grow the token array, or switch to a new output array and then call cpp_lex_step again with the chunk that was being lexed and the new output. You can also specify a max_tokens_out which is limits how many new tokens will be added to the token array. Even if token_array_out still had more space to hold tokens, if the max_tokens_out limit is hit, the lexer will stop and return LexResult_HitTokenLimit. If this happens there is still space left in the token array, so you can resume simply by calling cpp_lex_step again with the same chunk and the same output array. Also note that, unlike the chunks which must only be replaced when the system says it needs a chunk. You may switch to or modify the output array in between calls as much as you like. The most basic use of this system is to get it all done in one big chunk and try to allocate a nearly "infinite" output array so that it will not run out of memory. This way you can get the entire job done in one call and then just assert to make sure it returns LexResult_Finished to you: Cpp_Token_Array lex_file(char *file_name){ File_Data file = read_whole_file(file_name); char *temp = (char*)malloc(4096); // hopefully big enough Cpp_Lex_Data lex_state = cpp_lex_data_init(temp); Cpp_Token_Array array = {0}; array.tokens = (Cpp_Token*)malloc(1 array.max_count = (1 Cpp_Lex_Result result = cpp_lex_step(&lex_state, file.data, file.size, file.size, &array, NO_OUT_LIMIT); Assert(result == LexResult_Finished); free(temp); return(array); } See Also Cpp_Lex_Data */ /* doc_cpp_lex_data_init */ Cpp_Lex_Data cpp_lex_data_init( char *mem_buffer ) /* Parameters tb The memory to use for initializing the lex state's temp memory buffer. Return A brand new lex state ready to begin lexing a file from the beginning. Description Creates a new lex state in the form of a Cpp_Lex_Data struct and returns the struct. The system needs a temporary buffer that is as long as the longest token. 4096 is usually enough but the buffer is not checked, so to be 100% bullet proof it has to be the same length as the file being lexed. */ /* doc_cpp_lex_data_temp_size */ int32_t cpp_lex_data_temp_size( Cpp_Lex_Data *lex_data ) /* Parameters lex_data The lex state from which to get the temporary buffer size. Description This call gets the current size of the temporary buffer in the lexer state so that you can move to a new temporary buffer by copying the data over. See Also cpp_lex_data_temp_read cpp_lex_data_new_temp */ /* doc_cpp_lex_data_temp_read */ void cpp_lex_data_temp_read( Cpp_Lex_Data *lex_data, char *out_buffer ) /* Parameters lex_data The lex state from which to read the temporary buffer. out_buffer The buffer into which the contents of the temporary buffer will be written. The size of the buffer must be at least the size as returned by cpp_lex_data_temp_size. Description This call reads the current contents of the temporary buffer. See Also cpp_lex_data_temp_size cpp_lex_data_new_temp */ /* doc_cpp_lex_data_new_temp */ void cpp_lex_data_new_temp( Cpp_Lex_Data *lex_data, char *new_buffer ) /* Parameters lex_data The lex state that will receive the new temporary buffer. new_buffer The new temporary buffer that has the same contents as the old temporary buffer. Description This call can be used to set a new temporary buffer for the lex state. In cases where you want to discontinue lexing, store the state, and resume later. In such a situation it may be necessary for you to free the temp buffer that was originally used to make the lex state. This call allows you to supply a new temp buffer when you are ready to resume lexing. However the new buffer needs to have the same contents the old buffer had. To ensure this you have to use cpp_lex_data_temp_size and cpp_lex_data_temp_read to get the relevant contents of the temp buffer before you free it. See Also cpp_lex_data_temp_size cpp_lex_data_temp_read */ /* doc_cpp_make_token_array */ Cpp_Token_Array cpp_make_token_array( int32_t starting_max ) /* Parameters starting_max The number of tokens to initialize the array with. Return An empty Cpp_Token_Array with memory malloc'd for storing tokens. Description This call allocates a Cpp_Token_Array with malloc for use in other convenience functions. Stacks that are not allocated this way should not be used in the convenience functions. */ /* doc_cpp_free_token_array */ void cpp_free_token_array( Cpp_Token_Array token_array ) /* Parameters token_array An array previously allocated by cpp_make_token_array Description This call frees a Cpp_Token_Array. See Also cpp_make_token_array */ /* doc_cpp_resize_token_array */ void cpp_resize_token_array( Cpp_Token_Array *token_array, int32_t new_max ) /* Parameters token_array An array previously allocated by cpp_make_token_array. new_max The new maximum size the array should support. If this is not greater than the current size of the array the operation is ignored. Description This call allocates a new memory chunk and moves the existing tokens in the array over to the new chunk. See Also cpp_make_token_array */ /* doc_cpp_lex_file */ void cpp_lex_file( char *data, int32_t size, Cpp_Token_Array *token_array_out ) /* Parameters data The file data to be lexed in a single contiguous block. size The number of bytes in data. token_array_out The token array where the output tokens will be pushed. This token array must be previously allocated with cpp_make_token_array Description Lexes an entire file and manages the interaction with the lexer system so that it is quick and convenient to lex files. Cpp_Token_Array lex_file(char *file_name){ File_Data file = read_whole_file(file_name); // This array will be automatically grown if it runs // out of memory. Cpp_Token_Array array = cpp_make_token_array(100); cpp_lex_file(file.data, file.size, &array); return(array); } See Also cpp_make_token_array */ /* 5.5 Lexer Type Descriptions */ /* doc_lexer_types */ /* doc_Cpp_Token_Type */ enum Cpp_Token_Type; /* Description A Cpp_Token_Type classifies a token to make parsing easier. Some types are not actually output by the lexer, but exist because parsers will also make use of token types in their own output. Values CPP_TOKEN_JUNK = 0 CPP_TOKEN_COMMENT = 1 CPP_PP_INCLUDE = 2 CPP_PP_DEFINE = 3 CPP_PP_UNDEF = 4 CPP_PP_IF = 5 CPP_PP_IFDEF = 6 CPP_PP_IFNDEF = 7 CPP_PP_ELSE = 8 CPP_PP_ELIF = 9 CPP_PP_ENDIF = 10 CPP_PP_ERROR = 11 CPP_PP_IMPORT = 12 CPP_PP_USING = 13 CPP_PP_LINE = 14 CPP_PP_PRAGMA = 15 CPP_PP_STRINGIFY = 16 CPP_PP_CONCAT = 17 CPP_PP_UNKNOWN = 18 CPP_PP_DEFINED = 19 CPP_PP_INCLUDE_FILE = 20 CPP_PP_ERROR_MESSAGE = 21 CPP_TOKEN_KEY_TYPE = 22 CPP_TOKEN_KEY_MODIFIER = 23 CPP_TOKEN_KEY_QUALIFIER = 24 CPP_TOKEN_KEY_OPERATOR = 25 This type is not stored in token output from the lexer. CPP_TOKEN_KEY_CONTROL_FLOW = 26 CPP_TOKEN_KEY_CAST = 27 CPP_TOKEN_KEY_TYPE_DECLARATION = 28 CPP_TOKEN_KEY_ACCESS = 29 CPP_TOKEN_KEY_LINKAGE = 30 CPP_TOKEN_KEY_OTHER = 31 CPP_TOKEN_IDENTIFIER = 32 CPP_TOKEN_INTEGER_CONSTANT = 33 CPP_TOKEN_CHARACTER_CONSTANT = 34 CPP_TOKEN_FLOATING_CONSTANT = 35 CPP_TOKEN_STRING_CONSTANT = 36 CPP_TOKEN_BOOLEAN_CONSTANT = 37 CPP_TOKEN_STATIC_ASSERT = 38 CPP_TOKEN_BRACKET_OPEN = 39 CPP_TOKEN_BRACKET_CLOSE = 40 CPP_TOKEN_PARENTHESE_OPEN = 41 CPP_TOKEN_PARENTHESE_CLOSE = 42 CPP_TOKEN_BRACE_OPEN = 43 CPP_TOKEN_BRACE_CLOSE = 44 CPP_TOKEN_SEMICOLON = 45 CPP_TOKEN_ELLIPSIS = 46 CPP_TOKEN_STAR = 47 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_AMPERSAND = 48 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_TILDE = 49 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_PLUS = 50 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_MINUS = 51 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_INCREMENT = 52 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_DECREMENT = 53 This is an 'ambiguous' token type because it requires parsing to determine the full nature of the token. CPP_TOKEN_SCOPE = 54 CPP_TOKEN_POSTINC = 55 This type is for parser use, it is not output by the lexer. CPP_TOKEN_POSTDEC = 56 This type is for parser use, it is not output by the lexer. CPP_TOKEN_FUNC_STYLE_CAST = 57 This type is for parser use, it is not output by the lexer. CPP_TOKEN_CPP_STYLE_CAST = 58 CPP_TOKEN_CALL = 59 This type is for parser use, it is not output by the lexer. CPP_TOKEN_INDEX = 60 This type is for parser use, it is not output by the lexer. CPP_TOKEN_DOT = 61 CPP_TOKEN_ARROW = 62 CPP_TOKEN_PREINC = 63 This token is for parser use, it is not output by the lexer. CPP_TOKEN_PREDEC = 64 This token is for parser use, it is not output by the lexer. CPP_TOKEN_POSITIVE = 65 This token is for parser use, it is not output by the lexer. CPP_TOKEN_NEGAITVE = 66 This token is for parser use, it is not output by the lexer. CPP_TOKEN_NOT = 67 CPP_TOKEN_BIT_NOT = 68 This type is for parser use, it is not output by the lexer. CPP_TOKEN_CAST = 69 This type is for parser use, it is not output by the lexer. CPP_TOKEN_DEREF = 70 This type is for parser use, it is not output by the lexer. CPP_TOKEN_TYPE_PTR = 71 This type is for parser use, it is not output by the lexer. CPP_TOKEN_ADDRESS = 72 This type is for parser use, it is not output by the lexer. CPP_TOKEN_TYPE_REF = 73 This type is for parser use, it is not output by the lexer. CPP_TOKEN_SIZEOF = 74 CPP_TOKEN_ALIGNOF = 75 CPP_TOKEN_DECLTYPE = 76 CPP_TOKEN_TYPEID = 77 CPP_TOKEN_NEW = 78 CPP_TOKEN_DELETE = 79 CPP_TOKEN_NEW_ARRAY = 80 This type is for parser use, it is not output by the lexer. CPP_TOKEN_DELETE_ARRAY = 81 This type is for parser use, it is not output by the lexer. CPP_TOKEN_PTRDOT = 82 CPP_TOKEN_PTRARROW = 83 CPP_TOKEN_MUL = 84 This type is for parser use, it is not output by the lexer. CPP_TOKEN_DIV = 85 CPP_TOKEN_MOD = 86 CPP_TOKEN_ADD = 87 This type is for parser use, it is not output by the lexer. CPP_TOKEN_SUB = 88 This type is for parser use, it is not output by the lexer. CPP_TOKEN_LSHIFT = 89 CPP_TOKEN_RSHIFT = 90 CPP_TOKEN_LESS = 91 CPP_TOKEN_GRTR = 92 CPP_TOKEN_GRTREQ = 93 CPP_TOKEN_LESSEQ = 94 CPP_TOKEN_EQEQ = 95 CPP_TOKEN_NOTEQ = 96 CPP_TOKEN_BIT_AND = 97 This type is for parser use, it is not output by the lexer. CPP_TOKEN_BIT_XOR = 98 CPP_TOKEN_BIT_OR = 99 CPP_TOKEN_AND = 100 CPP_TOKEN_OR = 101 CPP_TOKEN_TERNARY_QMARK = 102 CPP_TOKEN_COLON = 103 CPP_TOKEN_THROW = 104 CPP_TOKEN_EQ = 105 CPP_TOKEN_ADDEQ = 106 CPP_TOKEN_SUBEQ = 107 CPP_TOKEN_MULEQ = 108 CPP_TOKEN_DIVEQ = 109 CPP_TOKEN_MODEQ = 110 CPP_TOKEN_LSHIFTEQ = 111 CPP_TOKEN_RSHIFTEQ = 112 CPP_TOKEN_ANDEQ = 113 CPP_TOKEN_OREQ = 114 CPP_TOKEN_XOREQ = 115 CPP_TOKEN_COMMA = 116 CPP_TOKEN_EOF = 117 This type is for parser use, it is not output by the lexer. CPP_TOKEN_TYPE_COUNT = 118 */ /* doc_Cpp_Token */ struct Cpp_Token { Cpp_Token_Type type; int32_t start; int32_t size; uint16_t state_flags; uint16_t flags; }; /* Description Cpp_Token represents a single lexed token. It is the primary output of the lexing system. Fields type The type field indicates the type of the token. All tokens have a type no matter the circumstances. start The start field indicates the index of the first character of this token's lexeme. size The size field indicates the number of bytes in this token's lexeme. state_flags The state_flags should not be used outside of the lexer's implementation. flags The flags field contains extra useful information about the token. See Also Cpp_Token_Flag */ /* doc_Cpp_Token_Flag */ enum Cpp_Token_Flag; /* Description The Cpp_Token_Flags are used to mark up tokens with additional information. Values CPP_TFLAG_PP_DIRECTIVE = 0x1 Indicates that the token is a preprocessor directive. CPP_TFLAG_PP_BODY = 0x2 Indicates that the token is on the line of a preprocessor directive. CPP_TFLAG_MULTILINE = 0x4 Indicates that the token spans across multiple lines. This can show up on line comments and string literals with back slash line continuation. CPP_TFLAG_IS_OPERATOR = 0x8 Indicates that the token is some kind of operator or punctuation like braces. CPP_TFLAG_IS_KEYWORD = 0x10 Indicates that the token is a keyword. */ /* doc_Cpp_Token_Array */ struct Cpp_Token_Array { Cpp_Token * tokens; int32_t count; int32_t max_count; }; /* Description Cpp_Token_Array is used to bundle together the common elements of a growing array of Cpp_Tokens. To initialize it the tokens field should point to a block of memory with a size equal to max_count*sizeof(Cpp_Token) and the count should be initialized to zero. Fields tokens The tokens field points to the memory used to store the array of tokens. count The count field counts how many tokens in the array are currently used. max_count The max_count field specifies the maximum size the count field may grow to before the tokens array is out of space. */ /* doc_Cpp_Get_Token_Result */ struct Cpp_Get_Token_Result { int32_t token_index; int32_t in_whitespace; }; /* Description Cpp_Get_Token_Result is the return result of the cpp_get_token call. Fields token_index The token_index field indicates which token answers the query. To get the token from the source array array.tokens[result.token_index] in_whitespace The in_whitespace field is true when the query position was actually in whitespace after the result token. See Also cpp_get_token */ /* doc_Cpp_Lex_Data */ struct Cpp_Lex_Data { /* non-public internals */ } ; /* Description Cpp_Lex_Data represents the state of the lexer so that the system may be resumable and the user can manage the lexer state and decide when to resume lexing with it. To create a new lexer state that has not begun doing any lexing work call cpp_lex_data_init.The internals of the lex state should not be treated as a part of the public API. See Also cpp_lex_data_init */ /* doc_Cpp_Lex_Result */ enum Cpp_Lex_Result; /* Description Cpp_Lex_Result is returned from the lexing engine to indicate why it stopped lexing. Values LexResult_Finished = 0 This indicates that the system got to the end of the file and will not accept more input. LexResult_NeedChunk = 1 This indicates that the system got to the end of an input chunk and is ready to receive the next input chunk. LexResult_NeedTokenMemory = 2 This indicates that the output array ran out of space to store tokens and needs to be replaced or expanded before continuing. LexResult_HitTokenLimit = 3 This indicates that the maximum number of output tokens as specified by the user was hit. */