Finds the Office files in this server's workspace and returns their absolute paths, host application and whether their VBA can be opened. Call this first when the user has not named a file. Covers Excel (.xlsm, .xlsb, .xlam, .xls, and .xlsx for Power Query and sheets), Word (.docm, .dotm, .doc), PowerPoint (.pptm, .potm), Access (.accdb, .mdb), and Visual Basic 6 projects (.vbp, whose modules are the files its manifest names). Files whose extension is recognized but not openable are listed with the reason, so a template or add-in is not silently missing. Use offset and next_offset to read large workspaces in pages.

A summary of one Office file in a single call: its VBA modules with kinds and line counts, its UserForms, its Power Query queries, its worksheets with used ranges and named ranges, and whether the VBA project is password-protected or digitally signed. has_vba_project is false for a macro-enabled file saved before its first macro, which is normal: the first xlide_write_module gives it a project. Call this once per file before working on it. Each module carries a content_token for a guarded write. For .xlsb and .xls sheet details, call xlide_list_sheets on Windows with Excel. An unreadable form or query summary is reported as unknown rather than empty.

Checks a file's VBA project for structural problems: records that disagree with each other, a module the directory names but the container does not hold, and the like. This is about the container, not about the code; use xlide_analyze for the code. Worth calling before risky work on an old or repaired file. Use offset and next_offset to read later problems from a damaged file.

Creates a new Office file with an empty VBA project at the given absolute path, from a template the application itself authored, so it opens with no repair prompt. Extensions: .xlsm, .xlsb, .xlam, .docm, .pptm, .accdb, and .xlsx for a workbook with Power Query and no macros. It never overwrites a file or replaces a project that is already there. A .xlsm, .docm or .pptm saved before its first macro has no VBA project at all; xlide_write_module gives it one along with the first module. This tool also gives an existing .docm or .accdb with no project the empty one its application makes.

Reports what this server can reach: its workspace roots, whether it is read-only, which optional layers are installed, and, on Windows, which Office applications are available to run macros and tests. Call it when a tool reports something missing, or before promising the user a test run.

Lists the VBA modules in an Office file: name, kind (standard, class, document or userform), line count, and a content_token to pass to a guarded write. xlide_project_info returns this and more in one call; use this one when the file is already known and only the module list is wanted. Use offset and next_offset to read large projects in pages.

The canonical way to read VBA. Returns a module's source as the VBA editor shows it, with the attribute header stripped, plus a content_token. Pass that token back as expected_content_token when you write, and the write is refused if anything changed the module in between. start_line and end_line read a slice of a long module; both are 1-based and inclusive. line_ranges reads several slices in one call, with each pair [first, last] using body line numbers.

Lists the Sub, Function and Property procedures in one module, with each one's kind, scope, line number and signature. The module's content_token can guard an xlide_edit_module call. Use it to find where to change something without reading a long module in full. Use offset and next_offset to page through a module with many procedures.

Searches every module's source in an Office file and returns each match with its module, line number and the line itself. Use it to find where a name is declared or used before changing it. content_tokens maps returned module names to tokens for guarded xlide_edit_module calls without a separate read. Use offset and next_offset to page through broad searches; total_match_count counts all matches. Plain text by default; set is_regex for a Python regular expression.

The canonical way to change VBA. Writes a module's source into the Office file and saves it. It replaces the module's whole source, so send all of it; send the body only, because the attribute header is managed for you. A module that does not exist is created: standard by default, or a class with kind='class'. Pass expected_content_token from your read and the write is refused if the module changed since. The result carries a diff of what the file now holds, read back after saving, which is what to show the user when they ask what changed. After writing, call xlide_analyze and treat any error as a build failure. Identical source is reported without saving. Ask the user first when the project is protected or signed.

Replaces, inserts or deletes several line ranges in one existing VBA module and saves once. Lines are 1-based against the original source returned by xlide_read_module, without the attribute header. Each edit has start_line, end_line inclusive, and replacement text. For insertion, set end_line to start_line - 1; an empty replacement deletes the named lines. Ranges must not overlap. expected_content_token is required and refuses a stale edit. Set preview_only to validate the edits and see the proposed diff without saving. An applied edit includes the read-back diff and new token. Analyze the file afterward.

Renames a VBA module everywhere its name is stored, and saves the file. Calls to the module's procedures elsewhere in the project are not rewritten; search for the old name first with xlide_search_modules. Document modules such as ThisWorkbook and Sheet1 cannot be renamed, because the host owns them.

Permanently deletes a VBA module from an Office file and saves it. There is no undo: ask the user first, and read the module before deleting it so its code can be put back if they change their mind. Document modules cannot be deleted. For Excel, the write is refused if the server cannot check whether a shape still calls the module.

Runs static analysis over every VBA module in an Office file and returns the problems with module, line, column, code and message. Needs no Office installation and runs nothing. Each file is measured against its own host's object model, so Word code is never judged by Excel's surface, and a Visual Basic 6 project against no host at all, because its code does not run in one. Call this after every VBA change and treat any problem at error severity as a build failure: fix it and analyze again until it is clean. Warnings are worth reading; some are style, some are the bug. Use offset and next_offset to read later findings.

Runs static analysis over VBA source you are holding, before it is written to a file. Use it to check code you have just generated: it costs nothing, needs no file, and catches the compile errors that would otherwise surface in front of the user. Pass host so the code is measured against the right object model, and file_path instead if the code is destined for a file that already exists, which resolves calls into the rest of that project. Use offset and next_offset to read later findings from a long result.

The analyzer's rule catalogue: every diagnostic code with its title, default severity, category, whether it mirrors a VBA compile failure, and the MS-VBAL section it enforces. Use it to explain a code to the user, or to decide whether a finding is a compile error or a judgement call.

Lists the type libraries a VBA project references: the name code uses to qualify them, the kind, and the registry or file path the project recorded. Call it when a name will not resolve, when deciding between early and late binding, or when code works on one machine and not another: a reference names a path and a version, so a project can be broken by the machine rather than by its own code.

Adds or removes a type library reference in a VBA project and saves the file. Use it when xlide_analyze reports missing-library-reference, or when code needs early binding, as Dim d As Scripting.Dictionary does. Name the library: Excel, Word, PowerPoint and Access work anywhere, and on Windows any library the VBA editor's References dialog lists resolves by its description (Microsoft Scripting Runtime) or by the name code writes (Scripting), taking its GUID, version and path from this machine's registry. A name that matches several libraries is refused with the candidates. Off Windows, pass guid and version. Adding the host's own library, or removing Microsoft Forms while a UserForm exists, is refused: the first is implicit and the second stops the project compiling.

Lists what an Access database holds besides its code: tables with their columns, saved queries with their SQL, and the relationships between tables. An .accdb is an application rather than a document, and the VBA in it is written against these, so reading the modules alone shows half of it. Use include with offset and next_offsets to page through a large catalog. Long query SQL is previewed; use xlide_read_access_query for the whole text. If one query's SQL cannot be read, that entry has sql=null and sql_error rather than hiding the catalog. Access files only.

Reads the SQL of one saved query in an Access database. Use it after xlide_access_catalog when a query's SQL was previewed. offset and max_chars read long SQL in character slices; next_offset points to the next slice. content_token describes the whole SQL, so compare it across pages if the database may have changed. Access files only.

Lists the UserForms in an Office file, or the forms and reports in an Access database, with each one's control count and, for Access, the sections a control can go in. A design's code is a module of the same name, read with xlide_read_module. An unreadable report collection is a failure, not an empty list. An unreadable design's sections are marked unknown with sections_error. Use offset and next_offset to read large form lists in pages.

Reads one form's design: every control with its name, type, the container it sits in, and the properties the developer set. Properties left at their default are not stored and so are not listed. A property read failure appears as _read_error, not an empty property set; unreadable sections have sections_error. Use offset and next_offset to read large forms in pages. Use it to understand a form's layout, or to see which control an event procedure belongs to.

Creates a UserForm, or an Access form or report, and saves the file. A form is a designer storage and a code module of the same name, and this writes both, which is why it exists rather than xlide_write_module. Renaming and deleting work on Access designs, where both halves move together; for a UserForm they are refused, because nothing here can move the designer storage and doing half of it loses the form. Add controls afterwards with xlide_edit_form, and write its event procedures with xlide_write_module.

Changes one form's design and saves the file: add a control, remove one, or set a property on one. Geometry is in points for a UserForm and twips for an Access design. Setting a property to null clears it, putting the control back at its default. Removing a container takes its children with it, so ask the user first. Adding a control does not write its event procedure; do that with xlide_write_module on the form's code module.

Lists the Power Query queries in an Excel workbook: name, group, description, where each loads, and its applied step names. If the M formula cannot be parsed, steps is null with steps_error rather than an empty list. Queries live outside the VBA project, so a plain .xlsx has them too. Call this when asked what a workbook does; a workbook with no macros can still be doing most of its work here. Use offset and next_offset to read large query lists in pages.

Reads one query's M formula, with its description, group, load target and refresh settings. The formula is the let ... in expression as the Advanced Editor shows it. start_line and end_line read a slice of a long formula; the content_token always describes the whole query. If applied steps cannot be read, steps is null and steps_error gives the reason; the M formula remains available.

Changes a workbook's Power Query and saves it. action='set' replaces a query's M formula, creating it if it does not exist; 'rename' renames it and rewrites the queries that reference it by name; 'remove' deletes it and everything that loaded it onto a sheet, which has no undo, so ask the user first. 'load' puts a query's result on a worksheet and 'unload' takes it back off. Loading needs the column names, because writing the connection means naming the columns and knowing them means running the query, which nothing here does; Excel settles them against the real result on the first refresh. A query already loaded keeps its rows until Excel refreshes it. Pass expected_content_token from xlide_read_query to refuse a change if that query changed meanwhile.

Lists the worksheets in an Excel file with their used ranges, whether each is hidden, and the pivot tables on each, the chart sheets, and the workbook's named ranges. Call this before reading cells, so the range you ask for is one that holds data. On .xlsx, .xlsm and .xlam the file also supplies pivot tables, chart sheets and named ranges. For .xlsb and .xls, Windows with Excel is required; that path surveys sheet names, used ranges and visibility only. Unreadable visibility or pivot metadata is marked unknown with hidden_error or pivot_tables_error. A malformed Excel survey is refused rather than returned as a partial sheet list.

Reads a range of cells from a worksheet and returns a grid of values, formulas, both, or the text each cell shows under its number format. On .xlsx, .xlsm and .xlam, values are what Excel last calculated and stored; calculate=true works formulas out in memory with pyOfficeEditor's engine and names cells it could not work out. A failed formatted or rich-text read names the cell and refuses rather than returning an empty value. On .xlsb and .xls, Windows with Excel is required and only calculated values are available, not formulas or formatted text. A partial grid from Excel is refused. At most 20,000 cells per call.

Works out what a formula would give in a cell of a workbook, without writing it there: to check a formula before xlide_write_cells, or to ask the workbook a question, such as =SUMIFS(Sales[Amount],Sales[Region],"West"). Uses pyOfficeEditor's formula engine, 493 of Excel's functions, with the workbook's cells as they stand. A formula written for one cell answers with one value, as Excel would give it there. Changes nothing. .xlsx, .xlsm and .xlam.

Lists what sits on a worksheet's drawing layer: buttons, form controls, AutoShapes, text boxes, pictures, charts and groups, each with the cells it covers, its position in points and, where it has one, the macro a click runs. A form control also carries what it holds: a check box's state, a list's chosen item, a spinner's value and bounds, the cell it is linked to. Call it when asked how a workbook is started, or before renaming a Sub: a button's OnAction names a procedure and nothing rewrites it. ActiveX controls are listed but have no macro; their code is event procedures in the sheet's module. For a crowded sheet, use sheet with offset and next_offset to read later shapes.

Changes which macro an existing shape or button runs when clicked, and saves the workbook. An empty macro clears the link. Use it after writing a Sub, so a button actually calls it, and after renaming one, because nothing rewrites an OnAction. Give the procedure as Proc or Module.Proc; it must already exist in the project, so write it first. To add a button with its macro, or to remove one, use xlide_manage_shape.

Adds a Forms control, an AutoShape, a text box, a line or a picture to a worksheet, or removes one, and saves the workbook. The usual case is a button that runs a macro: kind='button', a caption in text, and the procedure in macro as Proc or Module.Proc, written first. Place it with cell, its top-left cell, or with left and top in points; width and height are points, with a size to start from when left at 0. Check boxes, option buttons, lists and drop-downs take linked_cell, and lists and drop-downs list_range. A Forms control lives in four parts that have to agree, and they are written and removed together. Removing a shape that runs a macro leaves the macro; removing a chart is not offered. Excel workbooks only; .xlsx, .xlsm and .xlam.

Moves, resizes, renames or changes an existing shape's text, alt text or visibility without replacing it. A Forms control can also change its linked cell or list range. Coordinates and sizes are in points; omit any field to leave it unchanged, and pass an empty text or link to clear it. ActiveX, embedded objects and groups cannot be updated. Works on .xlsx, .xlsm and .xlam.

Adds a chart of a block of cells to a worksheet and saves the workbook, written as Excel's Insert Chart writes one of the same type. The block's first row names the series and its first column holds the categories, as Excel reads a selection; a block taller than it is wide makes a series of each column. The data can be on another sheet, as Data!A1:C13. Place it with cell or left and top in points. xlide_list_shapes reports it afterwards with each series' formula.

Writes a rectangular block of values and formulas into a worksheet, starting at one cell, and saves the file. Each row of data is a row of the sheet. A string starting with '=' is written as a formula, as you would type it into Excel 365 with no _xlfn prefixes; anything else is a value. A cell given as {"rich_text": [{"text": "Total ", "bold": true}, {"text": "42"}]} is text in more than one font. A value written over a formula removes that formula, which is what typing into the cell does. On .xlsx, .xlsm and .xlam, only the touched worksheet rows are rewritten; their cached formula results remain stale until Excel opens the file or xlide_read_cells calculates them in memory. Writing .xlsb cells needs Windows with Excel, which recalculates and saves the workbook. Writing .xls cells is not offered. Cells that hold data are refused until allow_overwrite=true; ask the user first.

Lists cells Excel would mark with a green error-checking triangle, such as numbers stored as text, inconsistent formulas, or formulas with cached errors. Returns the rule and cell for each finding. Excel hides ignored findings unless include_ignored=true. Formula-dependent checks use the file's cached results, which may be stale until Excel recalculates and saves it. Works on .xlsx, .xlsm and .xlam; page through long lists with offset and next_offset.

Sorts a range, a table's data rows, or a sheet autofilter's data rows, and saves the workbook. Keys are evaluated in order; each names a column letter for a range or filter, or a header name for a table. A range can keep its first row as a header. Hidden rows keep their places. Formulas, formatting, notes and links move with their rows. This changes existing data order and has no undo in the file: ask the user before calling it. Works on .xlsx, .xlsm and .xlam.

Removes later rows with the same values in the chosen columns, keeping the first row of each set, and saves the workbook. A range inside a table acts on the table and shrinks it. An empty columns list compares every column. This deletes data and cannot be undone in the file: ask the user before calling it. Works on .xlsx, .xlsm and .xlam.

Copies a range to another cell or block, on the same sheet or another sheet, and saves the workbook. Paste Special can select values, formulas, formats, comments, validation, links or other parts; it can also transpose, skip blanks or combine values arithmetically. The destination may hold data, which the paste can replace. Set allow_overwrite=true only after the user agrees to replace it. Formulas and their relative references move as Excel's Copy does. Works on .xlsx, .xlsm and .xlam.

Changes how a range looks: bold and font, fill colour, borders, alignment, number format, and merging. Only what you pass is changed, so each cell keeps the rest of its own format and making a header row bold does not flatten the number formats under it. Colours are RRGGBB or AARRGGBB hex without a leading hash. A number format is an Excel format code such as '#,##0.00' or 'yyyy-mm-dd'; that code is also what decides whether a number is shown as a date. Merging clears values and formulas outside the top-left cell; allow_overwrite is required when that would discard content. Works on .xlsx, .xlsm and .xlam.

Adds, removes, renames, moves, hides, shows, protects or unprotects a worksheet. Renaming rewrites the formulas and defined names that referred to the old name, so nothing breaks. Removing a sheet takes its cells, tables and everything on it, and formulas elsewhere that pointed at it become #REF!, which has no undo: ask the user first. Protecting a sheet stops editing in Excel; it is not a security boundary and the password is trivially recovered. Works on .xlsx, .xlsm, .xlam.

Inserts, deletes, resizes, hides, shows, groups or ungroups whole rows or columns. Inserting and deleting move every reference in the workbook with them: a formula pointing below an inserted row follows it, and one pointing into deleted cells becomes #REF!, exactly as Excel does it. Deleting has no undo, so ask the user first. Widths are in characters and heights in points, which is what Excel's own dialogs use. Works on .xlsx, .xlsm and .xlam.

Lists, adds or removes Excel tables, the ListObjects that Ctrl+T creates. A table names a block so formulas can say Sales[Amount] instead of an address that breaks when rows move, and it is what a Power Query load writes into. action='list' reads them and changes nothing. Adding one takes the column names from the header row of the range you give. Removing one leaves the cells and takes the table, so structured references to it break.

Lists, adds or removes a workbook's defined names. A defined name is what lets a formula say TaxRate rather than Config!$B$7, and VBA reads them too, so removing one can break code as well as formulas. action='list' changes nothing. For a range, qualify refers_to with its sheet and use absolute addresses to avoid following the active sheet or moving with a copied formula, for example Data!$A$1:$A$50.

Lists, adds or clears data validation: what a cell will accept, and the dropdown it shows. kind='list' with formula1 as a comma-separated set of values gives a dropdown; kind='list' with a range reference gives one driven by cells. The other kinds take an operator and one or two formulas, which may be literals or references. Validation stops typing in Excel, not writing through this server, and Excel does not re-check cells that already held a value.

Lists, adds or clears conditional formatting: the rules that colour cells by what is in them. rule='cell_is' with an operator and a value paints cells that compare true; rule='expression' takes a formula written for the top-left cell of the range and applied relatively, the way Excel's 'Use a formula' box works; rule='color_scale' and 'data_bar' are the gradient and in-cell bar. The paint itself is the fill and font arguments, which is what Excel calls a differential format.

Lists, adds or removes hyperlinks on a worksheet. A link either goes out to a target, which is a URL or a file path, or inside the workbook to a location such as 'Summary!A1'. Pass one or the other. The cell's displayed text is separate from the link and is left alone unless you pass display.

Reads how a worksheet is set up to print: orientation, paper size, margins, the print area, the rows or columns repeated on every page, whether it is scaled to fit, and the header and footer. Call it when asked why a sheet prints the way it does, or before changing a layout somebody set up deliberately.

Lists, writes, answers or removes the comments on a worksheet's cells. Excel has two kinds: a note, the yellow box that shows on hover, and a threaded comment, the conversation on the Review tab with replies and a resolved state. action='list' reads both and changes nothing. 'set' writes a note, replacing one already on the cell, or with kind='thread' starts a conversation; 'reply' and 'resolve' act on a thread; 'remove' takes either kind off the cell. Use a note to explain a cell to whoever reads the workbook next.

Lists, sets, reapplies or clears the autofilter on a worksheet or on an Excel table, and hides the rows it filters out. Excel does not apply a filter when it opens a workbook: it shows the rows as the file marks them, so the rows are worked out here, held to what Excel keeps. action='list' reads the filters and changes nothing. 'set' filters one column and keeps what the others already filter by; call it once per column. Give criteria as VBA's Range.AutoFilter spells Criteria1 and Criteria2: '>=10', '=North', '=east', '=' for blanks, '<>' for anything; or top for the top N items (negative for the bottom), or dynamic for aboveAverage, thisMonth, Q1 and the like. 'reapply' filters again after the data changed; 'clear' removes the filter and shows every row.

Writes every VBA module in an Office file to a folder as .bas and .cls files, for source control or review. Previews by default: it reports what it would create, update and leave alone, and writes nothing until apply=true. Only when the user asks for it. Applying a plan leaves unchanged files alone. The exported files are copies: editing one changes nothing inside the Office file until xlide_import_modules runs.

Reads .bas and .cls files from a folder back into an Office file's VBA project and saves it. Previews by default: it reports which modules would change and by how much, and writes nothing until apply=true. A file whose name matches no module creates one. Document modules such as ThisWorkbook are written but never created. Applying an unchanged plan skips the save. After a change, call xlide_analyze.

Lists what changed inside an Office file since a git revision, one entry per VBA module and Power Query, with a unified diff. git diff cannot show this: the file is binary, so a commit that changed one line and one that replaced the whole project look the same. Call this before committing, and to review what an agent or a colleague changed. Worksheet cell values are not compared. Defaults to HEAD; pass any revision git understands. Needs the file to be inside a git repository and tracked in that revision.

Runs a procedure that already exists in an Office file, in an application this server starts and owns, under a deadline. Windows only, with the application installed. The document opens read-only unless read_only=false, and closes without saving unless save=true. Returns the procedure's return value, anything it logged, and, on a VBA error, the error number and message. The failing line and call stack come from instrumentation applied to injected source, so a procedure already in the document does not carry them; run the same code through xlide_run_vba when you need them. A run that exceeds its timeout reports 'timeout' and the application is terminated. Ask the user before running a macro that changes data.

Injects VBA source into a document and calls one procedure from it, under a deadline. Windows only. Use it to check what a piece of code actually does before writing it into a file, or to read something out of a document that no existing macro exposes. With no file_path it runs in a new empty document. Errors come back as data with the failing line and call stack, never as a dialog. Call PyVbaLog "text" from the code to return output; Debug.Print and MsgBox do not work under automation.

Runs the VBA tests in an Office file: every zero-argument procedure whose name starts with Test. Windows only, with the application installed. Each test is run on its own, so one that hangs is reported as a timeout and the rest still run. Returns pass or fail per test with the assertion message, failing line, call stack and any logged output. Use PyVbaAssert and PyVbaAssertEqual in the tests; the harness supplies them.

Asks the real VBA editor to compile a file's project, and reports whether it accepted it. Windows only. This is the compiler's own verdict, where xlide_analyze is a static analyzer's; run the analyzer first, because it is free and needs no Office, and use this when the last word matters. Excel is made visible for the check, because a hidden instance does not surface the compile-error dialog and would report a rejection as a pass.

Says whether a file is open in its Office application, in any running instance: read-only or for editing, with unsaved changes or not, and which processes hold it locked. Call it when a write reports the file is locked, before closing anything, or when the user asks. Windows only. Changes nothing.

Opens a file in its Office application on the user's screen, for them to see or work in: after a change they should look at, or to put back a copy xlide_close_in_app closed. Already open, it is brought forward instead. read_only opens a copy that cannot be saved over the file, and new_instance a separate Excel or Word the user's other files are not in. bring_to_front=false reopens it behind whatever the user is doing. Macros follow the user's Trust Center settings, as for a file they open themselves. Windows only.

Closes a file in the Office application the user has it open in, which frees it for a write. Only that file: the application stays, unless this server started the instance and nothing else is open in it. A copy holding unsaved work is left open and reported, unless save_changes saves it first or discard_changes closes it without saving; losing the user's work is their decision, so ask them. When the application does not answer, or the file stays locked, end_process ends the process Windows says holds the file, and every unsaved document in that process is lost with it: ask the user first. Where the user was in the file is remembered, and xlide_open_in_app puts them back there. Windows only.

Lists the running xlide_vbide sessions this machine can reach: one per Office process that has opened the Visual Basic Editor with the add-in loaded. Use it to find out whether the user has a live editor before asking about what is on their screen. Windows only, and the add-in's local API has to be switched on by the user. Each session is probed before it is listed, because a discovery file outlives the process that wrote it.

What the running Visual Basic Editor is doing right now: the module and project on screen, whether the project is in break mode, whether there are unsaved edits, the procedure the caret is in, and whether the analyzer engine is answering. Use it when the user asks about what they are looking at, or before suggesting an edit to a module they may have unsaved changes in.

Calls one read route on a running xlide_vbide session and returns its JSON. Start with route='agent', which answers with the session's own route table and what each one is for. Allowed routes: agent, agent/examples, agent/routes, analyzer, doctor, engine, model, native, project, projects, state, stats, windows. Routes that drive the editor are deliberately not reachable here.

Reads a module's text as the running editor holds it, including edits the user has not saved. This is the one read that can differ from xlide_read_module, and the difference is exactly the user's unsaved work. Use it to see what they are actually working on; use xlide_read_module for what is in the file. surface_only=true reads the modern editor's own copy instead, which exists only for a module the user has open in a tab. start_line and end_line read a slice of long live source; content_token describes the whole live module.