[
{
"path": ".gitattributes",
"content": "# Auto detect text files and perform LF normalization\n* text=auto\n"
},
{
"path": ".gitignore",
"content": "# Prerequisites\n*.d\n\n# Compiled Object files\n*.slo\n*.lo\n*.o\n*.obj\n\n# Precompiled Headers\n*.gch\n*.pch\n\n# Compiled Dynamic libraries\n*.so\n*.dylib\n\n# Fortran module files\n*.mod\n*.smod\n\n# Compiled Static libraries\n*.lai\n*.la\n*.a\n\n# Executables\n*.out\n*.app\n\n# Visual studio stuff\n.vs\nbuild/\npackages/\ngraveyard/\n*.vcxproj.user\n.vscode\n\n# Other caches\n__pycache__\n.ipynb_checkpoints\n\n# External libraries\n/external/python/\n/external/sqlite\n/external/pybind11-stubgen\n/external/CTPL\n/external/tomlplusplus\n/external/spdlog\n/external/pybind11\n/external/rdcfswatcher\n/external/asmjit\n/external/winreg\n/docs/source/_build\n\n~$*"
},
{
"path": ".readthedocs.yml",
"content": "# .readthedocs.yml\n# Read the Docs configuration file\n# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details\n\n# Required\nversion: 2\n\n# Build documentation in the docs/ directory with Sphinx\nsphinx:\n configuration: docs/source/conf.py\n\nbuild:\n os: \"ubuntu-22.04\"\n tools:\n python: \"3.11\"\n \npython:\n install:\n - requirements: docs/requirements.txt"
},
{
"path": ".runsettings",
"content": "\n\n \n \n build/x64/Debug\n \n \n\n"
},
{
"path": "FUNDING.yml",
"content": "github: [cunnane]"
},
{
"path": "LICENSE",
"content": "Apache License\n\n Copyright 2020 Steven Cunnane\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n"
},
{
"path": "README.md",
"content": "\nxlOil\n=====\n\nxlOil provides framework for interacting with Excel in different programming\nlanguages. It gives a way to write functions in a language and have them \nappear in Excel as worksheet functions or macros or have them control GUI elements. \nFor example, the Python bindings can replace VBA in almost all use cases \nand even provide functionality not available from VBA.\n\nxlOil is designed to have very low overheads when calling your worksheet \nfunctions.\n\nxlOil supports different languages via plugins. The languages currently \nsupported are:\n\n- C++\n- Python\n- SQL\n\nIn addition there is *xlOil_Utils* which contains some handy tools which Microsoft\nnever quite got around to adding.\n\nThe latest stable documentation is here: https://xloil.readthedocs.io/en/stable.\n\nxlOil features\n--------------\n\n* Python\n - Concise syntax to declare an Excel function\n - Optional type checking of function parameters\n - Supports keyword arguments\n - Choice of globally declared functions or code modules limited to a single workbook\n like VBA workbook-level functions\n - Tight integration with *numpy* - very low overheads for array functions\n - Understands python tuples, lists, dictionarys and *pandas* dataframes\n - Async functions\n - RTD functions and on-the-fly RTD server creation\n - Macro type functions which write to ranges on the sheet\n - Access to the Excel Application object and the full Excel object model\n - Drive Excel through COM automation\n - Hook Excel events\n - Pass any python object back to Excel and back into another function\n - Simple add-in deployment\n - Two-way connection to *Jupyter* notebooks: run worksheet functions in *Jupyter* and query variables\n in the *jupyter* kernel\n - Create Ribbon toolbars and Custom Task Panes\n - Return *matplotlib* plots and images from worksheet functions\n* C++\n - Safe and convenient wrappers around most things in the C-API\n - Concise syntax to declare Excel functions: registration is automatic\n - Deal with Excel variants, Ranges, Arrays and strings in a natural C++ fashion\n - Object cache allows returning opaque objects to Excel and passing them back to other functions\n - Simplified RTD server creation\n - RTD-based background calculation\n - Create Ribbon toolbars and Custom Task Panes \n* SQL\n - Create tables from Excel ranges and arrays\n - Query and join them with the full sqlite3 SQL syntax\n* Utils: very fast functions to:\n - Sort on multiple columns\n - Split and join strings\n - Make arrays from blocks\n\n\nSupporting other languages\n--------------------------\n\nYou can use xlOil as an end-user of these plugins or you can use it to write\nyou own language bindings (and ideally add them to the repo)."
},
{
"path": "Version.txt",
"content": "0.22.1\n"
},
{
"path": "config/xloil.ini",
"content": "#\n######## xlOil Settings #########\n#\n# This is a TOML file.\n#\n#################################\n#\n[Addin]\n\n##### Plugins to load\n#\n# Load these plugins. The directory containing xloil.dll is searched\n# first, then the normal DLL search path order.\n#\nPlugins=[\"xlOil_Python\", \"xlOil_SQL\", \"xlOil_Utils\"]\n\n#\n# Load any plugins in the same directory as the core dll which \n# match this pattern.\n#\n#PluginSearchPattern=\"xloil_*.dll\"\n\n\n##### Log file settings \n#\n# Intensity of logging, choose from:\n# \"trace\", \"debug\", \"info\", \"warning\", \"error\", \"critical\", \"off\"\n#\nLogLevel=\"warning\"\n\n#\n# Level at which xlOil will pop up a log window to display recent \n# log entries\n#\nLogPopupLevel=\"error\"\n\n#\n# Level at which xlOil will flush the log file to disk, lower levels\n# decrease performance but can be useful for debugging crashes\n#\n#LogFlushLevel=\"warning\"\n\n#\n# The log file is created at .log and in the same \n# directory unless specified below\n#\n#LogFile=\"my.log\"\n\n#\n# Log file rotation is controlled by these two parameters. A single\n# log file can grow to the *LogMaxSize* in Kb. Once this limit is\n# reached, a new blank log file is started, existing old log files\n# are renamed and the oldest is deleted to ensure maximum of \n# *LogNumberOfFiles* files.\n# \n#LogMaxSize=512\n#LogNumberOfFiles=2\n\n# If you have an ini file at %APPDATA%\\xlOil\\xlOil.ini, the core xlOil.dll\n# is loaded using those settings before any other xlOil-based XLL. Since only one \n# instance of xlOil can be hosted in Excel, one settings file must take precedence. \n# The assumption is that if you have xlOil installed, you want those settings to \n# be the primary ones. The below option, when used in a XLL-specific ini file,\n# allows it to be loaded before the core.\n# LoadBeforeCore=False\n\n##### Date\n#\n# The date formats xlOil will attempt to parse for a string to date\n# conversion. Syntax follows C++ get_time here: \n# https://en.cppreference.com/w/cpp/io/manip/get_time\n# Note the date parsing is case sensitive because get_time is case \n# sensitive on Windows.\n#\nDateFormats=[\"%Y-%m-%d\", \"%Y%b%d\"]\n\n# \n# The key XLOIL_PATH is edited by the xlOil_Install powershell script\n# Note: Use [[]] syntax because the order of Environment variables matters\n#\n[[Addin.Environment]]\nXLOIL_PATH=\"\"\n[[Addin.Environment]]\nPATH='''%PATH%;%XLOIL_PATH%'''\n\n\n##### Python Plugin Settings\n#\n[xlOil_Python]\n#\n# Python modules to load on start up. Must be on python's sys.path.\n# xlOil provides the following optional modules:\n# * xloil.xloil_ribbon: adds a ribbon toolbar with some useful functions\n# * xloil.jupyter: adds jupyter interaction\n#\nLoadModules=[\"xloil.xloil_ribbon\"]\n\n#\n# On workbook open, look for a python file matching this template \n# where * is replaced by the Excel workbook name\n#\nWorkbookModule=\"*.py\"\n\n#\n# Look for a module matching this pattern in the directory of the \n# XLL when it is loaded where '*' is replaced with the addin name.\n# The default is \"*.py\" which means an ini file is optional for a \n# simple addin\n#\n#AddinModule=\"*.py\"\n\n#\n# Calls Py_SetPath before initialising python. This allows explict\n# specification of python's sys.path rather than using the usual\n# search routine, which overrides any setting of PYTHONPATH.\n# Generally this option is not required.\n#\n#SetSysPath='''.'''\n\n#\n# Sets the library for COM support. This is used by the `xloil.app` \n# and `to_com` functions although can be override on a per-call basis.\n# The default is 'win32com', 'comtypes' is also available. \n#\n#ComLib=\"comtypes\"\n\n#\n# Selects the debugger to use. The choices are:\n# * Visual Studio 2019+ : no need to pre-select this, just attach to \n# a running Excel process\n# * VS Code: choose `vscode` or `debugpy`. The `DebugPyPort` attribute\n# then determines the port on which the server listens.\n# * Pdb: choose 'pdb'\n#\nDebugger = \"\"\n\n#\n# Determines the port on which the server listens.\n# \nDebugPyPort = \"5678\"\n\n#\n# By default xlOil loads python modules in a background thread when the addin\n# starts up or a local worksheet module is loaded. This avoids blocking the \n# UI but can lead to #NAME! errors if the a workbook is calculated before\n# the relevant functions are registered. Set UseLoaderThread to false to \n# disable background loading\n# \n#UseLoaderThread=false\n\n\n#\n# When error propagation is enabled, if any function argument is an error code \n# (#N/A!, #NUM!, etc.) that error code is given as the function's return value,\n# otherwise all argument values are handled by the function. Error propagation \n# is consistent with how Excel built-in functions handle errors, it improves \n# performance in the presence of error codes and it allow's Excel's error tracing\n# to function.\n#\n# Currently this setting is respected only by the xlOil_Python plugin.\n#\n#ErrorPropagation=false\n\n\n#\n# List of path prefixes which will be ignored for autoreloading on file \n# modification detection.\n#\n#AutoReloadExcludePaths = []\n\n\n##### Python Environment\n#\n# We need to set the python environment paths. Usually this is done automatically \n# by `xloil install` or `xloil create` or the ribbon.\n#\n# Usually just set PYTHONEXECUTABLE - python should be able to figure out the rest.\n# xlOil also uses this variable to help detect the presence of a virtual Environment. \n# Alternatively set the PYTHONPATH, PYTHONHOME and PATH directly as required by your\n# distribution.\n#\n# Note environment vars can be set by dynamically expanding a registry key.\n#\n[[xlOil_Python.Environment]]\n\t#\n\t# Tells python to do case-insensitve module name lookup and so minimises \n\t# surprises on windows when creating workbook and addin modules. Recommended!\n\t#\n PYTHONCASEOK=\"1\"\n\n\t#\n\t# If this environment variable is set, xlOil tries to load the corresponding\n\t# pythonXY.dll as the interpreter. If unset or blank, xlOil uses the first python \n\t# version discovered using the paths set below.\n\t# \n\tXLOIL_PYTHON_VERSION=\"\"\n\n\t#\n\t# Additional paths to add to python's sys.path. Prefer to add user search\n\t# paths here and reserve the PYTHONPATH setting below for system paths. \n\t# (We make the empty value a semi-colon so that the variable exists \n\t# for the environment variable expansion below)\n\tXLOIL_PYTHON_PATH=\";\"\n\n[[xlOil_Python.Environment]]\n\t\n\t#\n\t# PYTHONEXECUTABLE should point to the python.exe of the current environment.\n\t# Note it is possible to dynamically expand registry keys contained in angle \n\t# brackets <>.\n\t#\n\tPYTHONEXECUTABLE=''''''\n\t\n\tPYTHONPATH='''%PYTHONPATH%;%XLOIL_PYTHON_PATH%'''"
},
{
"path": "config/xloil_local.ini",
"content": "#\n######## xlOil Dev Settings ###########################################\n#\n# This is a version of xlOil.ini which is copied to the build directory\n# when xloil.xll is built. Its purpose is to configure dev settings \n# without accidentally overwriting the distriuted xloil.ini file\n#\n#######################################################################\n#\n[Addin]\n\n##### Plugins to load\n#\n# Load these plugins. The directory containing xloil.dll is searched\n# first, then the normal DLL search path order.\n#\nPlugins=[\"xlOil_Python\", \"xlOil_SQL\", \"xlOil_Utils\"]\n\n##### Log file settings \n#\n# Intensity of logging, choose from:\n# \"trace\", \"debug\", \"info\", \"warning\", \"error\", \"critical\", \"off\"\n#\nLogLevel=\"trace\"\n\n#\n# Level at which xlOil will pop up a log window to display recent \n# log entries\n#\nLogPopupLevel=\"error\"\n\n#\n# Level at which xlOil will flush the log file to disk, lower levels\n# decrease performance but can be useful for debugging crashes\n#\n#LogFlushLevel=\"warning\"\n\n\n#\n# The log file is created at .log and in the same \n# directory unless specified below\n#\n#LogFile=\"my.log\"\n\n#\n# Log file rotation is controlled by these two parameters. A single\n# log file can grow to the *LogMaxSize* in Kb. Once this limit is\n# reached, a new blank log file is started, existing old log files\n# are renamed and the oldest is deleted to ensure maximum of \n# *LogNumberOfFiles* files.\n# \n#LogMaxSize=512\n#LogNumberOfFiles=2\n\n\n# If you have an ini file at %APPDATA%\\xlOil\\xlOil.ini, the core xlOil.dll\n# is loaded using those settings before any other xlOil-based XLL. The assumption\n# is that you have xlOil installed, but since only one instance of xlOil \n# can be hosted in Excel, one settings file must take precedence. The below option\n# allows an XLL to be loaded before the core.\n# LoadBeforeCore=false\n\n##### Date\n#\n# The date formats xlOil will attempt to parse for a string to date\n# conversion. Syntax follows C++ get_time here: \n# https://en.cppreference.com/w/cpp/io/manip/get_time\n# Note the date parsing is case sensitive because get_time is case \n# sensitive on Windows.\n#\nDateFormats=[\"%Y-%m-%d\", \"%Y%b%d\"]\n\n# \n# The key XLOIL_PATH is edited by the xlOil_Install powershell script\n# Note: Use [[]] syntax because the order of Environment variables matters\n#\n#[[Addin.Environment]]\n#XLOIL_PATH=\"\"\n#[[Addin.Environment]]\n#PATH='''%PATH%;%XLOIL_PATH%'''\n\n\n##### Python Plugin Settings\n#\n[xlOil_Python]\n#\n# Python modules to load on start up. Must be on python's sys.path\n#\nLoadModules=[\"xloil.xloil_ribbon\"]\n\n#\n# On workbook open, look for a python file matching this template \n# where * is replaced by the Excel workbook name\n#\nWorkbookModule=\"*.py\"\n\n#\n# Look for a module matching this pattern in the directory of the \n# XLL when it is loaded where '*' is replaced with the addin name.\n# The default is \"*.py\" which means an ini file is optional for a \n# simple addin\n#\n#AddinModule=\"*.py\"\n\n#\n# Calls Py_SetPath before initialising python. This allows explict\n# specification of python's sys.path rather than using the usual\n# search routine, which overrides any setting of PYTHONPATH.\n# Generally this option is not required.\n#\n#SetSysPath='''.'''\n\n#\n# Sets the library for COM support. This is used by the `xloil.app` \n# and `to_com` functions although can be override on a per-call basis.\n# The default is 'win32com', 'comtypes' is also available. \n#\n#ComLib=\"comtypes\"\n\n#\n# Selects the debugger to use. The choices are:\n# * Visual Studio 2019+ : no need to pre-select this, just attach to \n# a running Excel process\n# * VS Code: choose `vscode` or `debugpy`. The `DebugPyPort` attribute\n# then determines the port on which the server listens.\n# * Pdb: choose 'pdb'\n#\nDebugger = \"\"\n\n#\n# Determines the port on which the server listens.\n# \nDebugPyPort = \"5678\"\n\n#UseLoaderThread=false\n\nErrorPropagation=false\n\n\n##### Python Environment\n#\n# We need to set the python environment paths. Usually this is done automatically \n# by `xloil install` or `xloil create` or the ribbon.\n#\n# Usually just set PYTHONEXECUTABLE - python should be able to figure out the rest.\n# xlOil also uses this variable to help detect the presence of a virtual Environment. \n# Alternatively set the PYTHONPATH, PYTHONHOME and PATH directly as required by your\n# distribution.\n#\n# Note environment vars can be set by dynamically expanding a registry key.\n#\n[xlOil_Python.Environment]\n \n\tPYTHONCASEOK=\"1\"\n\n\t#\n\t# If this environment variable is set, xlOil tries to load the corresponding\n\t# pythonXY.dll as the interpreter. If unset or blank, xlOil uses the reported\n\t# python version of the interpreter in the first python dist found.\n\t# \n\tXLOIL_PYTHON_VERSION=\"\"\n\n #\n\t# PYTHONEXECUTABLE should point to the python.exe of the current environment.\n\t# Note it is possible to dynamically expand registry keys contained in angle \n\t# brackets <>.\n\t#\n\tPYTHONEXECUTABLE='''D:\\lib\\conda311\\python.exe'''\n\t#PYTHONEXECUTABLE=''''''\n\t\n\tXLOIL_PYTHON_PATH='''D:\\lib'''\n\n\tPYTHONPATH='''%PYTHONPATH%;D:\\lib'''\n"
},
{
"path": "config/xloil_local_32.ini",
"content": "#\n######## xlOil Dev Settings ###########################################\n#\n# This is a version of xlOil.ini which is copied to the build directory\n# when xloil.xll is built. Its purpose is to configure dev settings \n# without accidentally overwriting the distriuted xloil.ini file\n#\n#######################################################################\n#\n[Addin]\n\n##### Plugins to load\n#\n# Load these plugins. The directory containing xloil.dll is searched\n# first, then the normal DLL search path order.\n#\nPlugins=[\"xlOil_Python\", \"xlOil_SQL\", \"xlOil_Utils\"]\n\n##### Log file settings \n#\n# Intensity of logging, choose from:\n# \"trace\", \"debug\", \"info\", \"warning\", \"error\", \"critical\", \"off\"\n#\nLogLevel=\"trace\"\n\n#\n# Level at which xlOil will pop up a log window to display recent \n# log entries\n#\nLogPopupLevel=\"error\"\n\n#\n# The log file is created at .log and in the same \n# directory unless specified below\n#\n#LogFile=\"my.log\"\n\n#\n# Log file rotation is controlled by these two parameters. A single\n# log file can grow to the *LogMaxSize* in Kb. Once this limit is\n# reached, a new blank log file is started, existing old log files\n# are renamed and the oldest is deleted to ensure maximum of \n# *LogNumberOfFiles* files.\n# \n#LogMaxSize=512\n#LogNumberOfFiles=2\n\n\n# If you have an ini file at %APPDATA%\\xlOil\\xlOil.ini, the core xlOil.dll\n# is loaded using those settings before any other xlOil-based XLL. The assumption\n# is that you have xlOil installed, but since only one instance of xlOil \n# can be hosted in Excel, one settings file must take precedence. The below option\n# allows an XLL to be loaded before the core.\n# LoadBeforeCore=false\n\n##### Date\n#\n# The date formats xlOil will attempt to parse for a string to date\n# conversion. Syntax follows C++ get_time here: \n# https://en.cppreference.com/w/cpp/io/manip/get_time\n# Note the date parsing is case sensitive because get_time is case \n# sensitive on Windows.\n#\nDateFormats=[\"%Y-%m-%d\", \"%Y%b%d\"]\n\n# \n# The key XLOIL_PATH is edited by the xlOil_Install powershell script\n# Note: Use [[]] syntax because the order of Environment variables matters\n#\n#[[Addin.Environment]]\n#XLOIL_PATH=\"\"\n#[[Addin.Environment]]\n#PATH='''%PATH%;%XLOIL_PATH%'''\n\n\n##### Python Plugin Settings\n#\n[xlOil_Python]\n#\n# Python modules to load on start up. Must be on python's sys.path\n#\nLoadModules=[\"xloil.xloil_ribbon\", \"excelfunc\"]\n\n#\n# On workbook open, look for a python file matching this template \n# where * is replaced by the Excel workbook name\n#\nWorkbookModule=\"*.py\"\n\n#\n# Look for a module matching this pattern in the directory of the \n# XLL when it is loaded where '*' is replaced with the addin name.\n# The default is \"*.py\" which means an ini file is optional for a \n# simple addin\n#\n#AddinModule=\"*.py\"\n\n#\n# Calls Py_SetPath before initialising python. This allows explict\n# specification of python's sys.path rather than using the usual\n# search routine, which overrides any setting of PYTHONPATH.\n# Generally this option is not required.\n#\n#SetSysPath='''.'''\n\n#\n# Sets the library for COM support. This is used by the `xloil.app` \n# and `to_com` functions although can be override on a per-call basis.\n# The default is 'win32com', 'comtypes' is also available. \n#\n#ComLib=\"comtypes\"\n\n#\n# Selects the debugger to use. The choices are:\n# * Visual Studio 2019+ : no need to pre-select this, just attach to \n# a running Excel process\n# * VS Code: choose `vscode` or `debugpy`. The `DebugPyPort` attribute\n# then determines the port on which the server listens.\n# * Pdb: choose 'pdb'\n#\nDebugger = \"\"\n\n#\n# Determines the port on which the server listens.\n# \nDebugPyPort = \"5678\"\n\n#UseLoaderThread=false\n\n##### Python Environment\n#\n# We need to set the python environment paths. Usually this is done automatically \n# by `xloil install` or `xloil create` or the ribbon.\n#\n# Usually just set PYTHONEXECUTABLE - python should be able to figure out the rest.\n# xlOil also uses this variable to help detect the presence of a virtual Environment. \n# Alternatively set the PYTHONPATH, PYTHONHOME and PATH directly as required by your\n# distribution.\n#\n# Note environment vars can be set by dynamically expanding a registry key.\n#\n[xlOil_Python.Environment]\n \n\tPYTHONCASEOK=\"1\"\n\n\t#\n\t# If this environment variable is set, xlOil tries to load the corresponding\n\t# pythonXY.dll as the interpreter. If unset or blank, xlOil uses the reported\n\t# python version of the interpreter in the first python dist found.\n\t# \n\tXLOIL_PYTHON_VERSION=\"\"\n\n #\n\t# PYTHONEXECUTABLE should point to the python.exe of the current environment.\n\t# Note it is possible to dynamically expand registry keys contained in angle \n\t# brackets <>.\n\t#\n\tPYTHONEXECUTABLE='''D:\\lib\\Python311-32\\python.exe'''\n\t#PYTHONEXECUTABLE=''''''\n\n\tXLOIL_PYTHON_PATH='''D:\\lib'''\n\n\tPYTHONPATH='''%PYTHONPATH%;D:\\lib'''\n"
},
{
"path": "docs/make.cmd",
"content": "@ECHO OFF\n\npushd %~dp0\n\nREM Command file for Sphinx documentation\n\nif \"%SPHINXBUILD%\" == \"\" (\n\tset SPHINXBUILD=sphinx-build\n)\n\nif \"%1\" == \"\" goto help\n\nset XLOIL_SOLN_DIR=%~dp0..\nset DOC_BUILD_DIR=%XLOIL_SOLN_DIR%\\build\\docs\nset PY_PACKAGE_DIR=%XLOIL_SOLN_DIR%\\libs\\xlOil_Python\\Package\nset SOURCEDIR=%~dp0\\source\nset PATH=%PATH%;C:\\Program Files\\doxygen\\bin\n\n%SPHINXBUILD% >NUL 2>NUL\nif errorlevel 9009 (\n\techo.\n\techo.The 'sphinx-build' command was not found. Make sure you have Sphinx\n\techo.installed, then set the SPHINXBUILD environment variable to point\n\techo.to the full path of the 'sphinx-build' executable. Alternatively you\n\techo.may add the Sphinx directory to PATH.\n\techo.\n\techo.If you don't have Sphinx installed, grab it from\n\techo.http://sphinx-doc.org/\n\texit /b 1\n)\n\nmkdir \"%DOC_BUILD_DIR%\"\n\nif \"%1\" == \"doxygen\" goto doxygen\n\nif \"%1\" == \"-bin\" (\n set XLOIL_BIN_DIR=%XLOIL_SOLN_DIR%\\build\\%2\n shift\n shift\n)\n\nREM Generate the doc stubs: since we can import the core pyd locally, this is\nREM really just for ReadTheDocs\nif exist \"%PY_PACKAGE_DIR%\\generate_stubs.py\" (\n\techo.Generating doc stubs for xloil_core\n\tpython \"%PY_PACKAGE_DIR%\\generate_stubs.py\"\n)\n\nREM It's very important to pass the -E argument to sphinx, otherwise it does\nREM not notice changes to docstrings in python modules and generates the \nREM wrong documentation\n\nREM Set READTHEDOCS so we get consistency with the RTD online version\nset READTHEDOCS=1\n%SPHINXBUILD% -M %1 \"%SOURCEDIR%\" \"%DOC_BUILD_DIR%\" %SPHINXOPTS% -E -W --keep-going %O%\nset READTHEDOCS=\ngoto end\n\n\n:doxygen\n\npushd source\n\nREM For some reason doxygen can't create directories itself\nmkdir \"%DOC_BUILD_DIR%\\doxygen\\html\\doxygen\"\nmkdir \"%DOC_BUILD_DIR%\\doxygen\\xml\\doxygen\"\n\nREM Need to reverse slashes for doxygen because life is tough\nset \"XLO_SOLN_DIR=%XLOIL_SOLN_DIR:\\=/%\"\ndoxygen xloil.doxyfile\npopd\ngoto end\n\n\n:help\n%SPHINXBUILD% -M help %SOURCEDIR% %DOC_BUILD_DIR% %SPHINXOPTS% %O%\n\n:end\npopd\n"
},
{
"path": "docs/requirements.txt",
"content": "numpy\nnumpydoc\nautodocsumm\nsphinx-rtd-theme \ndocutils>=0.16 \nsphinx_rtd_theme\nautodocsumm"
},
{
"path": "docs/source/Concepts.rst",
"content": "==============\nxlOil Concepts\n==============\n\nThis document explains some of the key xlOil concepts shared accross different languages\n\n.. contents::\n :local:\n\n\nExcel Functions (UDFs)\n----------------------\n\nExcel supports several classes of user-defined functions:\n\n- Macros: run at user request, have write access to workbook\n- Worksheet functions: run by Excel's calculation cycle. Several sub-types:\n - Vanilla\n - Thread-safe: can be run concurrently\n - Macro-type: can read from sheet addresses and invoke a wider variety of Excel interface functions\n - Async: can run asynchronously during the calc cycle, but not in the background\n - RTD: (real time data) background threads which push data onto the sheet when it becomes available\n - Cluster: can be packaged to run on a remote Excel compute cluster\n\nxlOil currently supports all but Cluster functions.\n\nExcel can pass functions / macros data in one of these types:\n\n- Integer\n- Boolean\n- Floating point\n- String\n- Error, e.g. #NUM!, #VALUE!\n- Empty\n- Array of any of the above\n- Range refering to a worksheet address\n\nThere is no date type. Excel's builtin date functions interpret numbers as days since 1900. \nExcel does not support timezones.\n\n\n.. _core-cached-objects:\n\nCached Excel Objects\n--------------------\n\nxlOil has an internal lookup for Excel values, which is a convenient way of \npassing arrays around a sheet and as arguments to other xlOil functions.\n\nThe function ``=xloRef(A1:B2)`` returns a cache string of the form:\n``[WorkbookName]SheetName!CellRef,#``\n\nThe data can be recovered using ``=xloVal()``. Alternatively,\nthis string can be passed instead of the source range to xlOil functions which\nsupport cache lookups - and for large arrays this is much faster.\n\nExample use cases are:\n\n * Where you might use a named range - to avoid updating references \n in multiple functions when data is appended. Because `xloRef` automatically \n trims the range back to the last non-blank row, it can be pointed to a range\n far larger than the data.\n * To speed up passing the same large array into several functions \n (e.g. multiple lookups from a data table, although consider xlOil_SQL if\n you want to do this).\n\nHowever, there is a disadvantage to using `xloRef`: the cache is cleared when\na workbook is closed, but Excel does not know to recalculate the `xloRef` \nfunctions when the workbook is reopened. Hence you need to force a sheet\nrecalculation using *Ctrl-Alt-F9*.\n\nIn addition to caching arrays, xlOil plugins use the cache to opaquely return\nreferencs to in-memory structures. Although the strings look similar, they \npoint to very different objects and cannot be written to the sheet using `xloVal`.\n\n\n.. _concepts-rtd-async:\n\nRtd / Async\n-----------\n\nIn Excel, RTD (real time data) functions are able to return values independently of Excel's \ncalculation cycle. Excel has supported RTD functions since at least Excel 2002. In Excel \n2010, Excel introduced native async functions.\n\nRTD:\n\n * Pro: operates independently of the calc cycle - true background execution\n * Pro: provides notification when an RTD function call is changed or removed\n * Con: increased overhead compared to native async\n * Con: requires automatic calculation enabled (or repeated presses of F9 until calc is done)\n\nNative async:\n\n * Pro: Less overhead compared to RTD\n * Pro: works with manual calc mode\n * Con: tied to calc cycle, so any interruption cancels all asyncs functions\n\nThe last con is particularly problematic for native async: *any* user interaction with Excel will\ninterrupt the calc, so whilst native async functions can run asynchronously with each other, they\ncannot be used to perform background calculations.\n\n.. _concepts-ribbon:\n\nCustom UI: The Fluent Ribbon\n----------------------------\n\nxlOil allows dynamic creation of Excel Ribbon components. The ribbon is defined by XML\n(surrounded with tags) which should be created with a specialised editor, see the \n*Resources* below. Controls in the ribbon interact with user code via callback handlers. \nThese callbacks pass a variety of arguments and may expect a return value; it is important \nto check that the any callback behaves as per the callback specifications in the *Resources*.\n\nTo pass ribbon XML into Excel, xlOil creates a COM-based add-in in addition to the XLL-based \nadd-in which loads the xlOil core - you can see this appearing in Excel's add-in list in the \nExcel's Options windows.\n\nResources:\n\n * `Microsoft: Overview of the Office Fluent Ribbon `_\n * `Microsoft: Customizing the Office Fluent Ribbon for Developers `_\n * `Microsoft: Custom UI XML Markup Specification `_\n * `Microsoft: Ribbon Callback Specifications `_\n * `Office RibbonX Editor `_\n * `Ron de Bruin: Ribbon Examples files and Tips `_\n\n\n.. _concepts-intellisense:\n\nIntellisense / Function Context Help\n------------------------------------\n\nTo get pop-up function help, install `Excel-DNA Intellisense `_\n\nIn addition to the function wizard, Excel has a function context help which pops up as you type.\nThis is only directly available for built-in functions. Fortunately, Govert of *Excel-DNA* has created\nan add-in which mimics this behaviour for user-defined functions. Download the XLL (with the right bitness)\nfrom the link above and activate it by one of:\n\n 1) Dragging the XLL into Excel (must be done once per session)\n 2) Install it via *Excel* => *Options* => *Addins* => *Manage*. \n 3) Copy it to your `%APPDATA%\\\\Microsoft\\\\Excel\\\\XLSTART` directory.\n\nYou will now get pop-up help for all xlOil plugins functions, including any dynamically registered ones, \nfor example, created with python plugin."
},
{
"path": "docs/source/Core.rst",
"content": "===========\nxlOil Core\n===========\n\nHere we tell you how to get started using xlOil and how to distribute addins\n\n.. _core-getting-started:\n\nGetting Started\n---------------\n\nYou need **Excel 2010** or later on a desktop PC. xlOil will not work with online \nor Mac versions of Office.\n\n.. important::\n\n If you want to use xlOil with python you should install it via `pip`. Stop reading\n this page and go to :doc:`xlOil_Python/GettingStarted`\n\nDownload the binary package (e.g. from gitlab) and unzip to a directory of \nyour choice. \n\nYou can run the `xlOil_Install.ps1` script to install the addin for every\nExcel session, or just drop `xlOil.xll` into any running Excel session\nto load xlOil temporarily.\n\nxlOil should now load when you open Excel, try following \n:any:`sql-getting-started`\n\nTo configure the plugins being loaded, see :any:`core-edit-settings-files`.\nSome plugings, such as the python one, have several paths which must be set \ncorrectly - it will generally be easier to use these plugins by following their\nspecific installation instructions.\n\n.. _core-example-sheets:\n\nExample sheets\n--------------\n\nTo check your setup and see some of the capabilities of xlOil, try:\n:download:`Tests and Examples `.\n\n.. _core-edit-settings-files:\n\nEditing the settings file\n-------------------------\n\nThere is an `xlOil.ini` file linked to the main `xlOil.xll` addin. (This ini file \nis actually parsed as TOML, an extension of the ini format). xlOil searches for\nthis file first in `%APPDATA%/xlOil` then in the directory containing the `xlOil.xll` \naddin. \n\nThe two most important setting in `xlOil.ini` are:\n\n::\n\n ...\n XLOIL_PATH='''C:\\lib\\xloil```\n ...\n Plugins=[\"xloil_Python.dll\", \"xlOil_SQL.dll\"]\n\n``XLOIL_PATH`` allows the `xlOil.xll` addin to locate the main xlOil DLL if the \naddin is being run from a different directory. When the main DLL has loaded, \nxlOil loads the specified plugins. It searches for these plugins first in the \ndirectory containing `xlOil.dll`, then the directory containing the XLL, then \nthe usual DLL search paths. \n\n\nSetting enviroment variables in settings files\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nEach plugin can have an *Environment* section in the settings file. Within this block\ntokens are interpreted as enviroment variables to set. A plugin's environment settings \nare processed before the plugin is loaded. \n\nKeys are interpreted as environement variables to set. Values can reference other enviroment \nvariables by surrounding the name with `%` characters.\n\nIn addition you can pull values from the registry by surrounding the registry\npath with angle brackets `<>`. Leaving a trailing backslash `\\\\` in the \nregistry path fetches the default value for that key.\n\nThe TOML syntax of three single quotes indicates a string literal, this avoids escaping \nall the backslashes.\n\nThe default enviroment block for Python looks like this:\n\n::\n\n [[xlOil_Python.Environment]]\n xlOilPythonVersion=\"3.7\"\n\n [[xlOil_Python.Environment]]\n PYTHONPATH=''''''\n PYTHON_LIB=''''''\n\n [[xlOil_Python.Environment]]\n PATH='''%PATH%;%PYTHON_LIB%;%PYTHON_LIB%\\Library\\bin'''\n\nThe double brackets tell TOML that the order of these declarations is important,\nthis means we can refer to previously set enviroment variables.\n\nIn addition you can pull values from the registry by surrounding the registry\npath with angle brackets `<>`, for example, \n``. \nLeaving a trailing backslash `\\\\` in the registry path fetches the default \nvalue for that key.\n\nTroubleshooting\n---------------\n\nYou may need to tweak your settings file: :any:`core-edit-settings-files`\n\nA common problem is that the COM interface misbehaves by either failing on start-up or failing\nbecause of an open dialog box in Excel. For a start-up fail, unload and reload the addin. \nFor other errors try to close dialog boxes or panes and if that fails, restart Excel.\n\nThe log file\n~~~~~~~~~~~~~\n\nIf xlOil detects a serious load error, it pops up a log window to alert you (this can\nbe turned off). If it succesfully loaded the core DLL a log file will also be created\nnext to `xlOil.ini`, which by default is in ``%APPDATA%\\xlOil``. If xlOil loaded, the \nworksheet function `xloLog` can tell you where this file is. A setting in `xlOil.ini` \ncontrols the log level.\n\nManual installation\n~~~~~~~~~~~~~~~~~~~\n\nThe `xlOil_Install.ps1` script does the following:\n\n 1. Check xlOil is not in Excel's disabled add-ins\n 2. Copy xlOil.xll to the ``%APPDATA%\\Microsoft\\Excel\\XLSTART`` directory\n 3. Copy xlOil.ini in the ``%APPDATA%\\xlOil``` directory\n 4. Check VBA Object Model access is allowed in \n `Excel > File > Options > Trust Center > Trust Center Settings > Macro Settings``\n\n\nManual removal\n~~~~~~~~~~~~~~\n\nShould you need to force remove xlOil, do the following:\n\n 1. Remove *xlOil.xll* from ``%APPDATA%\\Microsoft\\Excel\\XLSTART``\n 2. Remove the directory ``%APPDATA%\\xlOil```\n\nIf you have added *xlOil.xll* or another xll add-in (xlOil does not do this by default)\nand you want to remove it go to:\n\n 1. `Excel > File > Options > Add-ins > Manage Excel Addins`\n 2. If the previous step fails to remove the addin, start Excel with elevated/admin \n priviledges and retry\n 3. If that fails, try to remove the add-in from the registry key\n ``HKEY_CURRENT_USER\\SOFTWARE\\Microsoft\\Office\\\\Excel\\Options``.\n You should see values *OPEN*, *OPEN1*, etc with add-in names to be loaded. After removing\n a value, you need to rename the others to preserve the numeric sequence.\n 4. If that does not work, also look at this registry key:\n ``HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Office\\\\Excel\\Options``.\n\nNote you may need to run the registry editor with elevated priviledges.\n\nTo really scrub the registry, you may find references to the addin under:\n * `HKEY_CURRENT_USER\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\\\\\Excel\\\\Add-in Manager`\n * `HKEY_CURRENT_USER\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\\\\\Excel\\\\AddInLoadTimes`\n * `HKEY_CURRENT_USER\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\\\\\Excel\\\\Resiliency\\DisabledItems`\n * `HKEY_CURRENT_USER\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\Excel\\\\Addins`\n * `HKEY_CURRENT_USER\\\\SOFTWARE\\\\Microsoft\\\\Office\\\\Excel\\\\AddinsData`\n"
},
{
"path": "docs/source/Developer.rst",
"content": "=======================\nxlOil Development Guide\n=======================\n\nGetting started as developer\n----------------------------\n\n- You need Visual Studio 2022 or newer\n- All xlOil_Core dependencies are already in the `external` folder. Some of them are compressed, \n so unpack them.\n- To build the `xlOil-COM` library you need the ATL headers which can be installed with the Visual\n Studio installer (under C++ development). \n- For debugging, set xlOil_Loader as the target project, with \n command=`` args=`$(OutDir)\\xloil.xll`\n\n\nRelease Instructions\n--------------------\n\n::\n\n cd \\tools\n python stage.py\n\n(Optional) test python wheels with \n\n::\n\n cd \\build\\staging\\pypackage\n pip install dist/xlOil-0.3-cp37-cp37m-win_amd64.whl\n pip uninstall dist/xlOil-0.3-cp37-cp37m-win_amd64.whl\n\nUse twine to upload to PyPI (note you need to ensure twine has the right login\nkeys/secrets):\n\n::\n\n cd \\build\\staging\\pypackage\n\n # (Optional test)\n twine upload --repository-url https://test.pypi.org/legacy/ dist/*\n\n # The real thing\n twine upload dist/*\n"
},
{
"path": "docs/source/Events.rst",
"content": "==================\nxlOil Excel Events\n==================\n\n.. contents::\n :local:\n\nIntroduction\n------------\n\nxlOil allows code to hook into Excel events. The Excel API documentation \n`Excel.Application `_\ncontains more complete descriptions of most of these events, with the exception of the\n`CalcCancelled`, `WorkbookAfterClose`, `XllAdd` and `XllRemove` events which are not part of the\n*Application* object and are provided by xlOil.\n\nFor the syntax used to hook these events, see the individual language documentation.\n\nParameter types\n===============\nMost events use some of the parameter types described below:\n\n* *Workbook name*: passed as a string (not a ``Workbook`` object)\n* *Worksheet name*: passed as a string \n* *Range*: passed as a ``Range`` object\n* *Cancel*: a bool which starts as False If the event handler sets this argument to True,\n further processing of the event will stop\n \nAfterCalculate\n--------------\n\nThis event occurs after all Worksheet.Calculate, Chart.Calculate, QueryTable.AfterRefresh, \nand SheetChange events. It's the last event to occur after all refresh processing and all \ncalc processing have completed, and it occurs after CalculationState is set to xlDone.\nThis event is called if the calculation was interrupted (for example by the user pressing \na key or mouse button).\n\nWorkbookOpen\n------------\nOccurs when a workbook is opened. Takes a single parameter containing the workbook name.\n\nNewWorkbook\n-----------\nOccurs when a new workbook is created. Takes a single parameter containing the workbook name.\n\nSheetSelectionChange\n--------------------\nOccurs when the selection changes on any worksheet (doesn't occur if the selection is on a \nchart sheet). Takes two paramters:\n\n* Worksheet name\n* Target / selected Range\n\nSheetBeforeDoubleClick\n----------------------\nOccurs when any worksheet is double-clicked, before the default double-click action. \nTakes three parameters\n\n * Worksheet name\n * Target - A Range giving cell nearest to the mouse pointer when the double-click occurred.\n * Cancel - False when the event occurs. If the event procedure sets this argument to True, the default \n double-click action isn't performed when the procedure is finished.\n\nSheetBeforeRightClick\n---------------------\nOccurs when any worksheet is right-clicked, before the default right-click action. \nTakes three parameters\n\n * Worksheet name\n * Target - A Range giving the cell nearest to the mouse pointer when the right-click occurred.\n * Cancel - False when the event occurs. If the event procedure sets this argument to True, the default \n right-click action isn't performed when the procedure is finished.\n\nSheetActivate\n-------------\nOccurs when any sheet is activated. Takes a single parameter containing the sheet name.\n\nSheetDeactivate\n---------------\nOccurs when any sheet is deactivated. Takes a single parameter containing the sheet name.\n\nSheetCalculate\n--------------\nOccurs after any worksheet is recalculated or after any changed data is plotted on a chart.\nTakes a single parameter containing the sheet name.\n\nSheetChange\n-----------\nOccurs when cells in any worksheet are changed by the user or by an external link. Takes \ntwo paramters:\n\n* Worksheet name\n* Changed Range\n\nWorkbookActivate\n----------------\nOccurs when any workbook is activated. Takes a single parameter containing the workbook name.\n\nWorkbookDeactivate\n------------------\nOccurs when any workbook is deactivated. Takes a single parameter containing the workbook name.\n\nWorkbookBeforeClose\n-------------------\nOccurs immediately before any open workbook closes. Takes two parameters\n\n * Workbook name\n * Cancel - False when the event occurs. If the event procedure sets this argument to True, the \n workbook doesn't close when the procedure is finished.\n\nThe event is not called for each workbook when Excel exits.\n\nWorkbookBeforeSave\n------------------\nOccurs before any open workbook is saved. Takes three parameters:\n\n * Workbook name\n * SaveAsUI - True if the Save As dialog box will be displayed due to changes made that need to \n be saved in the workbook.\n * Cancel - False when the event occurs. If the event procedure sets this argument to True, the \n workbook isn't save when the procedure is finished.\n\nWorkbookBeforePrint\n-------------------\nOccurs immediately before any open workbook is printed. Takes two parameters\n\n * Workbook name\n * Cancel - False when the event occurs. If the event procedure sets this argument to True, the \n workbook doesn't print when the procedure is finished.\n\nWorkbookAfterClose\n------------------\nExcel's *WorkbookBeforeClose* event is cancellable by the user so it is not possible to know if \nthe workbook actually closed. When xlOil calls `WorkbookAfterClose`, the workbook is certainly \nclosed, but it may be some time since that closure happened. Takes a single parameter containing the \nworkbook name.\n\nThe event is not called for each workbook when xlOil exits. This event is not part of the \n*Excel.Application* API.\n\nWorkbookNewSheet\n----------------\nOccurs when a new sheet is created in any open workbook. The first parameter is the workbook name, \nthe second is the new sheet name.\n\nWorkbookAddinInstall\n--------------------\nOccurs when a workbook is installed as an add-in. Takes a single parameter containing the workbook name.\n\nWorkbookAddinUninstall\n----------------------\nOccurs when any add-in workbook is uninstalled. Takes a single parameter containing the workbook name.\n\nCalcCancelled\n-------------\nCalled when the calculation cycle is cancelled (for example by the user pressing a key or mouse button).\nNative async functions should stop any background calculation when this event is received.\n\nThis event is not part of the *Excel.Application* API.\n\nXllAdd\n------\nTriggered when an XLL related to this instance of xlOil is added by the user using the Addin settings\nwindow. The parameter is the XLL filename.\n\nThis event is not part of the *Excel.Application* API.\n\nXllRemove\n---------\nTriggered when an XLL related to this instance of xlOil is removed by the user using the Addin settings\nwindow. The parameter is the XLL filename.\n\nThis event is not part of the *Excel.Application* API.\n"
},
{
"path": "docs/source/Introduction.rst",
"content": "=====\nxlOil\n=====\n\nxlOil is a framework for linking programming languages with Excel language. \nThat is, a way to write functions in a language of your choice and have them\nappear in Excel as worksheet functions and macros, as well as manipulating\nthe application and GUI similar to VBA.\n\nxlOil is designed to have very low overheads when calling your own worksheet \nfunctions.\n\nxlOil supports different languages via plugins. The languages currently \nsupported are:\n\n- C++\n- Python\n- SQL\n\nIn addition there is :any:`xlOil_Utils` which contains some handy tools which Microsoft\nnever quite got around to adding.\n\nYou can use xlOil as an end-user of these plugins or you can use it to write\nyou own language bindings and contribute.\n\n.. important::\n\n **Start Here:** :any:`core-getting-started`\n\nxlOil features\n--------------\n\n* Python\n - Very concise syntax to declare an Excel function\n - Optional type checking of function parameters\n - Supports keyword arguments\n - Choice of globally declared functions or code modules limited to a single workbook (just\n like VBA workbook-level functions)\n - Tight integration with numpy - very low overheads for array functions\n - Understands python tuples, lists, dictionarys and pandas dataframes\n - Async functions\n - RTD functions and on-the-fly RTD server creation\n - Macro type functions which write to ranges on the sheet\n - Access to the Excel Application object \n - Hook Excel events\n - Pass any python object back to Excel and then back into any python function\n - Simple and quick add-in deployment\n - Two-way connection to Jupyter notebooks: run worksheet functions in Jupyter and query variables\n in the jupyter kernel\n - On-the-fly creation/destruction of COM addin objects and Ribbon UI\n\n* C++\n - Safe and convenient wrappers around most things in the C-API\n - Concise syntax to declare Excel functions: registration is automatic\n - Deal with Excel variants, Ranges, Arrays and strings in a natural C++ fashion\n - Object cache allows returning opaque objects to Excel and passing them back to other functions\n - Async functions\n - RTD functions and on-the-fly RTD server creation\n - On-the-fly creation/destruction of COM addin objects and Ribbon UI\n\n* SQL\n - Create tables from Excel ranges and arrays\n - Query and join them with the full sqlite3 SQL syntax\n\n* Utils: very fast functions to\n - Sort on multiple columns\n - Split and join strings\n - Make arrays from blocks\n\nWhy xlOil was created\n---------------------\n\nProgramming with Excel has no ideal solution. You have a choice of APIs:\n\n- VBA - great integration with Excel, but clunky syntax compared with\n other languages, few common libraries, limited IDE, testing and source \n control very difficult, single-threaded, use not encouraged by MS.\n- C-API - It's C and hence unsafe. The API is also old, has some quirks \n and is missing many features of the other APIs. But it's the fastest\n interface.\n- COM - More fully-featured but slower and strangely missing some features\n of the C-API. It's C++ so still pretty unsafe. Has some unexpected behaviour\n and may fail to respond. Requires COM binding support in your language \n or the syntax is essentially unusuable.\n- .Net API - actually sits on top of COM, the best modern interface\n but only for .Net languages and speed-limited by COM overheads, still missing \n some C-API features.\n- Javascript API - supports Office on multiple devices and operating system, but \n very slow with limited functionality compared to other APIs.\n\nxlOil tries to give you the C and COM APIs blended in a more friendly \nfashion and adds:\n\n- Solution to the \"how to register a worksheet function without a static DLL entry point\" problem\n- Object caching\n- A framework for converting excel variant types to another language and back\n- A convenient way of creating worksheet-scope functions\n- A loader stub\n- Goodwill to all men\n\n\nComparison between xlOil and other Excel Addin solutions\n--------------------------------------------------------\n\nGiven the age of Excel, there are many other solutions for Excel add-in\ndevelopment.\n\nMost available packages are commercial (and quite expensive) so I \ncannot test relative performance with xlOil. They are generally\nfocussed on a single language rather than providing a framework\nfor language bindings as xlOil does.\n\nThe following, likely incomplete, list includes some of the most \nprominent Excel addin software. \n\n- Addin express: (commercial) fully-featured with nice GUI and the support\n seems good as well. Limited to .Net languages, but covers the entire Office\n suite (not just Excel)\n- ExcelDNA: (free) mature, well-regarded and widely used, covers \n almost all Excel API features, but only for .Net languages. I strongly\n recommend this software if you are using .Net languages.\n- XLL Plus: (commercial) seems to be fully-featured with GUI wizards\n to help developers, but only for C++ and the most expensive sofware \n here.\n- PyXLL: (commercial) Python-only. Supports the full range of Excel\n API features and some functionality to run on remote servers.\n- XlWings: (mostly free) Python-only. More mature sofware, but considerably\n slower (2000x in my test case) than xlOil due to use of slower APIs.\n Can only create 'local' functions backed by VBA, so every Excel sheet needs\n to be be a macro sheet with special VBA redirects. This means it is not viable\n for addin deployment. Supports Mac and Python 2.7 (but licence fee required \n for this).\n"
},
{
"path": "docs/source/conf.py",
"content": "# Configuration file for the Sphinx documentation builder.\n#\n# This file only contains a selection of the most common options. For a full\n# list see the documentation:\n# https://www.sphinx-doc.org/en/master/usage/configuration.html\n\n# -- Path setup --------------------------------------------------------------\n\n# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath to make it absolute, like shown here.\n# sys.path.insert(0, os.path.abspath('.'))\n\nimport os\nimport sys\nfrom pathlib import Path\n\n#\n# The default soln_dir and bin_dir paths here are to allow VS code to auto\n# preview the docs. I'm currently not sure how to add environment variables\n# to processes run by VS code.\n#\n\nfile_dir = Path(__file__).parent\nxloil_dir = file_dir.parent.parent\nsoln_dir = Path(os.environ.get(\"XLOIL_SOLN_DIR\", xloil_dir)).resolve()\nbin_dir = Path(os.environ.get(\"XLOIL_BIN_DIR\", xloil_dir / \"build/x64/Debug\")).resolve()\n\nif bin_dir.exists():\n sys.path.append(str(bin_dir))\nsys.path.append(str(soln_dir / \"libs/xlOil_Python/Package\"))\n\n# May as well fail here if we can't find xloil\ntry:\n import xloil\nexcept Exception as e:\n raise Exception(f'{e}. SysPath={sys.path}', e)\n\n# -- Project information -----------------------------------------------------\n\nproject = 'xlOil'\ncopyright = '2022, Steven Cunnane'\nauthor = 'Steven Cunnane'\n\n# The full version, including alpha/beta/rc tags\nrelease = (soln_dir / \"Version.txt\").read_text()\n\n# -- General configuration ---------------------------------------------------\n\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n \"sphinx.ext.autodoc\", \n \"sphinx.ext.autosummary\", \n \"sphinx.ext.autosectionlabel\", \n \"numpydoc\",\n 'autodocsumm'\n ]\n\n# Avoid duplicate label warnings from autosectionlabel\nsuppress_warnings = ['autosectionlabel.*']\n\n# True to prefix each section label with the name of the document it is in, \n# followed by a colon. For example, index:Introduction for a section called \n# Introduction that appears in document index.rst.\nautosectionlabel_prefix_document = True\n\n# Add any paths that contain templates here, relative to this directory.\ntemplates_path = ['_templates']\n\n# List of patterns, relative to source directory, that match files and\n# directories to ignore when looking for source files.\n# This pattern also affects html_static_path and html_extra_path.\nexclude_patterns = []\n\n\n# -- Options for HTML output -------------------------------------------------\n\n# The theme to use for HTML and HTML Help pages. See the documentation for\n# a list of builtin themes.\n\nUSE_READTHEDOCS_THEME = True\nif USE_READTHEDOCS_THEME:\n import sphinx_rtd_theme\n extensions.append('sphinx_rtd_theme')\n html_theme = \"sphinx_rtd_theme\"\nelse:\n html_theme = 'bizstyle'\n\n# Add any paths that contain custom static files (such as style sheets) here,\n# relative to this directory. They are copied after the builtin static files,\n# so a file named \"default.css\" will overwrite the builtin \"default.css\".\nhtml_static_path = []# ['_static']\n\n# A list of paths that contain extra files not directly related to the documentation, \n# such as robots.txt or .htaccess. Relative paths are taken as relative to the \n# configuration directory. They are copied to the output directory.\n#html_extra_path = ['../build/doxygen']\n\nautodoc_default_flags = ['members']\n\n#\n# If autosummary_generate is True, stub .rst files for for items in the autosummary\n# toctree are automatically generated. We prefer to keep a flatter structure.\n#\nautosummary_generate = False\n\n# See https://stackoverflow.com/questions/34216659/\nnumpydoc_show_class_members=False\n\n#\n# Required for readthedocs build as the master_doc seems to default to 'contents' in\n# their environment. Locally sphinx builds fine without this\n#\nmaster_doc = 'index'\n\n# -- Generate examples file ---------------------------------------------------\n#\n# Only do this when XLOIL_BIN_DIR is explicitly set so not on ad-hoc run\n#\nif \"XLOIL_BIN_DIR\" in os.environ:\n import zipfile\n from zipfile import ZipFile\n\n try: os.makedirs('_build')\n except FileExistsError: pass\n\n zipObj = ZipFile('_build/xlOilExamples.zip', 'w', compression=zipfile.ZIP_BZIP2)\n try:\n zipObj.write(soln_dir / \"tests\" / \"AutoSheets\" / \"PythonTest.xlsm\", \"PythonTest.xlsx\")\n zipObj.write(soln_dir / \"tests\" / \"ManualSheets\" / \"python\" / \"PythonTestAsync.xlsm\", \"PythonTestAsync.xlsm\")\n zipObj.write(soln_dir / \"tests\" / \"AutoSheets\" / \"PythonTest.py\", \"PythonTest.py\")\n zipObj.write(soln_dir / \"tests\" / \"AutoSheets\" / \"TestModule.py\", \"TestModule.py\")\n zipObj.write(soln_dir / \"tests\" / \"AutoSheets\" / \"TestSQL.xlsx\", \"TestSQL.xlsx\")\n zipObj.write(soln_dir / \"tests\" / \"AutoSheets\" / \"TestUtils.xlsx\", \"TestUtils.xlsx\")\n \n except FileNotFoundError as err: \n print(\"WARNING: Could not create xlOilExamples.zip due to: \", str(err))\n\n zipObj.close()\n"
},
{
"path": "docs/source/index.rst",
"content": ".. raw:: html\n\n\t\n\nxlOil documentation\n===================\n\n.. toctree::\n\t:maxdepth: 4\n\t:caption: Contents:\n\t:glob:\n\n\tIntroduction\n\tCore\n\tConcepts\n\tEvents\n\txlOil_Core_Functions\n\txlOil_Cpp/index\n\txlOil_Python/index\n\txlOil_SQL/index\n\txlOil_Utils\n\tDeveloper\n\n\nIndices and tables\n==================\n\n* :ref:`genindex`\n* :ref:`search`\n"
},
{
"path": "docs/source/xlOil_Core_Functions.rst",
"content": "=========================\nxlOil Core Functions\n=========================\n\nThis page describes the worksheet functions registered by the xlOil core, which should always \nbe available when xlOil is running.\n\nxloRef: adds a value or array to the cache\n------------------------------------------\n\n.. function:: xloRef(arrayOrRange)\n\n Adds the specified value or range or array to the object cache and returns a string \n reference.\n\n See :any:`core-cached-objects`\n\nxloVal: Retrives a value from the Excel data cache\n--------------------------------------------------\n\n.. function:: xloVal(cacheRefString)\n\n Given a reference string, returns a stored array or value. Cached values \n are not saved with the workbook so will need to be recreated by forcing \n a full recalc (press Ctrl-Alt-F9) when the workbook is opened\n\n See :any:`core-cached-objects`\n\n\nxloHelp: returns help on an xlOil registered function\n------------------------------------------------------\n\n.. function:: xloHelp(functionName)\n\n Returns a two column array containing the help information passed to Excel's \n function wizard when the function was registered. The first row contains \n the function name and the main help string. Subsequent rows contain argument\n names and their associated help.\n\n In the function wizard all help strings are limited to 256 characters. xloHelp\n does not have this limitation. \n\nxloLog: flushes the log file and returns its location\n-----------------------------------------------------\n\n.. function:: xloLog(ShowWindow=FALSE)\n\n The xlOil log is only flushed (written to file) occasionally or when an error \n or warning occurs. Executing this function flushes the log and returns the \n location of the log file (by default this is the same directory as the settings\n file).\n\n Setting the *ShowWindow* parameter causes xlOil's log window to appear. This \n doesn't display the contents of the entire log file but only the most recent log \n messages.\n\n\nxloVersion: returns information on the xlOil version\n----------------------------------------------------\n\n.. function:: xloVersion()\n\n Returns a two-column array of version information."
},
{
"path": "docs/source/xlOil_Cpp/COM.rst",
"content": "=======================\nxlOil C++ Using COM\n=======================\n\nThe root of Excel's COM interface is `Excel.Application `_\nwhich VBA programmers will be familiar with.\n\nThe easiest way to work with it in C++ is by importing the type library into your source file - \nthis allows compile time checks and auto-completion and results in faster code. COM objects\ncan be accessed using 'late-binding' where methods and properties are queried from the object\nat runtime, but this clearly limits performance.\n\nIn xlOil, the appropriate type library can be imported with the *ExcelTypeLib.h* header:\n\n::\n\n #include \n #include \n using namespace xloil;\n\n XLO_FUNC_START(testToday())\n {\n excelApp().Range[L\"A1\"]->NumberFormat = L\"dd-mm-yyyy\";\n }\n XLO_FUNC_END(testToday).macro();\n\nIf *ExcelTypeLib.h* is included before `xlOil.h` it adds COM error handling to any worksheet \nfunctions declared with `XLO_FUNC_START`. This is useful because COM throws its own `_com_error`\nclasses which do not derive from `std::exception`.\n\nI cannot find a specific Excel/COM/C++ tutorial at this time, but the *Excel.Application* API \ndocumentation is comprehensive. \n"
},
{
"path": "docs/source/xlOil_Cpp/CppRtd.rst",
"content": "=======================\nxlOil C++ RTD functions\n=======================\n\nIn Excel, RTD (real time data) functions are able to return values independently of Excel's \ncalculation cycle. The classic example of this is a stock ticker with live prices. This is contrasted \nwith Excel's native async support in :any:`concepts-rtd-async`.\n\n\nExample: Subscription\n---------------------\n\nxlOil wraps the RTD server implementation to make subscription and publication straightfoward as in the \nfollowing example:\n\n.. highlight:: c++\n\n::\n\n #include \n using namespace xloil;\n\n IRtdServer& myRtdServer()\n {\n static shared_ptr ptr = newRtdServer();\n static auto backgroundTask = std::async([]()\n {\n // Somehow fetch live prices here\n ptr->publish(\"SP500\", ExcelObj(123));\n ptr->publish(\"FTSE100\", ExcelObj(456));\n });\n return *ptr;\n }\n\n XLO_FUNC_START(\n getStock(const ExcelObj& ticker)\n )\n {\n auto value = myRtdServer().subscribe(tag.toString().c_str());\n return returnValue(value\n ? *value\n : Const::Error(CellError::NA));\n }\n XLO_FUNC_END(getStock);\n\n\nExample: Background task\n------------------------\n\nThe RTD mechanism can be used to run slow tasks like data fetches or calculations in the background whilst\nthe user continues to interact with Excel. The following demonstrates a simple counter which increments\nstepwise.\n\n.. highlight:: c++\n\n::\n\n #include \n using namespace xloil;\n \n struct Counter : public RtdAsyncTask\n {\n Counter(int iStep) : _iStep(iStep) {}\n\n int _iStep;\n\n // This function arranges for the work to be done in the background, but must\n // exit when the `RtdNotifier` requests it\n std::future operator()(RtdNotifier notify) override\n {\n return std::async([=, step = _iStep]()\n {\n int _count = 0;\n while (!notify.cancelled())\n {\n notify.publish(ExcelObj(_count));\n std::this_thread::sleep_for(std::chrono::seconds(2));\n _count += step;\n }\n });\n }\n\n // When the cell which generated the task is recalculated, xlOil cannot tell\n // whether Excel is calling it with new inputs or RTD triggered the call to get\n // a result. It uses this equality operator to determine if it already has a \n // running task for the given set of inputs\n bool operator==(const IRtdAsyncTask& that_) const override\n {\n const auto* that = dynamic_cast(&that_);\n if (!that)\n return false;\n return _iStep == that->_iStep;\n }\n };\n\n XLO_FUNC_START(\n rtdCounter(const ExcelObj& step)\n )\n {\n auto value = rtdAsync(\n std::make_shared(step.toInt(1)));\n return returnValue(value ? *value : CellError::NA);\n }\n XLO_FUNC_END(rtdCounter);"
},
{
"path": "docs/source/xlOil_Cpp/CustomGUI.rst",
"content": "==============================\nxlOil C++ GUI Customisation\n==============================\n\n.. contents::\n :local:\n\nxlOil allows dynamic creation of Excel Ribbon components and custom task panes. See \n:any:`concepts-ribbon` for background. The code differs slightly depending on whether \nyou are writing a static XLL or an xlOil plugin.\n\nCreating a ribbon in a static XLL\n---------------------------------\n\n.. highlight:: c++\n\n::\n \n void ribbonHandler(const RibbonControl& ctrl) {}\n \n\n struct MyAddin\n {\n std::shared_ptr theComAddin;\n MyAddin()\n {\n // We need this call so that xlOil defers execution of the ribbon creation\n // until Excel's COM interface is ready\n xllOpenComCall([this]()\n {\n auto mapper = [=](const wchar_t* name) mutable { return ribbonHandler; };\n theComAddin = makeAddinWithRibbon(\n L\"TestXlOil\",\n LR\"(\n \n ...\n \n )\", \n mapper);\n });\n }\n };\n XLO_DECLARE_ADDIN(MyAddin);\n\n\nCreating a ribbon in an xlOil plugin\n------------------------------------\n\n.. highlight:: c++\n\n:: \n\n #incude \n\n void ribbonHandler(const RibbonControl& ctrl) {}\n std::shared_ptr theComAddin;\n\n XLO_PLUGIN_INIT(xloil::AddinContext* ctx, const xloil::PluginContext& plugin)\n {\n xloil::linkLogger(ctx, plugin);\n\n auto mapper = [=](const wchar_t* name) mutable { return ribbonHandler; };\n theComAddin = makeAddinWithRibbon(\n L\"TestXlOil\",\n LR\"(\n \n ...\n \n )\", \n mapper);\n\n return 0;\n }\n\n \nCreating a Custom Task Pane\n---------------------------\n\nAfter a COM addin has been created using the ribbon examples above, a custom task pane\ncan be added in the following way.\n\n.. highlight:: c++\n\n:: \n \n std::shared_ptr taskPane(theComAddin->createTaskPane(L\"xloil\"));\n taskPane->setVisible(true);\n\nAn option progid can be passed to `createTaskPane` to create a specific COM object \nas the root of the task pane, if omitted, xlOil uses a simple default object."
},
{
"path": "docs/source/xlOil_Cpp/DynamicRegistration.rst",
"content": "==============================\nxlOil C++ Dynamic Registration\n==============================\n\nTo support registration of functions in other languages, xlOil has the ability to register worksheet\nfunctions generated at runtime. In C++, you usually can create a static entry point for each function\nyou want to register using xlOil macros. These macros end up calling `Excel12(xlfRegister, ...)` and \npass the name of your function. Dynamic registration is a little trickier since `xlfRegister` requires\nthe name of an entry point into your XLL rather than a function pointer. xlOil arranges for such a \nsuitable entry point to exist by generating a small trampoline function in assembler which redirects\nto your function. However, this creates a tiny performance overhead (typically around 8-16 instructions\nincreasing with the number of arguments).\n\n.. highlight:: c++\n\n::\n\n auto regId = RegisterLambda<>(\n [](const ExcelObj& arg1, const ExcelObj& arg2)\n {\n ...\n return returnValue(...);\n })\n .name(\"Foobar\")\n .help(\"Does nothing\")\n .arg(\"Arg1\")\n .registerFunc();\n\nThe lambda's can take as many `const ExcelObj&` args as required. It must return `ExcelObj*`,\nbut it may throw: xlOil will return the error string. By specifying `const FuncInfo&` as the \ntype of the first argument, the callable will be given a reference to the function registration info\nin addition the arguments passed by Excel.\n\nYou can dynamically register any function you could register statically, so :any:`SpecialArgs` \narguments are valid, as well as a void return, for example:\n\n.. highlight:: c++\n\n::\n\n auto regId = RegisterLambda(\n [](const FuncInfo&, const ExcelObj& arg1, const AsyncHandle& handle)\n {\n handle.returnValue(...);\n })\n .name(\"AsyncFoobar\").registerFunc();\n\nThe returned register Id is a `shared_ptr` whose destructor unregisters the function, so this must be\nkept in scope.\n\n"
},
{
"path": "docs/source/xlOil_Cpp/Events.rst",
"content": "================\nxlOil C++ Events\n================\n\nSee :ref:`Events:Introduction`.\n\nExamples\n--------\n\n.. highlight:: c++\n\n::\n\n // When the returned shared_ptr is destroyed, the handler is unhooked.\n auto ptr = xloil::Event::CalcCancelled().bind(\n [this]() { this->cancel(); }));\n\n // The returned id can be used to unhook the handler\n static auto id = Event::AfterCalculate() += [logger]() { logger->flush(); };\n\n"
},
{
"path": "docs/source/xlOil_Cpp/GettingStarted.rst",
"content": "=========================\nxlOil C++ Getting Started\n=========================\n\n\nThere are a few ways to build a C++ project with xlOil:\n\n 1. xlOil plugin: writing a DLL which can be loaded by xlOil after the loader XLL \n starts up the application. This allows co-operation with other xlOil features such as\n the the object cache and settings file. It means that cache references created by \n `xloRef` can be used in your addin.\n 2. XLL dynamically linking xlOil. This allows co-operation with the Excel object cache.\n Your XLL will need to be able to find xlOil when it loads - this may be easier if delay\n loading is employed.\n 3. XLL statically linking xlOil. This gives a standalone XLL. It does not include\n the xlOil cache functions `xloRef` and `xloVal`, although it is easy to define a private\n object cache with your own function names.\n\nThe header files and `xlOil.lib` file required for dynamic linking are included in the \n`binary releases `_.\n\nYou need: \n * `xlOil.lib`: linking library\n * `xlOil.dll`: main binary \n * `xlOil.xll`: XLL loader stub\n * `xlOil.ini`: Main settings file\n * `include/xloil`: header files\n\nThe static libs are a lot larger, so you'll need to build them from source.\n\nIf you want to read settings from the add-in's *.ini* file using *tomlplusplus* you can find \nthis in `xlOil/external` - it's header-only.\n\nCreating an xlOil Plugin\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis method assumes you already have a running install of xlOil.\n\nCreate a project & solution for your DLL.\n\nBuilding an xlOil plugin requires a number of build settings and the easiest way to get these right\nit is use a property sheet. First, include an edited copy of `./libs/SetRoot.props` where *xlOilRoot* \npoints to the xlOil directory. Then include `./libs/xlOilPlugin.props`.\n\nNow add the following source file:\n\n.. highlight:: c++\n\n:: \n\n #include \n\n XLO_PLUGIN_INIT(xloil::AddinContext* ctx, const xloil::PluginContext& plugin)\n {\n xloil::linkLogger(ctx, plugin);\n return 0;\n }\n\n using namespace xloil;\n\n XLO_FUNC_START( \n MyFunc(const ExcelObj* arg1, const ExcelObj* arg2)\n )\n {\n auto result = arg1->toString() + \": \" + arg2->toString(L\"default value\");\n return ExcelObj::returnValue(result);\n }\n XLO_FUNC_END(MyFunc).threadsafe()\n .help(L\"Joins two strings\")\n .arg(L\"Val1\", L\"First String\")\n .arg(L\"Val2\", L\"Second String\");\n\n\nDeclaring an `XLO_PLUGIN_INIT` entry point lets xlOil know the DLL is a plugin. Calling `linkLogger`\nlinks the *spdlog* to the main xlOil log output. This is optional if you don't plan on using any logging\nfunctionality.\n\nThe ``ExcelObj`` class wraps the xloper12 variant type used in the XLL interface. It provides\na number of accessors with a focus on efficiency and avoidance of copying (see below).\n\nTo load your plugin in Excel you need to ensure that the main xlOil add-in can locate your DLL. \nYou can do this by changing the Addin enviroment in the `xlOil.ini` file or changing the\ncurrent working directory or system PATH, or by simply ensuring your DLL is in the same directory\nas *xlOil.dll*.\n\nYou should also add your plugin to the `Plugins=` key in `xlOil.ini`.\n\n\nCreating an XLL which statically links xlOil\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBuild xlOil with the *DebugStatic* or *ReleaseStatic* configuration.\n\nCreate a project & solution for your XLL. It should output a DLL, but change the *Target Extension* to XLL.\n\nBuilding an xlOil-linked XLL requires a number of build settings and the easiest way to get these right\nit is use a property sheet. First, include an edited copy of `./libs/SetRoot.props` where *xlOilRoot* \npoints to the xlOil directory. Then include `./libs/xlOilStaticLib.props`.\n\nAlternatively, you can copy and modify the `TestAddin` project, though you will still need to ensure\n*xlOilRoot* is set correctly.\n\nCreate a `Main.cpp` file with the following contents:\n\n.. highlight:: c++\n\n::\n\n #include \n #include \n using namespace xloil;\n \n struct MyAddin\n {};\n XLO_DECLARE_ADDIN(MyAddin);\n\n XLO_FUNC_START( \n MyFunc(const ExcelObj* arg1, const ExcelObj* arg2)\n )\n {\n auto result = arg1->toString() + \": \" + arg2->toString(L\"default value\");\n return ExcelObj::returnValue(result);\n }\n XLO_FUNC_END(MyFunc).threadsafe()\n .help(L\"Joins two strings\")\n .arg(L\"Val1\", L\"First String\")\n .arg(L\"Val2\", L\"Second String\");\n\n\nDebugging your addin\n~~~~~~~~~~~~~~~~~~~~\n\nStart a debugging session with the following settings where the XLL may be `xlOil.xll`\nor one you built yourself depending on which path you are following.\n\n * Command: \n * Arguments: \n\nSetting the working directory is optional, but it may help locate any externals DLLs your\nadd-in uses.\n\nThere are many examples to follow in the ``xloil_Utils`` and ``xloil_SQL`` projects."
},
{
"path": "docs/source/xlOil_Cpp/ObjectHandles.rst",
"content": "========================\nxlOil C++ Object Handles\n========================\n\nIt is often convenient to pass a pointer to an in-memory object from one function to another in a way\nwhich generalises :any:`core-cached-objects`. xlOil makes this very straightforward:\n\n.. highlight:: c++\n\n::\n\n XLO_FUNC_START(\n cacheOut(const ExcelObj& val)\n )\n {\n auto key = makeCached(val.toInt());\n return returnValue(key);\n }\n XLO_FUNC_END(cacheOut);\n\n XLO_FUNC_START(\n cacheIn(const ExcelObj& cacheKey)\n )\n {\n auto* val = getCached(cacheKey.asPString());\n return returnValue(val ? *val : 0);\n }\n XLO_FUNC_END(cacheIn);\n\nThe cache key or handle returned looks `[Book1]Sheet1!R1C1,A`. The leading character \nallows rapid rejection of invalid cache strings; it is unique per cached object type.\n\nCached objects do not persist when a spreadsheet is closed, but Excel does not know to recalculate\nthe cells which generate the cache handles when a spreadsheet is opened, so a full recalc must\nbe manually performed with Ctrl-Alt-F9. To avoid this requirement, you can make the functions which\ngenerate the handles RTD, but this carries some overhead.\n"
},
{
"path": "docs/source/xlOil_Cpp/SpecialArgs.rst",
"content": "======================\nXLL Special Arguments\n======================\n\nUser-defined Excel functions in XLLs usually take a number of `const ExcelObj&` arguments\nand return a `ExcelObj*`. xlOil supports a number of other possibilities, the most useful\nof which are `RangeArg` and `AsyncHandle`.\n\nRangeArg\n--------\n\nDeclaring a class as `const RangeArg&` instead of an `ExcelObj` in registered function tells \nxlOil to allow range references to be passed. These are sheet addresses which avoid copying\nthe underlying data. Normally, references to areas on the sheet are converted to arrays\nbefore being passed to the function. A `RangeArg` only allows the possibility that a range\nreference be specified, `RangeArg` inherits from `ExcelObj` and so may actually be any Excel \ntype.\n\nAsyncHandle\n-----------\n\nDeclaring an argument as `const AsyncHandle&` causes the function to be declared as native\nasync type to Excel. Such a function does not return a value directly but invokes the \n`returnValue` method on its handle to pass a value to Excel (which should only be done once).\n\nExcelObj pointer\n----------------\n\nYou may opt to receive a `const ExcelObj*` instead of a reference. This is purely preference\nand has no other impact.\n\nFPArray\n-------\n\nAn `FPArray` argument is a two-dimensional array of double. This is naturally very fast to \naccess, particulary when combined with inplace returns but has a significant drawback: if\nif any value in the array passed to the function is not a number, Excel will return *#VALUE!*\nwithout actually invoking the function.\n\nInplace returns\n----------------\n\nExcel supports returning values by modifying arguments in place. This is most useful for the \nFPArray type. To declare inplace return, simply make the argument a non-const ref or pointer.\n\nIt is also possible to return an `ExcelObj` in-place but this is disabled by default. \nIn the words of the XLL SDK:\n\n\n \"Excel permits the registration of functions that return an XLOPER by modifying \n an argument in place. However, if an XLOPER argument points to memory, and the \n pointer is then overwritten by the return value of the DLL function, Excel can \n leak memory. If the DLL allocated memory for the return value, Excel might try \n to free that memory, which could cause an immediate crash. Therefore, you should \n not modify XLOPER/XLOPER12 arguments in place.\"\n\n\nIn practice, it can be safe to modify an ExcelObj in place, for instance *xloSort*\nmodifies its input by changing the row order in the array, but without changing memory \nallocation. However it does not use an inplace return because the drawback of this \ntechnique is that you cannot return a different type to the one passed, in particular\nyou cannot return an error message or error type. \n\nTo enable inplace `ExcelObj` returns, define the macro \n`XLOIL_UNSAFE_INPLACE_RETURN` before including any xlOil headers."
},
{
"path": "docs/source/xlOil_Cpp/StaticXLLs.rst",
"content": "======================\nxlOil C++ Static XLLs\n======================\n\nAs explained in :any:`GettingStarted`, it is possible to create an XLL which statically links xlOil.\nThis allows an all-in-one XLL without worrying about DLL search paths. We expand on the example \nin :any:`GettingStarted` to illustrate some of the other static XLL features:\n\n.. highlight:: c++\n\n::\n\n #include \n #include \n using namespace xloil;\n\n struct MyAddin\n {\n MyAddin()\n {\n // This constructor is called by Excel's AutoOpen\n\n xllOpenComCall([this]()\n {\n // If we need to do some COM stuff on startup, like register a Ribbon,\n // it needs to go in this delayed COM callback.\n });\n }\n\n ~MyAddin()\n {\n // This destructor is called by Excel's AutoClose\n }\n\n \n static wstring addInManagerInfo()\n {\n // The string returned here is displayed in Excel's addin options window\n // Note the function is static: it can be called before AutoOpen.\n return wstring(L\"My Addin Name\");\n }\n };\n XLO_DECLARE_ADDIN(MyAddin);\n\n"
},
{
"path": "docs/source/xlOil_Cpp/index.rst",
"content": "======================\nxlOil C++\n======================\n\nxlOil C++ provides a layer above the `XLL API `_\nand includes features not available via the XLL API, such as RTD Servers, Ribbon customisation\nand event handling.\n\nThe xlOil C++ interface has a `doxygen API description <../../doxygen/html/doxygen/index.html>`_.\n\n.. toctree::\n :maxdepth: 4\n :caption: Contents\n\n GettingStarted\n SpecialArgs\n Events\n ObjectHandles\n CustomGUI\n CppRtd\n DynamicRegistration\n StaticXLLs\n COM\n\n\nQuick Tour of the Key Classes\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nExcelObj - An XLOPER wrapper\n----------------------------\n\nAn *ExcelObj* is a friendly wrapper around Excel's *xloper12* struct which is the variant type\nused to pass arguments in the XLL interface. An *ExcelObj* it has the same size and *xloper12* so\nyou can freely cast between the two (although be aware that *ExcelObj* has a destructor).\n*ExcelObj* supports a number of variant-like operations: it can be compared to strings or numbers,\nconverted to a string, and created from values or initialiser lists. However, it's not recommended\nto use *ExcelObj* as a generic variant type - reserve it for interaction with the XLL API.\n\nExcelArray / ArrayBuilder\n-------------------------\n\nTo **view** a suitable `ExcelObj` as an array, pass it to the `ExcelArray` constructor. \nBy default, the array is 'trimmed' to last row and column containing data (i.e. not empty or \nN/A). `ExcelArray` is a view - it is lightweight but does not own the underlying\ndata.\n\nThe `ArrayBuilder` class constructs arrays to return to Excel. For efficiency (of the CPU not\nthe programmer!) it requires you to know up-front how many array elements you require and the\ntotal length of all strings in the array. This may mean you need to make two passes of your \ndata, but it saves iterating through the array on destruction. \n\nPString\n-------\n\nStrings in the XLL API are Pascal wide char strings: the first character is the length and \nthey are not null terminated. `PString` wraps such a string and provides a similar interface to \n`std::wstring`. There's also a `PStringView` type like `std::wstring_view`.\n\nRange / RangeArg / ExcelRef\n---------------------------\n\nThere are few types of range class with slightly different internals and usages. All behave \nin a \"range-like\" way, supporting:\n\n * `(i, j)` - accessor to pick out individual elements\n * `range(fromRow, fromCol, toRow, toCol)` - create a sub-range\n * `value()` - convert to an `ExcelObj` single value or array\n * `address()` - fetch the sheet address as a string \n * `set(val)` - sets the range values to the given `ExcelObj` (which may be an array)\n\n\nThe `RangeArg` type should only be used to declare an argument to a user-defined worksheet\nfunction. Specifing this type means that xlOil is allowed to pass range references to your\nfunction. See :any:`SpecialArgs`. A `RangeArg` is not directly constructable - you should\nconvert it to an `ExcelRef` to copy and pass it around.\n\nThe `ExcelRef` type is equivalent to an *xltypeRef* `ExcelObj`, that is it points to a \nrectangular space on a specific sheet. It can be created from an `ExcelObj` which is a \nrange reference (typically via `RangeArg.toExcelRef()`) or a sheet address string.\n\nThe `Range` type is a virtual base: it may point either to an `ExcelRef` range or a COM \nrange object. Prefer `ExcelRef` when you are sure the range information has been passed via\nan XLL worksheet function.\n\n\ncallExcel - calling XLL API functions\n-------------------------------------\n\nThe XLL SDK docs describe a number of API calls beginning with `xl` such as `xlCoerce` and\n`xlSheetNm`. There are also many more poorly documented API calls beginning with `xlc` and \n`xlf`. They can all be found in `xlcall.h`. Invoking these functions is straightforward:\n\n.. highlight:: c++\n\n::\n \n ExcelObj result = callExcel(msxll::xlSheetId, \"Sheet1\");\n\n\nAll arguments are automatically converted to `ExcelObj` type where a conversion is possible\nbefore being passed to Excel. The type of the return value is given in the documentation.\n\nrunExcelThread - calling blocked API functions \n----------------------------------------------\n\nExcel's COM API must be called on the main thread, since it's single-threaded apartment.\nBreaking this rule may lead to undefined behaviour. In addition, the COM interface must be 'ready'\nwhich means no dialog boxes are open or other tasks which busy the COM interface.\n\nCalls to the XLL API generally also require the main thread (with a few exceptions) and being in \nthe correct 'context', that is being in a function invoked by Excel.\n\nThe `runExcelThread` function queues a message to a hidden window or an asynchronous procedure call \n(APC) callback which will be executed on the main thread when Excel passes control to windows \nor pumps its message loop respectively (a window message is the default, most responsive choice).\n\nThe `runExcelThread` function can retry calls, trying to wait until the COM interface is ready (sadly \nthere is no mechanism to allow Excel to inform applications when it is ready to work, you just \nhave to keep trying).\n \nIn addition, setting the `XLL_API` flag runs the callback in the XLL context.\n\n "
},
{
"path": "docs/source/xlOil_Python/BuiltInUDFs.rst",
"content": "==================================\nxlOil Built-in Worksheet Functions\n==================================\n\nThe the important ``xloRef`` and ``xloVal`` functions are described at\n:ref:`core-cached-objects`\n\nxloPyLoad: import and scan a python module (worksheet function)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. function:: xloImport(ModuleName:str, From=None, As=None)\n\n Loads functions from a module and registers them in Excel. The functions do not have to be decorated.\n Provides an analogue of `from X import Y as Z`\n\n ModuleName:\n A module name or a full path name to a target py file. If empty, the workbook module\n with the same name as the calling workbook is (re)loaded.\n From: \n If omitted, imports the specified module as normal, i.e. :any:`xloil.scan_module` If a \n value or array, registers only the specified object names. If \"*\", all objects are registered.\n To: \n Optionally specifies the Excel function names to register in the same order as `From`.\n Should have the same length as `From`.\n\n See :any:`xloil.import_functions`\n\n.. function:: xloAttr(Object, Name:str, *Args, **Kwargs)\n Returns the named attribute value, or the result of calling it if possible. ie, ``object.attr`` \n or ``object.attr(*args, *kwargs)`` if it is a callable.\n\n Object: \n The target object\n Name: \n The name of the attribute to be returned. The attribute can be a bound method,\n member, property, method, function or class\n Args\n If the attribute is callable, it will be called using these positional arguments\n Kwargs\n If the attribute is callable, it will be called using these keyword arguments\n \n.. function:: xloAttrObj(Object, Name:str, *Args, **Kwargs)\n Returns the value of named attribute or the result of calling the attribute. Behaves like\n `xloAttr` except always returns a cache object (see :ref:`xlOil_Python/TypeConversion:Cached Objects`).\n\n This function is useful to stop the default conversion to Excel, for example when returning\n an iterable. A typical use is when chaining `=xloAttrObj` calls.\n\n.. function:: xloPyDebug(Debugger)\n\n See :ref:`xlOil_Python/Debugging:Selecting the debugger programmatically`"
},
{
"path": "docs/source/xlOil_Python/Concepts.rst",
"content": "=========================\nxlOil Python Concepts\n=========================\n\n.. contents::\n :local:\n\n\nWorkbook Modules\n----------------\n\nWhen an Excel workbook is opened, xlOil tries to load the module `.py` \n(this is configurable). When registering functions from workbook modules, xlOil defaults \nto making any declared functions :ref:`xlOil_Python/Functions:Local Functions`\n\nThe function :any:`xloil.linked_workbook` when called from a workbook module retrieves \nthe associated workbook path.\n\n\nArray Functions\n---------------\n\nBy default, xlOil-Python converts Excel array arguments to numpy arrays. The conversion\nhappens entirely in C++ and is very fast. Where possible you should write functions\nwhich support array processing (vectorising) to take advantage of this, for example\nthe following works when it's arguments are arrays or numbers:\n\n::\n\n @xlo.func\n def cubic(x, a, b, c, d)\n return a * x ** 3 + b * x ** 2 + c * x + d\n\nYou can take this further to evaluate polynominals of n-th degree:\n\n::\n\n @xlo.func\n def poly(x, coeffs: xlo.Array(float)):\n return np.sum(coeffs * x[:,None] ** range(coeffs.T.shape[0]), axis=1)\n\nSpecifing that we expect an array argument and the data type of that array avoids the\noverhead of xlOil determining the type. There is a problem with this function:\nwhat happens if ``x`` is two-dimensional? To avoid this possibility we can specify:\n\n::\n\n @xlo.func\n def poly(x: xlo.Array(dims=1), coeffs: xlo.Array(float)):\n return np.sum(coeffs * X[:,None] ** range(coeffs.T.shape[0]), axis=1)\n\n\nEvents\n------\n\nEvents allow for a callback on user interaction. If you are familiar with VBA, you may have used \nExcel's event model already. Most of the workbook events described in \n`Excel.Appliction `_\nare available in xlOil. \n\nSee :ref:`xlOil_Python/ModuleReference:Events` for more details on python events and :doc:`Events`\nfor a description of the available Excel events.\n\nExcel events do not use return values. However, some events take reference parameters. \nFor example, `WorkbookBeforeSave` has a boolean `cancel` parameter. Setting this to True cancels the \nsave. As references to primitive types aren't supported in python, in xlOil you need to set this \nvalue using `cancel.value=True`.\n\nEvent handlers are (currently) global to the Excel instance, so you may need to filter by workbook name \nwhen handling events even if you have hooked the event in a local workbook module.\n\nExamples\n~~~~~~~~\n\n::\n\n def greet(workbook, worksheet):\n xlo.Range(f\"[{workbook}]{worksheet}!A1\") = \"Hello!\"\n\n xlo.event.WorkbookNewSheet += greet\n\n\nRegistering functions in other modules\n--------------------------------------\n\nxlOil automatically scans modules when they are imported or reloaded via a\nhook in python's import mechanism. This ensures any :any:`xloil.func` \ndecorated functions are registered. \n\nIf you load a module outside the normal ``import`` mechanism, you can tell \nxlOil to look for functions to register with :any:`xloil.scan_module`. \n\nAlso see :any:`xlOil_Python/Functions:Dynamic Registration`, which explains\nhow any python callable can be registered as an Excel function.\n\n\nMultiple addins and event loops\n-------------------------------\n\n*xlOil_Python* can be used by multiple add-ins, that is, more than one XLL\nloader with its own settings and python codebase can exist in the same Excel\nsession. \n\n * Each add-in / XLL is loaded in a background thread equipped with an `asyncio` \n event loop. Get the loop using :any:`xloil.get_event_loop`.\n * You can find the addin associated with the currently running code with \n :any:`xloil.source_addin` .\n * All add-ins share the same python interpreter\n * All add-ins share the python object cache\n * Worksheet functions are executed in Excel's main thread or one of its \n worker threads for thread safe functions\n * Async / RTD worksheet functions are executed in a dedicated xlOil Core\n event loop which you can access with ``xloil.get_async_loop()``\n * You can ask xlOil to create a separate thread & event loop for an addin. \n\nAlthough CPython supports subinterpreters, most C-based extensions, particularly\n*numpy* do not, so there are no plans to add subinterpreter support at this stage.\n"
},
{
"path": "docs/source/xlOil_Python/CustomGUI.rst",
"content": "==============================\nxlOil Python GUI Customisation\n==============================\n\n.. contents::\n :local:\n\n\nStatus Bar\n----------\n\nPossibly the simplest Excel GUI interaction: writing messages to Excel's status bar:\n\n::\n\n from xloil import StatusBar\n\n with StatusBar(1000) as status:\n status.msg('Doing slow thing')\n ...\n status.msg('Done slow thing')\n\nThe :any:`xloil.StatusBar` object clears the status bar after the specified number of milliseconds\nonce the `with` context ends\n\n\nRibbon\n------\n\nxlOil allows dynamic creation of Excel Fluent Ribbon components. See :any:`concepts-ribbon` for \nbackground.\n\n::\n\n gui = xlo.ExcelGUI(r'''....''', \n funcmap={\n 'onClick1': run_click,\n 'onClick2': run_click,\n 'onUpdate': update_text,\n })\n\nThe ``gui`` object :any:`xloil.ExcelGUI` holds a handle to a COM addin created to support\nthe ribbon customisation. If the object goes out of scope and is deleted by python or if you call \n``gui.disconnect()``, the add-in is unloaded along with the ribbon customisation and any custom task \npanes.\n\nThe ``funcmap`` dictionary (or function) links callbacks named in the ribbon XML to python functions. \nEach handler should have a signature like the following:\n\n::\n\n def ribbon_button_press(ctrl: RibbonControl)\n ...\n def ribbon_callback2(ctrl: RibbonControl, arg1, arg2)\n ...\n def ribbon_get_text_label(ctrl: RibbonControl, *args)\n return \"something\"\n async def ribbon_callback4(ctrl: RibbonControl, *args)\n ... \n\nThe ``ctrl`` argument points to the control which raised the callback. The number of additional\narguments is callback dependent. Some callbacks are expected to return a value. \nSee `Customizing the Office Fluent Ribbon `_\nfor a description of the appropriate callback signature.\n\n.. note::\n\n Callbacks are executed in Excel's main thread unless declared *async*, in which case they will be \n executed in the addin's event loop. Async callbacks cannot return values.\n\n\nInstead of a dictionary, the `funcmap` object can be a function which takes any string and returns a \ncallback handler.\n\nSee :doc:`ExampleGUI` for an example of ribbon customisation, or look at xlOil's own ribbon in the \n`xloil/xloil_ribbon.py` module.\n\nSetting button images\n=====================\n\nAny `getImage` callbacks must return a `PIL Image `_.\nThis is converted to an appropriate COM object by xlOil. Instead of using a separate `getImage` callback \nper control, a single `loadImage` attribute can be added:\n\n::\n\n \n ...\n \n\nThe `MyImageLoader` function will be called with the argument `icon.jpg` and be expected to return\na *PIL Image*.\n\n\nCustom Task Panes\n-----------------\n\n`Custom task panes `_ are user \ninterface panels that are usually docked to one side of a window in the Excel application. They can \ncontain a *Qt*, *Tk* or *wx* interface, or any suitable custom COM control. \n\nCustom task panes are created using the :any:`xloil.ExcelGUI` object. There is no need to create a ribbon \nas well, but task panes are normally opened using a ribbon button, because Excel does not provide a \ndefault way for users to show or hide custom task panes.\n\nCustom task panes are associated with a document frame window, which presents a view of a workbook \nto the user. If you want to display a custom task pane with multiple workbooks, create a new instance \nof the custom task pane when the user creates or opens a workbook. To do this, either handle the \n`WorkbookOpen` event, or require the user to press a ribbon button to open a task pane for the active\nworkbook.\n\nThread-safety\n=============\n\nThe :any:`xloil.ExcelGUI` object and custom task panes can be created in any thread (internally they \nre-direct calls to Excel's main thread). Typically GUI creation will be done on xlOil's python loader \nthread, which also contains an *asyncio* event loop. The individual GUI toolkits are generally not \nthread-safe and should only be accessed from dedicated threads which xlOil creates. This is described \nbelow per toolkit in more detail.\n\n.. caution:\n\n If another non-xlOil Excel addin uses the same GUI toolkit, it is very likely that Excel will crash.\n\nQt Custom Task Panes\n====================\n\nQt support uses *qtpy* which auto-detects the Qt bindings (PySide/PyQt) and standardises the \nsmall syntactic differences between the libraries.\n\n.. caution::\n You *must* import :any:`xloil.gui.qtpy` before any other use of Qt. This allows xlOil \n to create and the *QApplication* on its own thread.\n\nIt's common in Qt GUIs to inherit from `QWidget`, so xlOil allows you to create a pane\nfrom a `QWidget`:\n\n::\n\n import xloil.gui.qtpy\n from qtpy.QtWidgets import QWidget \n\n class QtTaskPane(QWidget):\n def __init__(self):\n super().__init__() # Don't forget this!\n ... # some code to draw the widget\n def send_signal(self, int):\n ... # some code to emit a Qt signal\n\n excelui = xlo.create_gui(...)\n pane = excelui.attach_pane('MyPane', pane=QtTaskPane)\n\n # The widget is in the pane's `widget` attribute\n pane.widget.send_signal(3) \n\nThe :any:`xloil.ExcelGUI.attach_pane` call creates a task pane with the specified name. If ``pane`` \nis a *type* which inherits from `QWidget`, it is constructed (on the Qt thread, see below)\nand placed in a :any:`xloil.gui.qtpy.QtThreadTaskPane` then attached to the Excel window.\n\nTo talk to your widget, it's best to set up a system of Qt \n`signals `_ as these are thread-safe. \n(Note the `syntax differs slightly in PyQt5 `_\nbut it is standardised by *qtpy*) \n\n\nQt Thread-safety\n________________\n\nAll *Qt* interactions other than signals must take place in the same thread, or Qt\nwill abort. xlOil creates a special Qt thread which runs the Qt event loop, and \nconstructs any task panes on that thread.\n\nTo run commands on xlOil's *Qt* thread, use the :any:`xloil.gui.qtpy.Qt_thread` object\n\n::\n\n from xloil.gui.qtpy import Qt_thread\n future = Qt_thread().submit(func, *args) # returns a concurrent.futures.Future\n future2 = Qt_thread().submit_async(func, *args) # returns an asyncio.Future\n future.result() # Blocks if result is required now\n\nYou can also use `Qt_thread` as a decorator to wrap the function in a `submit` call, for example:\n\n::\n\n @Qt_thread\n def some_func():\n ...\n\nTkinter Custom Task Panes\n=========================\n\nWe create a class which derives from :any:`xloil.gui.tkinter.TkThreadTaskPane` (which in turn \nderives from :any:`xloil.gui.CustomTaskPane`). Unlike Qt, it's not (I think) as common to derive\nfrom a *tkinter.Frame* object.\n\nWe draw the window into the *tkinter.Toplevel* contained in `self.top_level`.\n\n::\n \n from xloil.gui.tkinter import TkThreadTaskPane, Tk_thread\n\n class TkTaskPane(TkThreadTaskPane):\n \n @Tk_thread\n def set_x(self, x):\n ...\n \n def __init__(self):\n super().__init__() # Don't forget this!\n \n # This name is picked up by ExcelGUI.attach_pane\n self.name = \"MyPane\"\n\n import tkinter as tk\n \n top_level = self.top_level\n # Draw into window\n ...\n \n\n excelui = xlo.ExcelGUI(xml=..., funcmap=...)\n pane = excelui.attach_pane(TkTaskPane())\n\n pane.set_x(3)\n\nAs *tkinter* does not have thread-safe signals, although it does have events which could be used here, \nbut for illustration, we ensure `set_x` is run on the *Tk* thread, by decorating it with \n:any:`xloil.gui.tkinter.Tk_thread`. The `__init__` method is always called on the *tkinter* thread \nso we don't need to decorate it.\n\nTkinter Thread-safety\n_____________________\n\nThe :any:`xloil.gui.tkinter.Tk_thread` function behaves the same as `Qt_thread` described\nin :ref:`xlOil_Python/CustomGUI:Qt Thread-safety`. \n\n\nwxPython Custom Task Panes\n==========================\n\nIt's common in wx GUIs to inherit from `wx.Frame`, so xlOil allows you to create a pane\nfrom a `wx.Frame`:\n\n::\n\n from xloil.gui.wx import wx_thread\n import wx\n\n class OurWxPane(wx.Frame):\n def __init__(self):\n super().__init__(None, title='Hello')\n ...\n\n @wx_thread\n def set_progress(self, x: int):\n ...\n\n excelui = xlo.create_gui(...)\n pane = excelui.attach_pane('MyPane', pane=OurWxPane)\n\n # The frame is in the pane's `frame` attribute\n pane.frame.set_progress(3)\n\nWe ensure `set_progress` is run on the *wx* thread, by decorating it with :any:`xloil.gui.wx.wx_thread`.\n\nwxPython Thread-safety\n______________________\n\nThe :any:`xloil.gui.wx.wx_thread` function behaves the same as `Qt_thread` described\nin :ref:`xlOil_Python/CustomGUI:Qt Thread-safety`. \n\n\nTask Pane Events\n================\n\nCustom task panes have three events which can be handled by defining methods in the subclass of \n:any:`xloil.gui.CustomTaskPane` used to create the pane. The callbacks occur on Excel's main thread.\nThe events are:\n\n::\n\n def on_docked(self):\n # Called when the user docks or undocks the pane. The dock position is in 'self.position'\n ...\n\n def on_visible(self, state: bool):\n # Called when the user closes/shows the pane with the new visibility in 'state'\n ...\n\n def on_destroy(self):\n # Called just before the pane is destroyed when the parent window is closed\n super().on_destroy() # Important!\n ...\n\nTask Pane registry\n==================\n\nThe created task panes are automatically stored in a registry so there is no need to hold a\nreference to them. Task panes are attached by default to the active window and it is possible to \nhave multiple windows per open workbook. xlOil will free the panes when the parent workbook ora\naddin closes.\n\nWe can search the registry by name for a task pane without having the :obj:`xloil.ExcelGUI` object:\n\n::\n\n pane = xloil.gui.find_task_pane(\"MyPane\")\n\nBy default, xlOil looks for a pane attached to the active window, but this can be changed with\narguments. It is possible to create multiple panes with the same name, in which case this search\ncould return either one.\n\n\nAsync GUI Calls\n---------------\n\nThe above examples create the GUI calls in a synchronous fashion but many of the GUI functions\nare or can be async. Because xlOil loads modules in a background thread, it's not necessary\nto do this to keep Excel responsive but it could be useful in some circumstances.\n\n::\n\n async def make_gui():\n \n # With connect=False the ctor does nothing\n excelui = xlo.ExcelGUI(xml=..., funcmap=..., connect=False)\n\n # The action happens when we call connect, which returns a awaitable future\n await excelui.connect()\n\n # We can also create the pane async by passing an awaitable but we have \n # to then pass the name explictly\n await excelui.attach_pane_async(\n name='TkPane',\n pane=Tk_thread().submit_async(TkTaskPane))\n\n # We need to keep a reference to 'excelui' as deleting it disconnects the UI\n return excelui, pane\n"
},
{
"path": "docs/source/xlOil_Python/Debugging.rst",
"content": "==============================\nxlOil Python Debugging\n==============================\n\nOnly python debuggers capable of handling *embedded* python interpreters can be used to debug xlOil\npython code.\n\nVisual Studio\n-------------\n\n*Visual Studio 2019* and *Visual Studio 2022* with Python Tools installed can break into xlOil python code. \nAttach to the relevant Excel process selecting *only Python Code* debugging. \n\nVisual Studio will occasionally hang when first hitting a python breakpoint. In the case, restart VS and\nExcel and re-try\n\n.. note::\n As of Aug 2022, mixed mode debugging with both Python and Native C code does not work: Python \n breakpoints are not hit.\n\n\nVS Code\n-------\n\n*VS Code* can break into xlOil python code. You need to tell xlOil to start a `debugpy` server by\nselecting it as the debugger in the xlOil ribbon or the ini file. Then use VS Code's python \nremote debugger to connect. The default port is *5678* but this can be changed in the ini file.\n\n*VS Code* cannot hit breakpoints in async and RTD functions even though tracing is enabled in the\nrelevant threads. The reason for this is unknown.\n\n.. note::\n Running the *debugpy* server has some peformance implications, so avoid leaving debugging \n enabled when not required.\n\nPdb\n---\n\nPdb can be used for post-mortem debugging, i.e. after an exception occurs. Select *pdb* in as \nthe debugger in the xlOil ribbon or the ini file. Use the command `breakpoint()` in your \ncode to trigger the debugger, or wait for an exception.\n\n\nSelecting the debugger programmatically\n---------------------------------------\n\nA debugger can be selected at runtime in the xlOil ribbon but this choice will persist when Excel\nis restarted. Alternatively, the debugger can be choosen in code, which is not persistent. Use\nthe following python code:\n\n::\n\n import xloil.debug\n xloil.debug.use_debugger('pdb')\n\nOr the Excel formula:\n\n::\n\n =xloPyDebug(...)\n\n"
},
{
"path": "docs/source/xlOil_Python/DistributingAddins.rst",
"content": "=======================================\nxlOil Python Distribution and Packaging\n=======================================\n\nxlOil supports two possiblilities for distribution:\n * Creating an XLL addin to distribute code to existing xlOil users\n * Packaging Python and xlOil to install code for new users\n\n\nCreating an Addin\n=================\n\nThe idea of this approach is to create an XLL addin so users don't have to edit\ntheir `xlOil.ini` to load some packaged code. \n\nUsers of XLL will need access to a python distribution which contains\nthe *xlOil* package, however they do not need the xlOil addin installed.\n\nAt a command prompt, run:\n\n::\n\n xloil create myaddin.xll\n\nThis will create a `myaddin.xll` and `myaddin.ini` in the current directory.\nBy default, the XLL will try to load `myaddin.py` in the same directory, so \ncreate this file:\n\n::\n\n import xloil as xlo\n\n @xlo.func\n def MySum(x, y, z):\n '''Adds up numbers'''\n return x + y + z\n\nDropping `myaddin.xll` into an Excel session will create the function ``MySum``.\n\nIf the python distribution will be in a standard directory on users' machines,\nthe `PYTHONEXECUTABLE` and `PATH` environment variables in `myaddin.ini` can\nbe used to point to it, otherwise these variables can read the python location\nfrom the registry.\n\nIf you copy `myaddin.xll`, `myaddin.ini` and `myaddin.py` to your `%APPDATA%\\\\Microsoft\\\\Excel\\\\XLSTART` \ndirectory, Excel attempts to opens the ini file and py files which is not ideal! xlOil will\nlook for `myaddin.ini` in `%APPDATA%\\\\xlOil`, so install the ini to there instead. You'll also need \nto choose a directory to hold `myaddin.py` (or other python modules) and ensure `myaddin.ini` points to \nit; `%APPDATA%\\\\xlOil\\\\myaddin` could be a sensible choice.\n\n.. important:: \n If a user of `myaddin.xll` has an ini file at `%APPDATA%\\\\xlOil\\\\xlOil.ini``\n the core xlOil.dll is loaded using those settings before `myaddin.xll`.\n The assumption is that the user has the xlOil addin installed in Excel, but \n since only one instance of xlOil (and one python interpreter) can be hosted in \n Excel, one settings file must take precedence. You can make your addin take\n precedence with the `LoadBeforeCore` flag in `myaddin.ini`.\n\n\nPackaging Python\n================\n\nxlOil can use `PyInstaller `_ to package a python distribution and\ncreate an installer executable. Support for this is fairly rudimentary at present.\n\nYou shouuld start with a minimum python distribution (ideally based on the standard distribution)\nfor the code you want to distribute, otherwise *PyInstaller* may create a very large output. The\ndistribution should include xlOil and be able to load your code in Excel.\n\nTo package the settings in the file *myaddin.ini* which loads the python module *excel_funcs.py*, \nrun the following command:\n\n::\n\n xloil package myaddin.ini --hidden-import excel_funcs\n\nNote that *--hidden-import* is actually an `argument to PyInstaller `_\nand can be specified multiple times. Any other trailing arguments will be passed directly to *PyInstaller*.\n\nThe resulting *dist* directory will contain:\n\n * install_main.exe (installs xlOil)\n * _internal (contains the python distribution)\n\nThe installer does not copy the python distribution, it is used in-situ\n\n\nCustomising the packaging\n-------------------------\n\nCalling \n\n:: \n\n xloil package -makespec myaddin.ini\n \nstops the packaging process before after creation of the \n`PyInstaller spec files `_. You can edit this\nspec file directly as described in the *PyInstaller* docs, then invoke *PyInstaller* on the spec file\nyourself to finish the process.\n"
},
{
"path": "docs/source/xlOil_Python/Dynamic.rst",
"content": "========================================\nxlOil Python Dynamic Runtime Interaction\n========================================\n\nxlOil function registration can be controlled dynamically at runtime. Also,\nthe Excel can be controlled from macros or the console.\n\n\n.. contents::\n :local:\n\nDynamic Import\n--------------\n\nFunctions for registration can be specified at runtime without the need to \nadd an :any:`xloil.func` decorator.\n\n.. note::\n Although Excel will let you, avoid doing this from (non-async) worksheet functions\n since creating new functions *during* Excel's calculation cycle is likely to cause\n instability.\n\nThe :any:`xloil.import_functions` call provides an analogue of ``from X import Y as Z`` \nwith Excel UDFs. A simple usage is:\n\n::\n\n xloil.import_functions(\"c:/lib/AnotherFile.py\", names=[\"greet\"], as_names=[\"PyGreet\"])\n\n\nwhere AnotherFile.py contains:\n\n::\n\n def greet(x:str):\n return f\"Hello {x}!\"\n\nWe specify the Excel name of the function explicitly, if we omitted this, the function \nwould be registered with its python name. In Excel you can then use the formula \n``=greet(\"World\")``.\n\nTyping annotations are respected, as are doc-strings - the import behaves as if we had \ndecorated the function with :any:`xloil.func`.\n\nIn a worksheet, :any:`xloil.import_functions` is exposed as ``xloImport`` with the same \narguments.\n\nSince the import machinery can register *any* callable, including class constructors,\nyou cane be a little creative. For example, the following cell formulae will\ncreate a *pandas* *DataFrame* from the range `C1:F5`, sum over rows and take the average\nof the result.\n\n::\n\n [A1] : =xloImport(\"pandas\",\"DataFrame\")\n\n [A2] : =DataFrame(C1:F5)\n\n [A3] : =xloAttr(xloAttrObj(A2,\"sum\",{\"axis\",1}), \"mean\")\n\n\nNotice we used ``xloAttrObj`` - the output of this is always a cache reference. This stops \nxlOil from trying to convert the result to an Excel value. Since a *DataFrame* is iterable\nit would otherwise output *DataFrame.index* as an array. Also note the convenient use of\n`array constants `_\nto specify keyword arguments.\n\n\nDynamic Registration\n--------------------\n\nFunctions can be registed using :any:`xloil.register_functions` and deregistered\nwith :any:`xloil.deregister_functions`.\n\nFor example:\n\n::\n\n def Greet(x):\n return f\"Hello {x}\"\n \n xlo.register_functions([Greet])\n\nAny callable can be registered, for example:\n\n::\n\n class Closure:\n self._total = 0\n def __call__(self, x):\n self._total += x\n return x\n \n xlo.register_functions(Closure())\n\nThe name and help of the function can be controlled using :any:`xloil.func`\nand the function can be linked to a specific python module, which means\nit will be removed if the module is unloaded or reloaded.\n\n::\n\n xlo.register_functions(\n [xlo.func(fn=Closure(), name=f\"Dynamic1\", register=False)], \n module=sys.modules[__name__])\n\nFunctions are deregistered by name:\n\n::\n\n xlo.deregister_functions(\"Greet\")\n"
},
{
"path": "docs/source/xlOil_Python/Example.rst",
"content": "======================\nxlOil Python Examples\n======================\n\nThis is code for the xlOil python test spreadsheet. You can find the associated sheet at \n:ref:`core-example-sheets`.\n\n.. literalinclude:: /../../tests/AutoSheets/PythonTest.py\n\n"
},
{
"path": "docs/source/xlOil_Python/ExampleGUI.rst",
"content": "=========================\nxlOil Python GUI Examples\n=========================\n\nThis is code for the xlOil python test spreadsheet. You can find the associated sheet at \n:ref:`core-example-sheets`.\n\n.. literalinclude:: /../../tests/ManualSheets/python/PythonTestUI.py\n\n"
},
{
"path": "docs/source/xlOil_Python/ExampleRTD.rst",
"content": "=========================\nxlOil Python RTD Examples\n=========================\n\nThis is code for the xlOil python test spreadsheet. You can find the associated sheet at \n:ref:`core-example-sheets`.\n\n.. literalinclude:: /../../tests/ManualSheets/python/PythonTestAsync.py\n\n"
},
{
"path": "docs/source/xlOil_Python/ExcelApplication.rst",
"content": "==========================================\nxlOil Python: The Excel.Application object\n==========================================\n\n.. contents::\n :local:\n\nIntroduction\n------------\n\nThe `Excel.Application` object is the root of Excel's COM interface. If you have used VBA you \nwill likely have come across it. If xlOil is running embedded in Excel, you can get a reference \nto the parent application with :any:`xloil.app`. If xlOil has been imported as package, you can \ncreate an Application with :any:`xloil.Application`.\n\nxlOil mirrors a small part of the `Excel.Application` object model as discussed below. For other calls,\nthe COM interface can be accessed directly which provides syntax similar to the `Application`` object in \nVBA.\n\n.. important:: \n All COM calls must be invoked on the main thread! A function runs in the main thread if is \n not declared multi-threaded or if it is called from VBA or the GUI. However during Excel's calc\n cycle, much of the Application object model is locked, in particular, writing to the sheet is blocked.\n To schedule a callback to be run on main thread use :any:`xloil.excel_callback`.\n\nThe object model is documented extensively at `Excel object model overview `_\nand `Application Object `_\n\n\nCalling Worksheet Functions and Application.Run\n-----------------------------------------------\n\nIn VBA, ``Application.Run`` takes a function name and a variable argument list and attempts\nto call the specified user-defined function. In xlOil, use :obj:`xloil.run` to make the same \ncall or go via the COM library with ``xloil.app().Run(...)``. All COM calls must be invoked\non the main thread, however :obj:`xloil.run` and :obj:`xloil.call` have async flavours \n:obj:`xloil.run_async` and :obj:`xloil.call_async` which return a Future and can be called \nfrom any thread.\n\nTo call a worksheet function, use :obj:`xloil.call`. This can also invoke old-style \n`macro sheet commands `_.\nIt must be called from **a non-local worksheet function**. Worksheet functions can be\ncalled from COM, for example, ``xloil.app().WorksheetFunction.Sum(...)``.\n\n+-------------------------------+---------------------------------------------------------+------------------------------+\n| Function | Use | Call from |\n+===============================+=========================================================+==============================+\n| :obj:`xloil.run` | Calls user-defined functions as per `Application.Run` | Main thread |\n+-------------------------------+---------------------------------------------------------+------------------------------+\n| :obj:`xloil.run_async` | (as above but async) | Anywhere |\n+-------------------------------+---------------------------------------------------------+------------------------------+\n| :obj:`xloil.call` | Calls worksheet functions, UDFs or macro sheet commands | Non-local worksheet function |\n+-------------------------------+---------------------------------------------------------+------------------------------+\n| :obj:`xloil.run_async` | (as above but async) | Anywhere |\n+-------------------------------+---------------------------------------------------------+------------------------------+\n| xloil.app().WorksheetFunction | Calls worksheet functions | Main thread |\n+-------------------------------+---------------------------------------------------------+------------------------------+\n\nxlOil's Excel Object Model\n--------------------------\n\nxlOil mirrors a small part of the `Excel.Application` object model to faciliate easier access to the commonly \nused :obj:`xloil.Application`, :obj:`xloil.Workbook`, :obj:`xloil.Worksheet`, :obj:`xloil.ExcelWindow`, and \n:obj:`xloil.Range` objects.\n\nEach of xlOil's application objects provides a `to_com` method which accepts an optional *lib* argument. \nCalling this returns a marshalled COM object which supports any method or property in the full Application object \nmodel. COM support is be provided by `comtypes `_ , a newer pure \npython package or `win32com `_ \na well-established C++ based library. If omitted, the default is 'win32com'. The default can be changed \nin the XLL's ini file.\n\nCOM methods can be called directly on xlOil's application objects, so the following are equivalent:\n\n::\n\n xlo.Application().RegisterXLL(...)\n xlo.Application().to_com().RegisterXLL(...)\n\nThere is no ambiguity with other methods on the *Application* object as COM methods and properties \nall start with a capital letter.\n\nCOM methods can be called with keyword arguments - note COM arguments start with a capital letter.\n\n::\n\n xloil.app().Selection.PasteSpecial(Paste=xloil.constants.xlPasteFormulas)\n\n\nExcel Automation\n----------------\n\nExcel's COM interface allows the application to be driven externally by a script. This is best explored\nby looking at (a simplified version of) xlOil's test runner. The test runner is started at the command line,\nrather than inside an Excel instance like an xlOil-based addin. You may want to look at the documentation\nfor Excel's `Name `_ object.\n\n::\n\n import xloil as xlo\n\n # Create a new Excel instance and make it visible\n app = xlo.Application()\n app.visible = True\n\n # Load addin\n if not app.RegisterXLL(\"xloil.xll\"):\n raise Exception(\"xloil load failed\")\n\n test_results = {}\n for filename in ['TestUtils.xlsx, PythonTest.xlsm']:\n\n # Open the workbook in readonly mode: don't change the test source!\n wb = app.open(filename, read_only=True)\n \n app.calculate(full=True)\n\n # Loop through all named ranges in the workbook, looking for ones \n # prefixed with 'Test_'. We expect those ranges to contain True\n # for a successful test outcome.\n names = wb.to_com().Names\n for named_range in names:\n if named_range.Name.lower().startswith(\"Test_\"):\n # skip one char as RefersTo always starts with '='\n address = named_range.RefersTo[1:]\n test_results[(filename, named_range.Name)] = wb[address].value\n \n wb.close(save=False)\n\n app.quit()\n\n if not all(test_results.values()):\n print(\"-->FAILED<--\")\n\n\nCreating an Application\n=======================\n\nThe :any:`xloil.Application` object can be created in several ways:\n\n 1) When xloil is embedded, the parent applicaton object is in :any:`xloil.app()`\n 2) `xlo.Application()` with no arguments opens an new instance of Excel (but does not make it visible)\n 3) `xlo.Application(\"MyWorkbook.xlsx\")` returns an instance of Excel which has *MyWorkbook.xlsx* open (or throws)\n 4) `xlo.Application(ComObject)` points an Application at a COM object managed by *win32com* or *comtypes*\n 5) `xlo.Application(HWND)` creates a Application given the window handle of Excel's main window as an int\n\nThe application object can be :any:`xloil.Application.quit()` manually or since it is a context manager, \nyou can write:\n\n::\n\n with xloil.Application() as app:\n # do stuff\n ...\n\n # app has been quit without saving any open Workbooks\n\n\nAccessing Sheets and Ranges\n---------------------------\n\nWhen xlOil is embedded in Excel as an addin, there is a natural default :obj:`xloil.Application` \nobject: the parent application, which can be accessed by :any:`xloil.app()`. Additionally,\nwhen embedded you can unambigiously create :any:`xloil.Range` and :any:`xloil.Worksheet` objects\nwithout needing to specify the application.\n\nReading from a Range\n====================\n\n::\n\n import xloil as xlo\n\n # if xlOil is embedded: no need to specify Application.\n # Returns a numpy array\n xlo.Range(\"A1:C1\").value\n\n # Above is equivalent to\n xlo.app().range(\"A1:C1\").value\n\n # Using COM (win32com) to access a range with empty index\n # Returns a tuple rather than a numpy array\n xlo.app().Range(\"A1\", \"C1\").Value\n\nIf the range referred to is empty, its `value` array will be populated with `None`. This \nis different to array/range arguments to :any:`xloil.func` worksheet functions where the\narray is trimmed to the last non-blank. This behaviour can be replicated with \n:any:`xloil.Range.trim` :\n\n::\n\n r = xlo.app().range(\"A1:C1\")\n\n r.clear()\n r.trim().value # returns the array [None]\n\n r.set(1)\n r.trim().value # returns the array [1, 1, 1]\n\nThe square bracket (getitem) operator for a Range behaves like a numpy array,\nin that if the tuple specifies a single cell, it returns the value in that cell, otherwise \nit returns a :any:`xloil.Range` object. To create a range consisting of a single cell\nuse the `cells` method.\n\nWriting to a range\n==================\n\n::\n\n # Using the COM object\n xlo.app().Range(\"A1\", \"B2\").Value = ((1, 2), (3, 4))\n\n rng = xlo.Range(\"A1:B2\")\n # Using xlOil syntax (can use numpy array)\n rng.value = np.array([[1, 2], [3, 4]])\n\n # Set the entire range to a single value\n rng.set(\"hello\")\n\n # Add something\n rng += \" world!\"\n\n\nWriting a cell formula\n======================\n\nUse the :any:`xloil.Range.formula` property to set or retrieve the formula in a cell\n\n::\n\n xlo.app().Range(\"A1\").formula = '=SUM(B1:B10)'\n xlo.log(xlo.app().Range(\"A1\").has_formula) # Will write True\n\nWhen write addresses used in formula strings, :any:`xloil.Address` can be useful e.g.:\n\n::\n \n sum_start_row=0\n sum_end_row=9\n address = xlo.Address((sum_start_row, 1, sum_end_row, 1), sheet=\"Sheet1\")\n xlo.app().Range(\"A1\").formula = f'=SUM({address})' # Will be '=SUM(Sheet1!B1:B10)'\n\n\nSince the introduction of dynamic arrays, array formulae have become largely obselete, but it\nis possible to set them with :any:`xloil.Range.set_formula`.\n\n\nUsing Worksheets and Workbooks\n==============================\n\nThere are several ways to address or refer to part of a worksheet:\n\n::\n\n wb = xloil.active_workbook() # Only available when embedded\n\n # Specify external Excel range address\n r1 = xlo.app().range[f'{wb.name}Sheet1!B2:D3']\n\n # Specify workbook Excel range address\n r1 = wb['Sheet1!B2:D3']\n\n # Specify worksheet, then local Excel range address\n ws = wb['Sheet1']\n r1 = ws['B2:D3']\n \n # The range function, like in Excel includes right and left hand ends\n r2 = ws.range(from_row=1, from_col=1, to_row=2, to_col=3)\n\n # The slice syntax follows python conventions so only the left\n # hand end is included\n r3 = ws[1:3, 1:4]\n\n\nThe square bracket (getitem) operator for :any:`xloil.Worksheet` always returns\na :any:`xloil.Range`. For :any:`xloil.Workbook` it may return a :any:`xloil.Range`\nor a :any:`xloil.Worksheet`.\n\nWriting to a worksheet\n~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n data = np.array([[1, 2], [3, 4]])\n\n ws = xloil.worksheets['Sheet1']\n\n # ws[...] gives a Range, so \n ws[\"A1:B2\"].value = data\n\n # However, value is optional when writing to a sheet\n ws[\"A1:B2\"] = data \n\n # You can copy another part of the sheet, it's faster to\n # drop the value property here\n ws[\"A1:B2\"] = ws[\"D1:E2\"] \n\n # Also works for Workbooks\n wb = xloil.active_workbook()\n wb['Sheet1!B2:D3'] = ws[\"D1:E2\"] \n\n\n\nPausing Excel Calculations\n--------------------------\n\nWhen writing to worksheets, performance can often be improved by disabling Excel's auto calculation \nand Event model, otherwise calculation cycles and events will be triggered on each write.\n\nThis is straightforward using :any:`xloil.PauseExcel`:\n\n::\n\n with xloil.PauseExcel() as paused:\n for i in range(100):\n worksheet[i, 1].value = i\n\n\nThe context manager can be replicated manually with\n\n::\n\n try:\n\n xloil.app().ScreenUpdating = False\n xloil.app().EnableEvents = False\n xloil.app().Calculation = xloil.constants.xlCalculationManual\n\n ...\n\n finally:\n \n xloil.app().ScreenUpdating = True\n xloil.app().EnableEvents = True\n xloil.app().Calculation = xloil.constants.xlCalculationAutomatic\n\n\nTroubleshooting\n---------------\n\nBoth *comtypes* and *win32com* have caches for the python code backing the Excel object model. If \nthese caches somehow become corrupted, it can result in strange COM errors. It is safe to delete \nthese caches and let the library regenerate them. The caches are located at:\n\n * *comtypes*: `/site-packages/comtypes/gen`\n * *win32com*: run ``import win32com; print(win32com.__gen_path__)``\n\nSee `for example `_\n\nNote: as of 25-Jan-2022, *comtypes* has been observed to give the wrong answer for a call to\n`xloil.app().Workbooks(...)` so it is no longer used as the default whilst this is investigated.\n"
},
{
"path": "docs/source/xlOil_Python/ExternalPackages.rst",
"content": "=============================\nxlOil Python Package Support\n=============================\n\nxlOil has built-in converters for several external libraries\n\n.. contents::\n :local:\n\n\nPandas\n------\n\nPandas support can be enabled in *xlOil* with:\n\n::\n\n import xloil.pandas\n\nThis registers a return converter which allows pandas dataframes to be returned\nfrom Excel functions in a natural table format. Not if a function always returns \na dataframe it is more performant to specify ``pandas.DataFrame`` as the return type\nannotation.\n\nThe annotation ``pandas.DataFrame`` can also be used for arguments. The converter by \ndefault expects a two dimensional array with headings in the first row.\n\nTo gain more control over the *DataFrame* conversion, use the annotion \n`xloil.pandas.PDFrame`. Examples:\n\n::\n\n @xlo.func\n def getDataField(data: PDFrame(headings=True), columns) -> PDFrame(headings=False):\n return data[columnName]\n\n @xlo.func\n def readDatedData(df: PDFrame(headings=True, index=['Date', 'Type'], dates=['Date'])):\n # df will have a pandas.MultiIndex index\n return df\n\n\nThe parameters have slightly different interpretations when reading or outputting arguments.\n\nThe `headings`` parameter when reading, if True, interprets the first row as column heading or \nif it is an int inperets the first *N* rows as a *pandas.MultiIndex* heading. When outputting, \nif it is True/False outputs column headings or not.\n\nThe `index`` parameter when reading specifies column(s) which should be set as the index: xloil \ncalls `DataFrame.set_index()`, so a column name or list-like of columns names can be \ngiven. When writing: if *index* is set to False, the index is not output, otherwise it is.\n\nThe `dates` parameters specifies which columns to convert from from Excel serial date numbers \nto *numpy.datetime64*. Since Excel stores dates as floating points it is not possible for\nxlOil to identify date columns automatically. This parameter has no effect when outputting as \n*datetime* arrays are converted automatically.\n\nWe can call the *PDFrame* converter in the function itself if we want to control the arguments\npassed to it based on the function's inputs (this isn't possible if it is used as a decorator).\n\n::\n\n @xlo.func\n def dFrameMultiHeadings(\n df: PDFrame(headings=2),\n outputHeadings=False):\n return PDFrame(headings=outputHeadings)(df)\n\n\nSee :doc:`Example` for more examples.\n\nMatplotlib\n----------\n\nImporting ``xloil.matplotlib`` defines a return converter so matplotlib figures\ncan be returned from worksheet functions. By default they are resized to the cell.\nSubseqent figures returned from the same cell overwrite previous ones.\nReturning a figure requires setting ``macro=True`` in the :obj:`xloil.func` declaration.\n\n::\n\n import xloil.matplotlib\n from matplotlib import pyplot\n \n @xlo.func(macro=True)\n def pyTestPlot(x, y, **kwargs):\n fig = pyplot.figure()\n ax.plot(x, y, **kwargs)\n return fig\n\n @xlo.func(macro=True)\n def pyTestPlot(x, y, width, height, **kwargs):\n fig = pyplot.figure()\n ax.plot(x, y, **kwargs)\n return xloil.matplotlib.ReturnFigure(size=(width, height), pos='top')(fig)\n\nPIL / pillow\n------------\n\nImporting ``xloil.pillow`` defines a return converter so PIL images\ncan be returned from worksheet functions. By default they are resized to the cell.\nSubseqent images returned from the same cell overwrite previous ones.\nReturning an image requires setting ``macro=True`` in the :obj:`xloil.func` declaration.\n\n::\n\n import xloil.pillow\n from PIL import Image\n\n @xlo.func(macro=True)\n def pyTestPic():\n im = Image.open(\"MyPic.jpg\")\n return im\n"
},
{
"path": "docs/source/xlOil_Python/FAQ.rst",
"content": "======================\nxlOil Python Questions\n======================\n\n.. contents::\n :local:\n\n\nImportError: Typelib different than module\n------------------------------------------\n\nWhen using `comtypes` for COM support, then auto-generated modules can go out of sync, for example, if\nyou upgrade `comtypes`. Fix this at a command prompt with \n\n.. highlight:: dosbatch\n\n:: \n\n C:\\ > where clear_comtypes_cache.py\n C:\\MyPythonDist\\Scripts\\clear_comtypes_cache.py\n C:\\ > python C:\\MyPythonDist\\Scripts\\clear_comtypes_cache.py -y\n\nYou'll probably need to restart Excel.\n\n\nIntellisense / Function Context Help\n------------------------------------\n\nTo activate pop-up function help, follow the instructions here: :any:`concepts-intellisense`.\n\n\nAuto-reload doesn't reload a module\n-----------------------------------\n\nxlOil only watches for changes in modules which contain :any:`xloil.func` regisrations: it does\nnot do a deep scan / reload of all dependent modules as this could include large portions of your\npython distribution!\n\nDynamically Resized Arrays\n--------------------------\n\nThis is available in Office 365. It would be possible to replicate this behaviour in older Excel \nversions however it is somewhat tricky, as the output ranges are not 'protected' as they are with \narray formulae or with the Office 365 support. The code would need to:\n \n 1. Hook the *AfterCalculate* event.\n 2. Remember which functions output arrays in the current calc cycle and their calling cell.\n 3. Remember which functions output arrays in the previous calc cycle and their calling cell.\n 4. On *AfterCalculate*, loop through the functions in (2) writing their array to the worksheet.\n 5. When writing the array, take care to clear any previous result from (3) but not to overwrite\n any other non-empty cells.\n 6. Clear the ranges for functions in (3) but not in (2).\n 7. Carefully handle the case where the output range for a function in (3) has been edited, for example\n it may now contain a function in (2)!\n\nUnlike the built-in support in Office 365, the written arrays would be static data so, for example,\nfunction dependency tracing would not work on them (except the top left entry).\n\n\nThis application failed to start because it could not find or load the Qt platform plugin \"windows\"\n---------------------------------------------------------------------------------------------------\n\nUnder Anaconda (and possibly other distributions), Qt is installed outside the usual site-packages \nlocation. A *qt.conf* file in the root dir directs Qt to the correct place. However under Windows, \nQt will only look for this file in the directory returned by GetModuleFileName or in :/qt/etc/ which \nis unlikely to exist or be easily creatable on Windows. (See https://doc.qt.io/qt-6/qt-conf.html)\nIn our case GetModuleFileName always returns Excel.exe.\n\nxlOil attempts to work around this by passing the correct location to Qt on start up, however for \nnon-standard locations like virtual environments it may be necessary to set the \n`QT_QPA_PLATFORM_PLUGIN_PATH` environment variable explicitly in xlOil.ini. If `QT_QPA_PLATFORM_PLUGIN_PATH`\nis set, xlOil will not try to workaround this issue, so verify the value of this variable in the\nlauching environment.\n\n\nwin32com / pythoncom: has no attribute 'CLSIDToClassMap' \n----------------------------------------------------------------------\n\nThe cache used by *win32com* has somehow gone wrong. Deleting the cache dir will cause a rebuild\nwhich usually resolves the issue. The location of this directory can be discovered with\n\n::\n\n python -c \"import win32com; print(win32com.__gen_path__)\"\n\nEither delete the entire *gen_py* directory or just the subdirectory corresponding to the CLSID\nwhich is indicated in the error.\n\n\nCould not connect COM: trying again in 1 second\n-----------------------------------------------\n\nIf this appears frequently in your log file, it may be because Excel is not opening a blank \nworkbook on load. It is a long-standing Excel bug that the COM server is not properly \nstarted until a workbook is opened: xlOil needs this COM server to register ribbon components,\nso waits in a loop until is is available. To make Excel open a blank workbook on load (the\npre-Office 2016 behaviour), go to the *File* menu, then *Options*, under *General*, find\n*Start up options*, uncheck the \"Show the Start screen when this application starts\" box.\n"
},
{
"path": "docs/source/xlOil_Python/Functions.rst",
"content": "==================================\nxlOil Python Registering Functions\n==================================\n\n.. contents::\n :local:\n\nThere are several ways a python function can be registered with Excel via arguments to \n:any:`xloil.func` decorator.\n\n::\n\n @xloil.func\n def Greeting(who):\n return \"Hello \" + who\n\n\nLocal Functions\n---------------\n\nWhen registering functions from :ref:`xlOil_Python/Concepts:Workbook Modules`, xlOil defaults to making\nany declared functions \"local\": this means their scope is limited to the workbook.\nIt also means the function is automatically macro-type (xlOil achieves this by creating \na VBA stub to invoke them).\n\nThis behaviour can be overriden by `local` argument:\n\n::\n\n @xloil.func(local=False)\n def Greeting(who):\n return \"Hello \" + who\n\n\nLocal functions have some limitations compared to global scope ones:\n- No native async or threadsafe, but RTD async is OK\n- Slower due to the VBA redirect\n- Associated workbook must be saved as macro-enabled (xlsm extension)\n- No function wizard help, but CTRL+SHIFT+A to show argument names is available\n\n(Technical note: It is possible to use the Application.MacroOptions call to add help to the \nfunction wizard for VBA, but identically named functions will conflict which rather defeats \nthe purpose of local functions).\n\n\nAsync and RTD Functions\n-----------------------\n\nRTD (real time data) functions are able to return values independently of Excel's \ncalculation cycle and correspond to `async generators `_\nin python. For example, the function below returns the time every two seconds:\n\n::\n\n import xloil, datetime, asyncio\n\n @xloil.func\n async def pyClock():\n while True:\n await asyncio.sleep(2)\n yield datetime.datetime.now()\n\nThis is discussed in detail in :ref:`xlOil_Python/Rtd:Introduction`.\n\n\nCommands, Macros & Subroutines\n------------------------------\n\n'Macros' in VBA are declared as subroutines (``Sub``/``End Sub``) and do not return a value. \nThese functions run outside the calculation cycle, triggered by some user interaction such\nas a button. They run on Excel's main thread and have full permissions on the Excel object \nmodel. In the XLL interface, these are called 'commands' in the XLL interface and xlOil uses \nthis terminology.\n\nPrograms which heavily use the :ref:`xlOil_Python/ExcelApplication:Introduction` object model are usually written as \ncommands.\n\n::\n\n @xloil.func(command=True)\n def pressRunTests():\n\n r = xloil.Range(\"TestArea\")\n r.clear()\n r.set(\"Foo\")\n\n ...\n\nIf not :ref:`xlOil_Python/Functions:Local Functions`, XLL commands are hidden and not displayed in \ndialog boxes for running macros, such as Excel's macro viewer (Alt+F8). However their \nnames can be entered anywhere a valid command name is required, including in the macro\nviewer.\n\n\nMulti-threaded functions\n------------------------\n\nDeclaring a function re-entrant tells Excel it can be called on all of its calculation\nthreads simultaneously - any other function is invoked on the main thread. \n\n:ref:`xlOil_Python/Functions:Local Functions` cannot be declared re-entrant.\n\nSince python (at least CPython) is single-threaded there is no direct performance\nbenefit from enabling this. However, if you make frequent calls to C-based libraries \nspeed gains may be possible.\n\n::\n\n import xloil, ctypes\n\n @xloil.func(local=False, threaded=True)\n def threadsafe(x: float) -> int:\n # Do lots of calculations\n ...\n # Return the thread ID to prove the functions were executed on different threads\n return ctypes.windll.kernel32.GetCurrentThreadId(None)\n\n\nDynamic Registration\n--------------------\n\nFunctions for registration can be specified at runtime without the need to decorate them\nwith :any:`xloil.func`. \n\n.. note::\n Although Excel will let you, avoid doing this from (non-async) worksheet functions\n since creating new functions *during* Excel's calculation cycle is likely to cause\n instability.\n\nThe :any:`xloil.import_functions` call provides an analogue of ``from X import Y as Z`` \nwith Excel UDFs. A simple usage is:\n\n::\n\n xloil.import_functions(\"c:/lib/AnotherFile.py\", names=[\"greet\"], as_names=[\"PyGreet\"])\n\n\nwhere AnotherFile.py contains:\n\n::\n\n def greet(x:str):\n return f\"Hello {x}!\"\n\nWe specify the Excel name of the function explicitly, if we omitted this, the function \nwould be registered with its python name. In Excel you can then use the formula \n``=greet(\"World\")``.\n\nTyping annotations are respected, as are doc-strings - the import behaves as if we had \ndecorated the function with :any:`xloil.func`.\n\nIn a worksheet, :any:`xloil.import_functions` is exposed as ``xloImport`` with the same \narguments.\n\nSince the import machinery can register *any* callable, including class constructors,\nyou cane be a little creative. For example, the following cell formulae will\ncreate a *pandas* *DataFrame* from the range `C1:F5`, sum over rows and take the average\nof the result.\n\n::\n\n [A1] : =xloImport(\"pandas\",\"DataFrame\")\n\n [A2] : =DataFrame(C1:F5)\n\n [A3] : =xloAttr(xloAttrObj(A2,\"sum\",{\"axis\",1}), \"mean\")\n\n\nNotice we used ``xloAttrObj`` - the output of this is always a cache reference. This stops \nxlOil from trying to convert the result to an Excel value. Since a *DataFrame* is iterable\nit would otherwise output *DataFrame.index* as an array. Also note the convenient use of\n`array constants `_\nto specify keyword arguments.\n\nMore controlled registration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n:any:`xloil.register_functions`\n\n::\n\n class Closure:\n self._total = 0\n def __call__(self, x):\n self._total += x\n return x\n \n funcs.append(\n xlo.func(fn=Closure(), name=f\"dynamic1\", register=False)\n )\n\n xlo.register_functions(funcs, sys.modules[__name__])\n\n Loads functions from the specified source and registers them in Excel. The functions\n do not have to be decorated, but are imported as if they were decorated with ``xloil.func``.\n So if the functions have typing annotations, they are respected where possible.\n\n This function is intended \n\n Imports the specifed python module and registers any it for xloil \n functions it contains. Leaving the argument blank loads or reloads the\n workbook module for the calling sheet, i.e. the file `WorkbookName.py`."
},
{
"path": "docs/source/xlOil_Python/GettingStarted.rst",
"content": "=========================\nxlOil Python Introduction\n=========================\n\n.. contents::\n :local:\n\nIntroduction\n------------\n\nThe Python plugin for xlOil primarily allows creation of Excel functions and macros \nbacked by Python code. In addition it offers full control over GUI objects and an \ninterface for Excel automation: driving the application in code.\n\nWhen loaded by xlOil, *xlOil_Python* loads specified python modules, looking for functions \nto add to Excel's global name scope, like an Excel addin. The plugin can also look for modules \nof the form .py and load these too, this is like creating a VBA code module for \na workbook. Any python module which contains Excel functions is watched for file modifications so \ncode changes are reflected immediately in Excel.\n\n*xlOil_Python* is tightly integrated with numpy, allowing creation of fast Excel array \nfunctions.\n\n*xlOil_Python* can be imported in python code to allow remote control of an Excel application.\nSee :doc:`ExcelApplication`\n\nFor examples of worksheet functions and GUI controls have a look at :doc:`Example` and\n:ref:`core-example-sheets`.\n\nGetting Started\n---------------\n\n**You must use the same bit-ness of python and Excel**. So if your Excel is 32-bit, you must\ninstall xloil using a 32-bit python distibution.\n\nRun the following at a command prompt with python environment settings:\n\n::\n\n pip install xlOil\n \nxlOil can now be imported to allow remote control of an Excel application. See :doc:`ExcelApplication`\n\nTo install the addin which allows you to create python-based Excel functions, type:\n\n::\n\n xloil install\n\nThis call registers the xlOil addin with Excel and places a settings file at\n`%APPDATA%/xlOil/xlOil.ini`. The settings file describes the python modules \nwhich will be loaded and sets the paths to the python distribution. xlOil should \nset the python paths automatically, but they can be overriden if required.\n\nTo test the setup, you can try the python example sheet: :ref:`core-example-sheets`.\n\n.. note:: \n It's not necessary for ``xlOil.xll`` to be registered in this way: you can just\n drop it into your Excel session when required. \n\nYou now have three ways to get xlOil to load your python code.\n\n\nMy first xlOil module\n~~~~~~~~~~~~~~~~~~~~~\n\nCreate a `MyTest.py` file with the following lines:\n\n::\n\n import xloil as xlo\n\n @xlo.func\n def Greeting(who):\n return \"Hello \" + who\n\nOpen Excel and use the *xlOil* ribbon toolbar to ensure the search paths include\nthe directory containing `MyTest.py`. Then add 'MyTest' to the *Load Modules* \nfield, separating entries with a comma. The order of these steps matters because \nediting the *Load Modules* field triggers a load of all newly added modules.\n\nCall the `=Greeting(\"world\")` function in a cell.\n\n\nMy first workbook module\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nCreate an Excel workbook called `MyBook`. In the same directory, create a\nfile `MyBook.py` containing the following:\n\n::\n\n import xloil as xlo\n\n @xlo.func\n def Adder(x, y):\n return x + y\n\nYou need to open and close `MyBook` in Excel for xlOil to find the python file.\nNow try invoking the `=Adder()` function - it can also add arrays!\n\nIf this isn't working, ensure that \"Trust access to the VBA object model\" is\nchecked in *Excel Options -> Trust Centre -> Macro Settings* - this setting\nis off by default.\n\nUsing the Ribbon\n----------------\n\nxlOil's Ribbon toolbar can:\n\n * Change the python environment (reqires restart)\n * Select modules to load at startup and *sys.path* to set\n * Open the log file\n * Open a console to interact with the embedded python environment\n * Choose a debugger, see :ref:'xlOil_Python/Debugging'\n * Select date formats to use when parsing strings\n\nThe toolbar edits the settings file so that changes persist. The ribbon is enabled by\nbut can be disabled by removing it from the specified *Load Modules*.\n\n.. note::\n\n If you have an old ini file (prior to v0.15), you will need to upgrade it to use the \n ribbon toolbar. Remove the old ini file and remove/install xlOil.\n\nTroubleshooting\n---------------\n\nIf xlOil detects a serious load error, it pops up a log window to alert you (this can\nbe turned off). If it succesfully loaded the core DLL a log file will also be created\nin `%APPDATA%/xlOil` next to `xlOil.ini`. The worksheet function `=xloLog()` will tell \nyou where this file is.\n\nNormally a python distribution or environment can be loaded with only the location of \n*python.exe* passed via the `PYTHONEXECUTABLE` environment varaible. For more complex\nsetups, you may need to set the python paths, i.e. `PATH` and `PYTHONPATH` and maybe even \n`PYTHONHOME`, in the `xlOil.ini` file for xlOil to load your python distribution.\n\nIf the xlOil ribbon does not appear, check that `xloil.xloil_ribbon` appears in the\n*LoadModules* key in the ini file.\n\nIntellisense / Function Context Help\n------------------------------------\n\nTo activate pop-up function help, follow the instructions here: :any:`concepts-intellisense`.\n"
},
{
"path": "docs/source/xlOil_Python/Jupyter.rst",
"content": "=========================\nxlOil Jupyter Interaction\n=========================\n\n.. contents::\n :local:\n \nIntroduction\n------------\n\nxlOil can connect to a Jupyter python kernel, allowing interaction between a Jupyter notebook \nand Excel. To use this functionality, either run `=xloPyLoad(\"xloil.jupyter\")` in a cell or\nload the `xloil.jupyter` module by specifying it in the `xlOil.ini` file:\n\n::\n\n ...\n\n [xlOil_Python]\n LoadModules=[\"xloil.jupyter\"]\n\nTo establish the connection, call the `xloJpyConnect` function. You pass it one of the following:\n\n 1. The name of a notebook e.g. `MyBook.ipynb`. In this case all local jupyter instances\n will be searched to find which one has this notebook open.\n 2. The full URL to the notebook, e.g. \n `http://localhost:8888/notebooks/MyBook.ipynb?token=ac3894ab667fa1f3e4f7fe473fa89566a1580cdb49a2649b`\n 3. The `kernel-xxxx-xxx-xxx.json` file which is specified in the output of running \n the magic `%connect_info` in a Jupyter cell (no file path is required).\n\nThe `xloJpyConnect` function will return a cache reference.\n\n.. note:: \n\n The targeted jupyter kernel can be running any version of Python 3 and does not need to\n to have the `xloil` package installed.\n\n\nRegistering an Excel function from Jupyter\n------------------------------------------\n\nAfter the connection is estabilished, any function created in the kernel and decorated with\n`@xloil.func` will be registed in Excel just as if it had been loaded by xlOil in the normal way.\nThe function will be run in the context of the kernel and the result returned asynchronously \nto Excel.\n\n.. note:: \n\n Any `@xloil.func` declarations prior to connection will be ignored, so part of the \n jupyter notebook may need to be re-calculated to ensure functions are registed\n\n\nWatching a variable in a Jupyter notebook\n-----------------------------------------\n\nThe function `=xloJpyWatch(Connection, VarName)` can dynamically capture the value of any \nglobal variable in the kernel. It is an RTD function so automatically updates when the variable\nis changed.\n\nRunning code in the kernel\n--------------------------\n\nCalling `xloJpyRun` executes the provided string as python code in the kernel, captures the \nresult and returns it to Excel. xloJpyRun processes the code string as a `format` string using \npassing the *repr* of any additional arguments, that is, it executes \n`code_string.format(repr(arg1), repr(arg2), ...)`\n\nExamples\n--------\n\nIn an Excel cell enter:\n\n::\n\n =xloJpyRun(, \"{} + {}\", 3, 4)\n\n\nExecute the following in a jupyter cell in a connected notebook:\n\n::\n\n @xloil.func\n def jptest(x):\n return f\"Jupyter says {x}\"\n\nWhen xlOil connects to the kernel it will automatically import xlOil, although it does \nnot cause a problem if re-imported.\n\nNow try entering `=jptest(\"hi\")` in Excel!\n\n\nUsing COM Automation\n--------------------\n\nIf the *jupyter* kernel has the *xloil* package installed, we can turn the tables on the \nconnected Excel application and control it using COM automtion. Executing the following\nin the jupyter kernel will add a new workbook to the connected Excel:\n\n::\n\n app = xloil.app()\n app.workbooks.add()\n\nSee :ref:`xlOil_Python/ExcelApplication:Introduction` for full details on the :any:`xloil.Application` \nobject and COM automation support.\n\n\nLimitations\n-----------\n\nFunctions declared in the kernel cannot specify the `async` or `rtd` arguments: they are \nautomatically of RTD async type to stop the kernel blocking Excel's calculation cycle! \nThey cannot be multi-threaded, although xlOil can connect to more than one kernel \nsimultaneously and exection in each kernel will be concurrent.\n\nRegistered kernel-based functions have addin/global scope in Excel. Any `@xloil.func` \ndeclarations prior to connection will be ignored, even if `xloil` was imported. \n\nThere is reasonable overhead in the machinery required to pass the function arguments to \njupyter and process the result: all transport is via strings, so peformance degredation \nmay be noticable for a large number of calls or for large arrays.\n\n"
},
{
"path": "docs/source/xlOil_Python/ModuleReference.rst",
"content": "=================================\nxlOil Python Module Reference\n=================================\n\n.. contents::\n :local:\n\nDeclaring Worksheet Functions\n-----------------------------\n\n.. currentmodule:: xloil\n\n.. autosummary::\n\tAllowRange\n\tArg\n\tArray\n\tCache\n\tCannotConvert\n\tCellError\n\tExcelArray\n\tFastArray\t\n\tSingleValue\n\tfunc\n\tconverter\n\treturner\n\timport_functions\n\tregister_functions\n\tderegister_functions\n\tscan_module\n\n.. automodule:: xloil\n\t:members: Arg,Array,Cache,CannotConvert,CellError,ExcelArray,FastArray,SingleValue,func,converter,returner,import_functions,register_functions,deregister_functions,scan_module\n\t:imported-members:\n\t:undoc-members:\n\n.. autodata:: AllowRange\n\nExcel Object Model\n------------------\n\n.. currentmodule:: xloil\n\n.. autosummary::\n\tworkbooks\n\tworksheets\n\tapp\n\tactive_worksheet\n\tactive_workbook\n\tApplication\n\tCaller\n\tRange\n\tWorkbook\n\tWorksheet\n\tExcelWindow\n\tExcelWindows\n\tWorkbooks\n\tWorksheets\n\n.. autodata:: workbooks\n\t\n.. autodata:: worksheets\n\t\n.. autofunction:: app\n\n.. autofunction:: active_worksheet\n\n.. autofunction:: active_workbook\n\n.. autoclass:: Application\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\t:special-members: __enter__, __exit__\n\n.. autoclass:: Caller\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\n.. autoclass:: Range\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\t:special-members: __getitem__\n\n.. autoclass:: Workbook\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\t:special-members: __getitem__\n\n.. autoclass:: Worksheet\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\t:special-members: __getitem__, __setitem__\n\n.. autoclass:: ExcelWindow\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\n.. autoclass:: ExcelWindows\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\n.. autoclass:: Workbooks\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\n.. autoclass:: Worksheets\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\n.. autoclass:: PauseExcel\n\t:members: \n\n.. automodule:: xloil\n\t:members: SpecialCells\n\t:imported-members:\n\t:undoc-members:\n\n\nRTD Functions\n-------------\n\n.. currentmodule:: xloil\n\n.. autosummary::\n\tRtdPublisher\n\tRtdServer\n\txloil.rtd.subscribe\n\txloil.rtd.RtdSimplePublisher\n\n.. autoclass:: RtdPublisher\n\t:members:\n\t\n.. autoclass:: RtdServer\n\t:members:\n\n.. automodule:: xloil.rtd\n\t:members:\n\n\nGUI Interaction\n---------------\n\n.. currentmodule:: xloil\n\n.. autosummary::\n\tStatusBar\n\tExcelGUI\n\tTaskPaneFrame\n\tRibbonControl\n\txloil.gui.CustomTaskPane\n\txloil.gui.find_task_pane\n\txloil.gui.qtpy.Qt_thread\n\txloil.gui.qtpy.QtThreadTaskPane\n\txloil.gui.tkinter.Tk_thread\n\txloil.gui.tkinter.TkThreadTaskPane\n\txloil.gui.wx.wx_thread\n\txloil.gui.wx.WxThreadTaskPane\n\n.. autoclass:: StatusBar\n\t:members:\n\n.. autoclass:: ExcelGUI\n\t:members:\n.. autoclass:: TaskPaneFrame\n\t:members:\n.. autoclass:: RibbonControl\n\t:members:\n\n.. automodule:: xloil.gui\n\t:members: CustomTaskPane \n\n.. autofunction:: find_task_pane\n\n.. automodule:: xloil.gui.qtpy\n\t:members: Qt_thread, QtThreadTaskPane\n\t:inherited-members:\n\n.. automodule:: xloil.gui.tkinter\n\t:members: Tk_thread, TkThreadTaskPane\t\n\t:inherited-members:\n\n.. automodule:: xloil.gui.wx\n\t:members: wx_thread, WxThreadTaskPane\t\n\t:inherited-members:\n\nEvents\n------\n\n.. currentmodule:: xloil.event\n\n.. automodule:: xloil.event\n\n.. autoclass:: Event\n\t:members:\n\t:special-members: __iadd__, __isub__\n\n.. autofunction:: pause\n.. autofunction:: allow\n\n.. autodata:: AfterCalculate\n.. autodata:: WorkbookOpen\n.. autodata:: NewWorkbook\n.. autodata:: SheetSelectionChange\n.. autodata:: SheetBeforeDoubleClick\n.. autodata:: SheetBeforeRightClick\n.. autodata:: SheetActivate\n.. autodata:: SheetDeactivate\n.. autodata:: SheetCalculate\n.. autodata:: SheetChange\n.. autodata:: WorkbookAfterClose\n.. autodata:: WorkbookRename\n.. autodata:: WorkbookActivate\n.. autodata:: WorkbookDeactivate\n.. autodata:: WorkbookBeforeClose\n.. autodata:: WorkbookBeforeSave\n.. autodata:: WorkbookAfterSave\n.. autodata:: WorkbookBeforePrint\n.. autodata:: WorkbookNewSheet\n.. autodata:: WorkbookAddinInstall\n.. autodata:: WorkbookAddinUninstall\n.. autodata:: XllAdd\n.. autodata:: XllRemove\n.. autodata:: ComAddinsUpdate\n.. autodata:: PyBye\n.. autodata:: UserException\n\n\nEverything else\n---------------\n\n.. currentmodule:: xloil\n\n.. autosummary::\n\tin_wizard\n\tget_async_loop\n\tget_event_loop\n\tfrom_excel_date\n\tdate_formats\n\tlinked_workbook\n\texcel_state\n\tcheck_abort\n\tAddress\n\trun\n\trun_async\n\tcall\n\tcall_async\n\texcel_callback\n\tcache\n\tAddin\n\tsource_addin\n\txloil_addins\n\tcore_addin\n\txloil._core._AddinsDict\n\txloil._core._DateFormatList\n\txloil._core._LogWriter\n\txloil.logging.log\n\txloil.debug.use_debugger\n\n.. autoclass:: ObjectCache\n\t:members: \n\n.. autodata:: cache\n\t:annotation: = ObjectCache\n\t:no-value:\n\n.. automodule:: xloil\n\t:members: in_wizard,get_async_loop,get_event_loop,from_excel_date,linked_workbook,source_addin,excel_state,run,run_async,call,call_async,excel_callback,source_addin,xloil_addins,core_addin,check_abort\n\t:imported-members:\n\t:undoc-members:\n\n.. autoclass:: Address\n\t:members:\n\n.. autodata:: date_formats\n\t:annotation: = _DateFormatList\n\t:no-value:\n\n.. autoclass:: ExcelState\n\t:members: \n\t:inherited-members:\n\t:undoc-members:\n\n.. autoclass:: Addin\n\t:members:\n\n.. autodata:: xloil_addins\n\t:annotation: = _AddinsDict\n\t:no-value:\n\n.. automodule:: xloil._core\n\t:members: _AddinsDict, _DateFormatList, _LogWriter\n\n.. automodule:: xloil.logging\n\t:members: \n\n.. automodule:: xloil.debug\n\t:members:\n\n\n\nExternal libraries\n------------------\n\n.. currentmodule:: xloil\n\n.. autosummary::\n\tinsert_cell_image\n\txloil.pandas.PDFrame\n\txloil.pillow.ReturnImage\n\txloil.matplotlib.ReturnFigure\n\n.. autofunction:: insert_cell_image\n\n.. automodule:: xloil.pandas\n\t:members: PDFrame\n.. automodule:: xloil.pillow\n\t:members: ReturnImage\n.. automodule:: xloil.matplotlib\n\t:members: ReturnFigure\n\n"
},
{
"path": "docs/source/xlOil_Python/Rtd.rst",
"content": "======================\nxlOil Python Async/Rtd\n======================\n\nIntroduction\n------------\n\nRTD (real time data) functions are able to return values independently of Excel's calculation\ncycle. The classic example of this is a stock ticker with live prices. It is easy to create\nan RTD function in *xlOil_Python* -- the following gives a ticking clock:\n\n::\n\n import xloil, datetime, asyncio\n\n @xloil.func\n async def pyClock():\n while True:\n yield datetime.datetime.now()\n await asyncio.sleep(2)\n \n\nNote that calculation must be on automatic mode or you will not see the updates. \nWhatever parameter is passed to `sleep` the clock will not tick faster than 2 seconds - this due \nto the `RTD throttle interval `_\nWhich can bed changed via `xlo.app().RTD.ThrottleInterval = `, however \nreducing it below the default of 2000 may impair performance. The change is global and\npersists when Excel is restarted, so give some consideration to altering the value.\n\nAny `async def` function is handled in xlOil as using RTD by default. It is possible to \nuse Excel's native async support, but this has some drawbacks, discussed in :any:`concepts-rtd-async`\n\nThere is another advantage of RTD: RTD functions can be 'local', i.e. called through a \nVBA stub associated with the workbook, which avoids cluttering the global function namespace.\n\nImproving RTD performance (specifying topics)\n---------------------------------------------\n\nRegistering an `async def` function as described above has a certain overhead: excel will \ncall the function multiple times to fetch the result, so xlOil must store and compare all \nthe function arguments to figure out if Excel wants the result of a previous calculation \nor to starta new calculation with new arguments.\n\nIf an RTD `topic`, i.e. a unique string identifier, is easy to determine we can take over\nresponsibility for generating it manually.\n\n::\n\n # First create a new RTD COM server so the `topic` strings don't collide\n _rtdServer = xlo.RtdServer()\n \n @xloil.func\n def pyClock2(secs):\n\n async def fetch() -> dt.datetime:\n while True:\n await asyncio.sleep(secs)\n yield dt.datetime.now()\n \n return xloil.rtd.subscribe(_rtdServer, \"Time:\" + str(secs), fetch)\n\nThe `subscribe` call will look for an existing publisher, i.e. a clock with `secs` interval,\nand return the value if one is found. Otherwise it will run the coroutine and publish\nthe value. Note the coroute specifies a return type: this is handled with a return converter\njust like functions decorated with :any:`xloil.func`.\n\nThe instance of the :obj:`xloil.RtdServer` object creates and registers a COM class. When xlOil is\nunloaded, the server will be unregistered and destroyed. Since we created our own server the \nserver, we can choose the convention for these topic strings (i.e. the unique publisher ID).\n\nNote that we do not need to declare the outer function async, the `subscribe()` call notifies \nExcel that this function should be treated as RTD.\n\nxlOil's RTD Interface\n---------------------\n\nIf even finer-grained control of the RTD mechanism is required (such as in the `xloil_jupyter`\nmodule, :doc:`Jupyter`), we can specify the publisher as described below.\n\nWe will follow the *UrlGetter* example in :doc:`ExampleRTD`. In this case we make the topics URLs. \nThe RTD workflow is to first check if a given topic has a publisher using `peek()`. If not, \nwe spin one up with :any:`xloil.RtdServer.start`. Then we :any:`xloil.RtdServer.subscribe` to \nthe topic which tells xlOil to call Excel's RTD function.\n\n:: \n\n _rtdServer = xlo.RtdServer()\n\n @xlo.func\n def pyGetUrlLive(url):\n if _rtdServer.peek(url) is None:\n publisher = UrlGetter(url)\n _rtdServer.start(publisher)\n return _rtdServer.subscribe(url)\n\n\nThe publisher is the class which does the work. Its `connect()` method is called when a \nworksheet function calls `subscribe()` for its topic. The publisher should then start\nan async task to publish values.\n\nIf the worksheet function is subsequently changed or deleted, then `disconnect()` is called. \nWhen a publisher has no subscribers it should save CPU cycles by stopping its task. A \npublisher should also stop when requested by the `stop()` method.\n\nApart from `connect()` the remaining methods are boilerplate at least for a simple publisher.\nThe boilerplate can be avoided by use of the `RtdSimplePublisher` class, then only the\n`run()` method in the below requires definition. \n\n::\n\n class UrlGetter(xlo.RtdPublisher):\n\n def __init__(self, url):\n # You *must* call this ctor explicitly or the python binding library will crash\n super().__init__() \n self._url = url\n self._task = None\n \n def connect(self, num_subscribers):\n if self.done():\n async def run():\n try:\n while True:\n data = await getUrlAsync(self._url);\n _rtdServer.publish(self._url, data)\n await asyncio.sleep(4) \n except Exception as e:\n _rtdServer.publish(self._url, e)\n \n self._task = xlo.get_event_loop().create_task(run())\n \n def disconnect(self, num_subscribers):\n if num_subscribers == 0:\n self.stop()\n # Returning True schedules the publisher for destruction\n return True \n \n def stop(self):\n if self._task is not None: \n self._task.cancel()\n \n def done(self):\n return self._task is None or self._task.done()\n \n def topic(self):\n return self._url\n\nThe final task, left as an exercise, is to write `getUrlAsync()`: an async function which \nfetches a URL. It is straightforward with the `aiohttp` library.\n"
},
{
"path": "docs/source/xlOil_Python/TypeConversion.rst",
"content": "============================\nxlOil Python Type Conversion\n============================\n\n.. contents::\n :local:\n\n\nArgument Types\n--------------\n\nxlOil function declarations in python look like:\n\n::\n\n @xlo.func\n def DoSomething(x, y:float):\n return x\n\nIf no type is specified for an argument, xlOil will dynamically choose a type based\non the argument provied by Excel, this can be one of:\n\n * *bool*\n * *int*\n * *str*\n * *float*\n * *numpy.ndarray* (if an array or range is passed)\n * :py:class:`xloil.CellError`\n\nUsing ``typing`` annotations improves performance at the expense of static\ntyping. Annonations also allow for user-defined conversion to any python type. \nxlOil has built-in support for the following annotations:\n\n.. list-table:: Supported argument annotations\n :widths: 20 50\n :header-rows: 1\n\n * - Type\n - Comment\n * - *bool*\n - \n * - *int*\n -\n * - *str*\n -\n * - *float*\n -\n * - *numpy.ndarray*\n - Use the :py:class:`xloil.Array` annotation rather than ndarray directly\n * - *dict*\n - Requires a 2-column input array. The first column is interpreted as keys\n * - *tuple*\n - Gives a tuple of tuple-of-tuples depending on number of input dimensions\n * - *datetime.date*\n - See :ref:`xlOil_Python/TypeConversion:Dates`\n * - *datetime.datetime*\n - See :ref:`xlOil_Python/TypeConversion:Dates`\n * - *pandas.DataFrame*\n - Can use the :py:class:`xloil.pandas.PDFrame` annotation for more conversion options. \n Need to `import xloil.pandas` before use.\n * - *pandas.Timestamp*\n - Need to `import xloil.pandas` before use.\n * - :py:class:`xloil.Range`\n - See :ref:`xlOil_Python/TypeConversion:Range Arguments`\n * - :py:class:`xloil.AllowRange`\n - See :ref:`xlOil_Python/TypeConversion:Range Arguments` \n * - \n - See :ref:`xlOil_Python/TypeConversion:Custom Type Conversion`\n\nAnnotations which xlOil does not understand are ignored.\n\nExample:\n\n::\n\n @xlo.func\n def pySumNums(x: float, y: float, a: int = 2, b: int = 3) -> float:\n return x * a + y * b\n\n\nReturn Types\n------------\n\nLike argument types, xlOil can read return type annotations. If no annotation\nis specified xlOil tries the following conversions:\n \n * *None*\n * *int*\n * *float*\n * *numpy.ndarray*\n * *datetime*\n * :py:class:`xloil.CellError`\n * *str*\n * Registered custom return converters, see :ref:`xlOil_Python/TypeConversion:Custom Return Conversion`\n * iterable\n\nIf none of these succeeds, the object is placed in the cache, see :ref:`xlOil_Python/TypeConversion:Cached Objects`\n\n.. list-table:: Supported return type annotations\n :widths: 20 50\n :header-rows: 1\n\n * - Type\n - Comment\n * - *bool*\n - \n * - *int*\n -\n * - *str*\n -\n * - *float*\n -\n * - *numpy.ndarray*\n - Use the :py:class:`xloil.Array` annotation rather than ndarray directly\n * - *dict*\n - Outputs a 2-column array of key, value pairs\n * - *tuple*\n - A tuple of tuple-of-tuples produces a 1 or 2 dim array\n * - *datetime.date*\n - See :ref:`xlOil_Python/TypeConversion:Dates`\n * - *datetime.datetime*\n - See :ref:`xlOil_Python/TypeConversion:Dates`\n * - *pandas.DataFrame*\n - Can use the :py:class:`xloil.pandas.PDFrame` annotation for more conversion options. \n Need to `import xloil.pandas` before use.\n * - *pandas.Timestamp*\n - Need to `import xloil.pandas` before use.\n * - *PIL.Image*\n - See :ref:`xlOil_Python/TypeConversion:Returning Images and Plots`\n * - *matplotlib.pyplot.Figure*\n - See :ref:`xlOil_Python/TypeConversion:Returning Images and Plots`\n * - :py:class:`xloil.Cache`\n - Placed the return value in the python object cache, see :ref:`xlOil_Python/TypeConversion:Cached Objects`.\n * - :py:class:`xloil.SingleValue`\n - Ensures the output will be a single cell value, not an array.\n * - \n - See :ref:`xlOil_Python/TypeConversion:Custom Return Conversion`\n\nCached Objects\n--------------\n\nIf xlOil cannot convert a returned python object to Excel, it will place it in \nan object dictionary and return a reference string of the form\n\n``[SheetID]!CellNumber,#``\n\nxlOil automatically resolves cache string passed function arguments to their\nobjects. With this mechanism you can pass python objects opaquely between \nfunctions. You should not attempt to construct a cache string directly.\n\nFor example:\n\n::\n\n @xlo.func\n def make_lambda(pow):\n return lambda x: x ** pow\n\n @xlo.func\n def apply_lambda(f, x):\n return f(x)\n\nSince xlOil cannot convert a lambda function to an Excel object, it outputs a \ncache reference string. That string is automatically turned back into a lambda \nif passed as an argument to the second function.\n\nThe python cache is separate to the Core object cache accessed using `xloRef`\nand `xloVal`. The Core cache stores native Excel objects such as arrays.\nWhen reading functions arguments xlOil tries to lookup strings in both of these\ncaches. \n\nThe leading ** means xlOil can very quickly determine that a string\nisn't a cache reference, so the overhead of checking if every string argument\nis a cache object is very low in practice. \n\nUsing :any:`xloil.cache` it is possible to place objects into the cache. This \ncan be used an alternative to the :py:class:`xloil.Cache` decorator to allow\nthe function to choose whether or not to return a cache object. It could \nalso be used to return cached objects from commands or subroutines, but \nunderstand the object lifecycle before doing this\n\nCache Object Lifecycle\n~~~~~~~~~~~~~~~~~~~~~~\n\nxlOil uses the caller infomation provided by Excel to construct the cache \nstring. When invoked from a worksheet function, the caller info contains \nthe sheet and cell reference and so on each calculation cycle the same\ncache reference appears and the new cache object automatically overwrites \nthe previous one.\n\nWhen invoked from a source other than a worksheet function (there are several\npossibilies for this, see the help for `xlfCaller`), xlOil again generates a \nreference string based on the caller info. However, this may not be unique. \nIn addition, objects with the same caller info will replace those created \nduring a previous calculation cycle. For example, creating cache objects \nfrom a button clicked repeatedly will behave differently if Excel recalculates \nin between the clicks. To override this behaviour, the exact cache `key` can \nbe specified. For example, use Python's `id` function or the cell address \nbeing written to. When `key` is specified the user is responsible for managing\nthe lifecycle of their cache objects using `remove` in :any:`xloil.cache`.\n\n\nDates\n-----\n\nApplying the argument annotation ``datetime.datetime`` requests a date conversion. Returning \na ``datetime`` is allowed without a return annotation: the datetime will be converted to\nan Excel date number:\n\n::\n\n from datetime import datetime, timedelta\n @func\n def AddDay(date: datetime):\n return date + timedelta(days = 1)\n\n\nxlOil can interpret strings as dates. In the settings file, the key ``DateFormats`` \nspecifies an array of date formats to try when parsing strings. Naturally, adding more \nformats decreases performance. The formats use the C++ ``std::get_time`` syntax,\nsee https://en.cppreference.com/w/cpp/io/manip/get_time.\n\nSince ``std::get_time`` is **case-sensitive** on Windows, so is xlOil's date parsing\n(this may be fixed in a future release as it is quite annoying for month names).\n\nExcel has limited internal support for dates. There is no primitive date object \nbut cells containing numbers can be formatted as dates. This means that worksheet \nfunctions cannot tell whether numerical values are intended as dates - this applies\nto Excel built-in date functions as well. (It is possible to check for date formatting\nvia the COM interface but this would give behaviour inconsistent with the built-ins)\n\nExcel does not understand timezones and neither does ``std::get_time``, so these\nare currently unsupported.\n\n\nDicts\n-----\n\nWhen the ``dict`` *argument type* annotation is specified, xlOil expects a two-column \narray of(*string*, *value*) to be passed.\n\nUsing a ``dict`` *return type* annotation allows a ``dict`` to be returned as as a \ntwo column array. Without the annotation, the default iterable converter would be invoked, \nresulting in only the keys being output.\n\nVariable and Keyword Arguments\n-------------------------------\n\nIf keyword args (`**kwargs`) are specified, xlOil expects a two-column array of \n(*string*, *value*) to be passed, the same as using a ``dict`` annotation. For variable\nargs (`*args`) xlOil adds a large number of trailing optional arguments. The variable\nargument list is ended by the first missing argument. If both *kwargs* and *args* are \nspecified, their order is reversed in the Excel function declaration.\n\nThe following example shows dictionary and keyword aruments:\n\n::\n\n @xlo.func\n def pyTestKwargs(lookup: dict, **kwargs) -> dict:\n lookup.update(kwargs)\n return lookup\n\nThe number of trailing optional arguments is limited by the maxiumum number of arguments \nallowed by Excel, which is 255 for a worksheet function and 60 for a local function.\n\nRange Arguments\n---------------\n\nRange arguments allow a function to directly access a part of the worksheet. This \nallows macro functions to write to the worksheet or it can be used for optimisation\nif a function only requires a few values from a large input range.\n\nA function can only receive range arguments if it is declared as *macro-type*. In \naddition, attempting to write to a Range during Excel's calculation cycle will fail.\n\nAnnotating an argument with :py:class:`xlo.Range` will tell xlOil to pass the function an\n:py:class:`Range` object, or fail if this is not possible. An :py:class:`Range` \ncan only be created when the input argument explicitly points to a part of the worksheet, not \nan array output from another function.\n\nAnnotating an argument with :py:class:`xlo.AllowRange` will tell xlOil to pass an \n:py:class:`Range` object if possible, otherwise one of the other basic data types\n(int, str, array, etc.).\n\n\nCustom Type Conversion\n----------------------\n\nA custom type converter is a function or a class which serialises between a set \nof simple types understood by Excel and general python types.\n\nA type converter class is expected to implement at least one of ``read(self, val)`` \nand ``write(self, val)`` and be decorated with :py:func:`xloil.converter`.\nIt may take parameters in its constructor and hold state. \n\nA function can be interpreted as a type reader or writer depending on the parameters\npassed to the :py:func:`xloil.converter` decorator.\n\nThe ``read(self, val)`` method or a function decorated as a reader or argument converter \nshould be able to accept a value of: \n\n *int*, *bool*, *float*, *str*, :py:class:`xloil.ExcelArray`, :py:class:`CellError`, \n :py:class:`xloil.Range` (optional) \n\nand return a python object or raise an exception (ideally :py:class:`xloil.CannotConvert`).\n\nAn :py:class:`xloil.ExcelArray` represents an un-processed array argument, a\nhandle to the raw Excel object not yet converted to a *numpy* array. The converter\nmay opt to process only a part of this array for efficiency. \n\nA converter may be used by name in *typing* annotations for :py:func:`xloil.func` \nfunctions. In addition, the converter can register as the handler for a specific type \nwhich enables that type to be used in annotations. For registration, the converter must\nbe default-constructible (or be a function).\n\nBy decorating with ``@xloil.converter(range=True)``, the type converter can opt to\nreceive :py:class:`Range` arguments in addition to the other types.\n\n\n::\n\n @xlo.converter()\n def arg_doubler(x):\n if isinstance(x, xlo.ExcelArray):\n x = x.to_numpy()\n return 2 * x\n\n @xlo.func\n def pyTestCustomConv(x: arg_doubler):\n return x\n\n @xlo.converter(typeof=bytes, register=True)\n class StrToBytes:\n def __init__(self, encoding='utf-8'):\n self._encoding = encoding\n def read(self, val):\n return val.encode(self._encoding)\n def write(self, val):\n return val.decode(self._encoding)\n \n @xlo.func\n def Pad(text: bytes, size: int) -> StrToBytes('utf-8'):\n return text.center(size) \n\nCustom Return Conversion\n------------------------\n\nA return type converter should take a python object and return a simple type\nwhich xlOil knows how to return to Excel. It should raise :py:class:`xloil.CannotConvert` \nif it cannot handle the given object.\n\nIt can be a class implementing ``write(self, val)`` and decorated with \n:py:class:`xloil.converter` or a function decorated with :py:class:`xloil.returner`\nor :py:class:`xloil.converter`.\n\nA return converter can register as the handler for a specific type which enables that \ntype to be used in return annotations *and* allows xlOil to try to call \nthe converter for Excel functions with no return annotation, see :ref:`xlOil_Python/TypeConversion:Return Types`.\n \n\n::\n\n @xlo.returner(typeof=MyType, register=True)\n def mytypename(val):\n return val.__name__\n \n @xlo.func\n def MakeMyType():\n return MyType()\n \n\nReturning Images and Plots\n--------------------------\n\nBy using custom return converters you can return `PIL` or `pillow` image \nobjects from worksheet functions. The returned image can be automatically \nsized to the calling range, or any offset from it, but it floats like a \nnormal picture in Excel. Calling the worksheet function again removes\nthe previous image and replaces it with a new one.\n\n::\n\n import xloil.pillow\n from PIL import Image\n \n @xlo.func(macro=True) # macro permissions required\n def ShowPic(filename):\n return Image.open(filename)\n\n\nImporting ``xloil.pillow`` registers a custom return converter for ``PIL.Image``.\nTo gain control over the image size and position, use the :py:class:`xloil.pillow.ReturnImage`\nreturn annotation.\n\nSimilarly a matplotlib figure can be returned directly\n\n::\n\n import xloil.matplotlib\n\n @func(macro=True)\n def Plot(x, y):\n fig = pyplot.figure(figsize=(5,5))\n fig.add_subplot(111).plot(x, y)\n return fig\n\nImporting ``xloil.matplotlib`` registers a custom return converter for \n``matplotlib.pyplot.Figure``. To gain control over the plot size and position, \nuse the :py:class:`xloil.matplotlib.ReturnFigure` return annotation.\n\nBoth of these converters use :py:class:`xloil.insert_cell_image`.\n"
},
{
"path": "docs/source/xlOil_Python/index.rst",
"content": "============\nxlOil Python\n============\n\n.. toctree::\n :maxdepth: 4\n :caption: Contents\n\n GettingStarted\n Concepts\n Functions\n TypeConversion\n ExcelApplication\n CustomGUI\n Dynamic\n ExternalPackages\n BuiltInUDFs\n Jupyter\n Rtd\n Debugging\n DistributingAddins\n Example\n ExampleGUI\n ExampleRTD\n FAQ\n ModuleReference\n"
},
{
"path": "docs/source/xlOil_SQL/index.rst",
"content": "=========\nxlOil SQL\n=========\n\nThe SQL plugin uses sqlite3 to provide functions which query Excel arrays (or\nranges) as if they were tables in a database. Multiple tables can be queried \nand joined.\n\n.. contents::\n :local:\n\n.. _sql-getting-started:\n\nSQL Getting Started\n-------------------\n\nxlOil_SQL does not require any settings and is automatically loaded in a default \nxlOil installation. It should appear in the plugin list in\n`%APPDATA%/xlOil/xlOil.ini`:\n\n::\n\n Plugins=[\"xlOil_SQL.dll\"]\n\nYou can open the example spreadsheet at :ref:`core-example-sheets` to see it in action.\n\nFor a quick demo, create a 3 column table of data in an new Excel workbook. \nMake the headings 'Foo', 'Bar' and 'Baz'. The contents of the data can be \nanything you like.\n\nSuppose the table is in cells A1:C5, then in another cell type \n\n::\n\n =xloSql(\"SELECT Bar, Baz FROM Table1\", A1:C5)\n\nMake the output an array formula with Ctrl-Shift-Enter and size it \nappropriately.\n\n.. _xloSql:\n\nxloSql\n------\n\nExecutes a query on multiples data arrays\n\n.. function:: xloSql(Query, [Meta], [Table1], [Table2], [Table3], ...)\n\n Excecutes the SQL query on the provided tables, returning the \n result in an array. The tables will be named Table1, Table2, etc in the \n query but this can overrided by the `meta` parameter\n\n Query:\n a string or array of string (which will be concatenated) \n describing a query in SQL (sqlite3). \n\n Meta: \n optional array of string. The first column contains the \n names of the tables. Subsequent columns are interpreted\n as column headings for the table. Providing a blank table\n name or few names than tables results in the un-named\n tables retaining their default name of tableN\n \n TableN:\n each table argument should point to an array of data with\n columns as fields and records as rows. Unless column\n names are specified in the meta, the first row is interpreted as column names\n\n\n **Examples**\n \n (Arguments pointing to array data are surrouned by `{}`)\n\n ::\n\n =xloSql(\"SELECT table1.A, B, C FROM table1 \", { A B } , { A C } )\n \"INNER JOIN table2 \" { Foo 1 } { Bar 2 } )\n \"ON table1.A == table2.A \" { Baz 7 } { Foo 3 } )\n\n --> Foo 1 3\n\nStateful Database Functions\n---------------------------\n\nThis family of functions can be used to build up and repeatedly query an \nin-memory database for cases where building the database on the fly using \n:ref:`xlOil_SQL/index:xloSql` is not performant.\n\nxloSqlDB\n~~~~~~~~\n\n.. function:: xloSqlDB()\n\n Returns a reference to a new database object. The functions :ref:`xlOil_SQL/index:xloSqlDB`, :ref:`xlOil_SQL/index:xloSqlTable`\n and :ref:`xlOil_SQL/index:xloSqlQuery` can be used to build up an in-memory database for the cases where\n building these objects on the fly using :ref:`xlOil_SQL/index:xloSql` is not performant.\n\nxloSqlTable\n~~~~~~~~~~~\n\n.. function:: xloSqlTable(Database, Data, Name, [Headings], [Query])\n\n Creates a table in a database created with :ref:`xlOil_SQL/index:xloSqlDB`. The function returns a reference \n to the database: it is recommended to chain xloSqlTable calls to force execution order\n in Excel. This ensures tables are added to the database before any queries are run\n\n Database:\n a reference to a database created with `xloSqlDB`. \n\n Data: \n an array of data with columns as fields and records as rows. Unless column\n headings are specified, the first row is interpreted as column names\n\n Name:\n The name of the table in the database. This must be unique.\n \n Headings:\n optional column headings for the data. If these are specified, data is read\n from the first input row\n \n Query:\n An optional query to process the data as it is copied into the database.\n If ommitted, \"SELECT * FROM name\" is used.\n\nxloSqlQuery\n~~~~~~~~~~~\n.. function:: xloSqlQuery(Database, Query)\n\n Database:\n A reference to a database originally created with :ref:`xlOil_SQL/index:xloSqlDB` but which has\n passed through calls to :ref:`xlOil_SQL/index:xloSqlTable`.\n\n Query:\n A SQL query to execute. Tables referenced in the query must have been added \n to the database by :ref:`xlOil_SQL/index:xloSqlTable` before this function is called.\n\n\n **Examples**\n\n ::\n\n . A B C D \n 1 =xloSqlDB() MyTab Foo Bar\n 2 7 2\n 3 =xloSqlTable(A1, C1:D4, B1) 4 1\n 4 8 4\n 5\n 6 =xloSqlQuery(A3, \"SELECT Bar FROM MyTab\")\n\n Cell A6 will contain the array [2, 1, 4]\n\nxloSqlTables\n~~~~~~~~~~~~\n\n.. function:: xloSqlTables(Database)\n\n Returns an array of all table names in the database\n"
},
{
"path": "docs/source/xlOil_Utils.rst",
"content": "===========\nxlOil Utils\n===========\n\nThe Utils plugin contains general purpose tools to manipulate data,\nparticularly arrays.\n\n.. contents:: Contents\n\t:local:\n \nxloBlock: creates an array from blocks\n----------------------------------------\n\n.. function:: xloBlock(layout, arg1, arg2, arg3,...)\n\n Creates a block matrix given a layout specification.\n\n Layout has the form `1, 2, 3; 4, 5, 6` where numbers refer to\n argument numbers provided (note indexing is 1-based). Commas\n divide argument numbers, semi-colons indicate a new row. xlOil \n expands the blocks row by row.\n\n Omiting the argument number, i.e. two consecutive commas gives an\n auto-sized padded space. You can only have one per row.\n\n Whitespace is ignored in the layout specification.\n\n Arguments may be an array or a single value, which is interpreted as\n a 1x1 array.\n\n Any holes in the result are filled with #N/A - this is preferrable \n over Excel's 'empty' value which is transformed to a zero when \n written to the sheet.\n\n **Examples**\n\n ::\n\n =xloBlock(\"1, 2; 3, 4\", A A, B B, C C, D D)\n A A B B\n\n --> A A B B\n A A B B\n C C D D\n\n\n =xloBlock(\"1, 2; 3,, 4\", A A, B B, C, D)\n A A B B\n\n --> A A B B\n A A B B\n C - - D\n\nxloFill: gives an array filled with a single value\n--------------------------------------------------\n\n.. function:: xloFill(value, numRows, numColumns)\n\n Creates an array of size numRows by numColumns filled with value.\n\n Throws if value is not a single value.\n\nxloFillNA: replaces Empy or #N/A with a specified value\n----------------------------------------------------------\n\n.. function:: xloFillNA(value, array, [trim])\n\n Replaces any #N/A or Empty with a specified value. #N/As in Excel \n result from holes, e.g. from xloBlock or array which does not fill\n the space allocated in an array formula. Empty values are particularly\n problematic: they correpond to Excel reading an empty cell in an array\n but are transformed to a zero when written to the sheet.\n\n Throws if value is not a single value.\n\n The optional trim parameter can be used to disable xlOil's default\n array-trimming behaviour of resizing to the last non-empty, non-NA \n row and column.\n\n\nxloSort: sorts an array by multiple columns\n----------------------------------------------------------\n\n.. function:: xloSort(Array, Order, [colOrHeading1], [colOrHeading2], ...)\n\n Sorts data by one or more column keys. The function behaves similarly\n to Excel's sort command, but works as a sheet function.\n\n The `Order` parameter should be a string with a descriptor character\n for each column to used as a sort key. The character described how \n the column data will be compared. Allowed characters and their meaning \n are:\n\n *a*: ascending\n\n *A*: ascending case-sensitive,\n\n *d*: descending\n\n *D*: descending case-sensitive\n\n *whitespace*: ignored\n\n Each subsequent argument should be the (1-based) number of a column\n or string. If any strings are specified, the first row of `Array`\n is interpreted as column headers and the strings are matched against\n these headers.\n\n The order of the column specifiers indicates the prescendence in the\n sort order.\n\n xloSort works in-place for speed but uses Excel's variant types. This \n means it will not be \n\n **Examples**\n\n ::\n\n =xloSort( { Baz 4 } , \"a d\", 2, 1)\n { Bar 4 } \n { Boz 2 } \n\n -> 2 Boz\n 4 Baz\n 4 Bar \n\n\n\nxloPad: pads an array to have at least two rols and columns\n-----------------------------------------------------------\n\n.. function:: xloPad(array)\n\n xloPad works around the Excel 'feature' that duplicates arrays\n with only one row or column when they are used in an array formula with \n a larger target size. This can be frustrating for display of variable \n sized array results. xloPad simply ensures the array has at least two\n rows and columsn, adding #N/A where required to fill the space.\n\n\nxloConcat: concatenates strings\n--------------------------------\n\n.. function:: xloConcat([separator], valOrArray1, valOrArray2, ...)\n\n Concatenates strings or other values with an optional separator.\n Concatenation is in argument order. The separator may be blank or any\n value which can be converted to a string. Non string arguments are \n converted to string before concatenation. Arrays are concatenated\n along rows using the sparator if specified.\n\n\nxloSplit: splits strings at a separator\n---------------------------------------\n\n.. function:: xloSplit(stringOrArray, separators, [consecutiveAsOne])\n\n Splits a string at one or more separator characters, returning an array.\n A separators can only be a single character, but multiple separators\n can be specified. If `consecutiveAsOne` is omitted or TRUE, consecutive\n separators are treated as one, otherwise they generate empty cells.\n\n If a array of strings is passed, splitting will occur on each array\n element and the array orientation wil be preserved. The array must be \n 1-dimensional\n\n Any non string values are ignored - no coercision is performed.\n\n The `separators` input can be a string containing any number of characters;\n each will be treated as a distinct separator - multi-character separators\n are not supported.\n\n **Examples**\n\n ::\n\n =xloSplit(\"Foo:Bar,,Baz\", \":,\")\n\n -> Foo Bar Baz\n\n\nxloIndex: gets values or sub-arrays for arrays and ranges\n---------------------------------------------------------\n\n.. function:: xloIndex(ArrayOrRef, [FromRow], [FromCol], [ToRow], [ToCol])\n\n Extends the Excel INDEX function to support xloRefs and sub-arrays. With\n the first three arguments, `xloIndex` behaves like INDEX but can be passed\n an xloRef. This is an efficient way to fetch data from xloRef objects as it \n avoids copying the entire object to Excel.\n\n If *ToRow* and *ToCol* are provided they specify the right-hand end (not \n inclusive) of a sub-array from (*FromRow*, *FromCol*) to (*ToRow*, *ToCol*).\n\n **The row and column indices are 1-based**. If any of the indices is zero or \n negative it is interpreted as an offset from the number of rows or columns \n in the parent array.\n\n **Examples**\n\n ::\n\n =xloIndex(A1:D5,1,3) -> returns C1\n =xloIndex(A1:D5,-1,-1) -> returns D5\n =xloIndex(A1:D5,1,3,3,4) -> returns C1:D3\n =xloIndex(A1:D5,-2,-2,0,0) -> returns C4:D5\n"
},
{
"path": "docs/source/xloil.doxyfile",
"content": "# Doxyfile 1.8.18\n\n# This file describes the settings to be used by the documentation system\n# doxygen (www.doxygen.org) for a project.\n#\n# All text after a double hash (##) is considered a comment and is placed in\n# front of the TAG it is preceding.\n#\n# All text after a single hash (#) is considered a comment and will be ignored.\n# The format is:\n# TAG = value [value, ...]\n# For lists, items can also be appended using:\n# TAG += value [value, ...]\n# Values that contain spaces should be placed between quotes (\\\" \\\").\n\n#---------------------------------------------------------------------------\n# Project related configuration options\n#---------------------------------------------------------------------------\n\n# This tag specifies the encoding used for all characters in the configuration\n# file that follow. The default is UTF-8 which is also the encoding used for all\n# text before the first occurrence of this tag. Doxygen uses libiconv (or the\n# iconv built into libc) for the transcoding. See\n# https://www.gnu.org/software/libiconv/ for the list of possible encodings.\n# The default value is: UTF-8.\n\nDOXYFILE_ENCODING = UTF-8\n\n# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by\n# double-quotes, unless you are using Doxywizard) that should identify the\n# project for which the documentation is generated. This name is used in the\n# title of most generated pages and in a few other places.\n# The default value is: My Project.\n\nPROJECT_NAME = xlOil\n\n# The PROJECT_NUMBER tag can be used to enter a project or revision number. This\n# could be handy for archiving the generated documentation or if some version\n# control system is used.\n\nPROJECT_NUMBER = 1\n\n# Using the PROJECT_BRIEF tag one can provide an optional one line description\n# for a project that appears at the top of each page and should give viewer a\n# quick idea about the purpose of the project. Keep the description short.\n\nPROJECT_BRIEF =\n\n# With the PROJECT_LOGO tag one can specify a logo or an icon that is included\n# in the documentation. The maximum height of the logo should not exceed 55\n# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy\n# the logo to the output directory.\n\nPROJECT_LOGO =\n\n# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path\n# into which the generated documentation will be written. If a relative path is\n# entered, it will be relative to the location where doxygen was started. If\n# left blank the current directory will be used.\n\nOUTPUT_DIRECTORY = $(XLO_SOLN_DIR)/build/docs/doxygen\n\n# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-\n# directories (in 2 levels) under the output directory of each output format and\n# will distribute the generated files over these directories. Enabling this\n# option can be useful when feeding doxygen a huge amount of source files, where\n# putting all generated files in the same directory would otherwise causes\n# performance problems for the file system.\n# The default value is: NO.\n\nCREATE_SUBDIRS = NO\n\n# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII\n# characters to appear in the names of generated files. If set to NO, non-ASCII\n# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode\n# U+3044.\n# The default value is: NO.\n\nALLOW_UNICODE_NAMES = NO\n\n# The OUTPUT_LANGUAGE tag is used to specify the language in which all\n# documentation generated by doxygen is written. Doxygen will use this\n# information to generate all constant output in the proper language.\n# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese,\n# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States),\n# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian,\n# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages),\n# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian,\n# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian,\n# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish,\n# Ukrainian and Vietnamese.\n# The default value is: English.\n\nOUTPUT_LANGUAGE = English\n\n# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all\n# documentation generated by doxygen is written. Doxygen will use this\n# information to generate all generated output in the proper direction.\n# Possible values are: None, LTR, RTL and Context.\n# The default value is: None.\n\nOUTPUT_TEXT_DIRECTION = None\n\n# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member\n# descriptions after the members that are listed in the file and class\n# documentation (similar to Javadoc). Set to NO to disable this.\n# The default value is: YES.\n\nBRIEF_MEMBER_DESC = YES\n\n# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief\n# description of a member or function before the detailed description\n#\n# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the\n# brief descriptions will be completely suppressed.\n# The default value is: YES.\n\nREPEAT_BRIEF = YES\n\n# This tag implements a quasi-intelligent brief description abbreviator that is\n# used to form the text in various listings. Each string in this list, if found\n# as the leading text of the brief description, will be stripped from the text\n# and the result, after processing the whole list, is used as the annotated\n# text. Otherwise, the brief description is used as-is. If left blank, the\n# following values are used ($name is automatically replaced with the name of\n# the entity):The $name class, The $name widget, The $name file, is, provides,\n# specifies, contains, represents, a, an and the.\n\nABBREVIATE_BRIEF = \"The $name class\" \\\n \"The $name widget\" \\\n \"The $name file\" \\\n is \\\n provides \\\n specifies \\\n contains \\\n represents \\\n a \\\n an \\\n the\n\n# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then\n# doxygen will generate a detailed section even if there is only a brief\n# description.\n# The default value is: NO.\n\nALWAYS_DETAILED_SEC = NO\n\n# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all\n# inherited members of a class in the documentation of that class as if those\n# members were ordinary class members. Constructors, destructors and assignment\n# operators of the base classes will not be shown.\n# The default value is: NO.\n\nINLINE_INHERITED_MEMB = NO\n\n# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path\n# before files name in the file list and in the header files. If set to NO the\n# shortest path that makes the file name unique will be used\n# The default value is: YES.\n\nFULL_PATH_NAMES = YES\n\n# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.\n# Stripping is only done if one of the specified strings matches the left-hand\n# part of the path. The tag can be used to show relative paths in the file list.\n# If left blank the directory from which doxygen is run is used as the path to\n# strip.\n#\n# Note that you can specify absolute paths here, but also relative paths, which\n# will be relative from the directory where doxygen is started.\n# This tag requires that the tag FULL_PATH_NAMES is set to YES.\n\nSTRIP_FROM_PATH =\n\n# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the\n# path mentioned in the documentation of a class, which tells the reader which\n# header file to include in order to use a class. If left blank only the name of\n# the header file containing the class definition is used. Otherwise one should\n# specify the list of include paths that are normally passed to the compiler\n# using the -I flag.\n\nSTRIP_FROM_INC_PATH =\n\n# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but\n# less readable) file names. This can be useful is your file systems doesn't\n# support long names like on DOS, Mac, or CD-ROM.\n# The default value is: NO.\n\nSHORT_NAMES = NO\n\n# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the\n# first line (until the first dot) of a Javadoc-style comment as the brief\n# description. If set to NO, the Javadoc-style will behave just like regular Qt-\n# style comments (thus requiring an explicit @brief command for a brief\n# description.)\n# The default value is: NO.\n\nJAVADOC_AUTOBRIEF = NO\n\n# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line\n# such as\n# /***************\n# as being the beginning of a Javadoc-style comment \"banner\". If set to NO, the\n# Javadoc-style will behave just like regular comments and it will not be\n# interpreted by doxygen.\n# The default value is: NO.\n\nJAVADOC_BANNER = NO\n\n# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first\n# line (until the first dot) of a Qt-style comment as the brief description. If\n# set to NO, the Qt-style will behave just like regular Qt-style comments (thus\n# requiring an explicit \\brief command for a brief description.)\n# The default value is: NO.\n\nQT_AUTOBRIEF = NO\n\n# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a\n# multi-line C++ special comment block (i.e. a block of //! or /// comments) as\n# a brief description. This used to be the default behavior. The new default is\n# to treat a multi-line C++ comment block as a detailed description. Set this\n# tag to YES if you prefer the old behavior instead.\n#\n# Note that setting this tag to YES also means that rational rose comments are\n# not recognized any more.\n# The default value is: NO.\n\nMULTILINE_CPP_IS_BRIEF = NO\n\n# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the\n# documentation from any documented member that it re-implements.\n# The default value is: YES.\n\nINHERIT_DOCS = YES\n\n# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new\n# page for each member. If set to NO, the documentation of a member will be part\n# of the file/class/namespace that contains it.\n# The default value is: NO.\n\nSEPARATE_MEMBER_PAGES = NO\n\n# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen\n# uses this value to replace tabs by spaces in code fragments.\n# Minimum value: 1, maximum value: 16, default value: 4.\n\nTAB_SIZE = 4\n\n# This tag can be used to specify a number of aliases that act as commands in\n# the documentation. An alias has the form:\n# name=value\n# For example adding\n# \"sideeffect=@par Side Effects:\\n\"\n# will allow you to put the command \\sideeffect (or @sideeffect) in the\n# documentation, which will result in a user-defined paragraph with heading\n# \"Side Effects:\". You can put \\n's in the value part of an alias to insert\n# newlines (in the resulting output). You can put ^^ in the value part of an\n# alias to insert a newline as if a physical newline was in the original file.\n# When you need a literal { or } or , in the value part of an alias you have to\n# escape them by means of a backslash (\\), this can lead to conflicts with the\n# commands \\{ and \\} for these it is advised to use the version @{ and @} or use\n# a double escape (\\\\{ and \\\\})\n\nALIASES =\n\n# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources\n# only. Doxygen will then generate output that is more tailored for C. For\n# instance, some of the names that are used will be different. The list of all\n# members will be omitted, etc.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_FOR_C = NO\n\n# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or\n# Python sources only. Doxygen will then generate output that is more tailored\n# for that language. For instance, namespaces will be presented as packages,\n# qualified scopes will look different, etc.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_JAVA = NO\n\n# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran\n# sources. Doxygen will then generate output that is tailored for Fortran.\n# The default value is: NO.\n\nOPTIMIZE_FOR_FORTRAN = NO\n\n# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL\n# sources. Doxygen will then generate output that is tailored for VHDL.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_VHDL = NO\n\n# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice\n# sources only. Doxygen will then generate output that is more tailored for that\n# language. For instance, namespaces will be presented as modules, types will be\n# separated into more groups, etc.\n# The default value is: NO.\n\nOPTIMIZE_OUTPUT_SLICE = NO\n\n# Doxygen selects the parser to use depending on the extension of the files it\n# parses. With this tag you can assign which parser to use for a given\n# extension. Doxygen has a built-in mapping, but you can override or extend it\n# using this tag. The format is ext=language, where ext is a file extension, and\n# language is one of the parsers supported by doxygen: IDL, Java, JavaScript,\n# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL,\n# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran:\n# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser\n# tries to guess whether the code is fixed or free formatted code, this is the\n# default for Fortran type files). For instance to make doxygen treat .inc files\n# as Fortran files (default is PHP), and .f files as C (default is Fortran),\n# use: inc=Fortran f=C.\n#\n# Note: For files without extension you can use no_extension as a placeholder.\n#\n# Note that for custom extensions you also need to set FILE_PATTERNS otherwise\n# the files are not read by doxygen.\n\nEXTENSION_MAPPING =\n\n# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments\n# according to the Markdown format, which allows for more readable\n# documentation. See https://daringfireball.net/projects/markdown/ for details.\n# The output of markdown processing is further processed by doxygen, so you can\n# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in\n# case of backward compatibilities issues.\n# The default value is: YES.\n\nMARKDOWN_SUPPORT = YES\n\n# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up\n# to that level are automatically included in the table of contents, even if\n# they do not have an id attribute.\n# Note: This feature currently applies only to Markdown headings.\n# Minimum value: 0, maximum value: 99, default value: 5.\n# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.\n\nTOC_INCLUDE_HEADINGS = 5\n\n# When enabled doxygen tries to link words that correspond to documented\n# classes, or namespaces to their corresponding documentation. Such a link can\n# be prevented in individual cases by putting a % sign in front of the word or\n# globally by setting AUTOLINK_SUPPORT to NO.\n# The default value is: YES.\n\nAUTOLINK_SUPPORT = YES\n\n# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want\n# to include (a tag file for) the STL sources as input, then you should set this\n# tag to YES in order to let doxygen match functions declarations and\n# definitions whose arguments contain STL classes (e.g. func(std::string);\n# versus func(std::string) {}). This also make the inheritance and collaboration\n# diagrams that involve STL classes more complete and accurate.\n# The default value is: NO.\n\nBUILTIN_STL_SUPPORT = NO\n\n# If you use Microsoft's C++/CLI language, you should set this option to YES to\n# enable parsing support.\n# The default value is: NO.\n\nCPP_CLI_SUPPORT = NO\n\n# Set the SIP_SUPPORT tag to YES if your project consists of sip (see:\n# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen\n# will parse them like normal C++ but will assume all classes use public instead\n# of private inheritance when no explicit protection keyword is present.\n# The default value is: NO.\n\nSIP_SUPPORT = NO\n\n# For Microsoft's IDL there are propget and propput attributes to indicate\n# getter and setter methods for a property. Setting this option to YES will make\n# doxygen to replace the get and set methods by a property in the documentation.\n# This will only work if the methods are indeed getting or setting a simple\n# type. If this is not the case, or you want to show the methods anyway, you\n# should set this option to NO.\n# The default value is: YES.\n\nIDL_PROPERTY_SUPPORT = YES\n\n# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC\n# tag is set to YES then doxygen will reuse the documentation of the first\n# member in the group (if any) for the other members of the group. By default\n# all members of a group must be documented explicitly.\n# The default value is: NO.\n\nDISTRIBUTE_GROUP_DOC = NO\n\n# If one adds a struct or class to a group and this option is enabled, then also\n# any nested class or struct is added to the same group. By default this option\n# is disabled and one has to add nested compounds explicitly via \\ingroup.\n# The default value is: NO.\n\nGROUP_NESTED_COMPOUNDS = NO\n\n# Set the SUBGROUPING tag to YES to allow class member groups of the same type\n# (for instance a group of public functions) to be put as a subgroup of that\n# type (e.g. under the Public Functions section). Set it to NO to prevent\n# subgrouping. Alternatively, this can be done per class using the\n# \\nosubgrouping command.\n# The default value is: YES.\n\nSUBGROUPING = YES\n\n# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions\n# are shown inside the group in which they are included (e.g. using \\ingroup)\n# instead of on a separate page (for HTML and Man pages) or section (for LaTeX\n# and RTF).\n#\n# Note that this feature does not work in combination with\n# SEPARATE_MEMBER_PAGES.\n# The default value is: NO.\n\nINLINE_GROUPED_CLASSES = NO\n\n# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions\n# with only public data fields or simple typedef fields will be shown inline in\n# the documentation of the scope in which they are defined (i.e. file,\n# namespace, or group documentation), provided this scope is documented. If set\n# to NO, structs, classes, and unions are shown on a separate page (for HTML and\n# Man pages) or section (for LaTeX and RTF).\n# The default value is: NO.\n\nINLINE_SIMPLE_STRUCTS = NO\n\n# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or\n# enum is documented as struct, union, or enum with the name of the typedef. So\n# typedef struct TypeS {} TypeT, will appear in the documentation as a struct\n# with name TypeT. When disabled the typedef will appear as a member of a file,\n# namespace, or class. And the struct will be named TypeS. This can typically be\n# useful for C code in case the coding convention dictates that all compound\n# types are typedef'ed and only the typedef is referenced, never the tag name.\n# The default value is: NO.\n\nTYPEDEF_HIDES_STRUCT = NO\n\n# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This\n# cache is used to resolve symbols given their name and scope. Since this can be\n# an expensive process and often the same symbol appears multiple times in the\n# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small\n# doxygen will become slower. If the cache is too large, memory is wasted. The\n# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range\n# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536\n# symbols. At the end of a run doxygen will report the cache usage and suggest\n# the optimal cache size from a speed point of view.\n# Minimum value: 0, maximum value: 9, default value: 0.\n\nLOOKUP_CACHE_SIZE = 0\n\n#---------------------------------------------------------------------------\n# Build related configuration options\n#---------------------------------------------------------------------------\n\n# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in\n# documentation are documented, even if no documentation was available. Private\n# class members and static file members will be hidden unless the\n# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.\n# Note: This will also disable the warnings about undocumented members that are\n# normally produced when WARNINGS is set to YES.\n# The default value is: NO.\n\nEXTRACT_ALL = YES\n\n# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will\n# be included in the documentation.\n# The default value is: NO.\n\nEXTRACT_PRIVATE = NO\n\n# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual\n# methods of a class will be included in the documentation.\n# The default value is: NO.\n\nEXTRACT_PRIV_VIRTUAL = NO\n\n# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal\n# scope will be included in the documentation.\n# The default value is: NO.\n\nEXTRACT_PACKAGE = NO\n\n# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be\n# included in the documentation.\n# The default value is: NO.\n\nEXTRACT_STATIC = NO\n\n# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined\n# locally in source files will be included in the documentation. If set to NO,\n# only classes defined in header files are included. Does not have any effect\n# for Java sources.\n# The default value is: YES.\n\nEXTRACT_LOCAL_CLASSES = NO\n\n# This flag is only useful for Objective-C code. If set to YES, local methods,\n# which are defined in the implementation section but not in the interface are\n# included in the documentation. If set to NO, only methods in the interface are\n# included.\n# The default value is: NO.\n\nEXTRACT_LOCAL_METHODS = NO\n\n# If this flag is set to YES, the members of anonymous namespaces will be\n# extracted and appear in the documentation as a namespace called\n# 'anonymous_namespace{file}', where file will be replaced with the base name of\n# the file that contains the anonymous namespace. By default anonymous namespace\n# are hidden.\n# The default value is: NO.\n\nEXTRACT_ANON_NSPACES = NO\n\n# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all\n# undocumented members inside documented classes or files. If set to NO these\n# members will be included in the various overviews, but no documentation\n# section is generated. This option has no effect if EXTRACT_ALL is enabled.\n# The default value is: NO.\n\nHIDE_UNDOC_MEMBERS = NO\n\n# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all\n# undocumented classes that are normally visible in the class hierarchy. If set\n# to NO, these classes will be included in the various overviews. This option\n# has no effect if EXTRACT_ALL is enabled.\n# The default value is: NO.\n\nHIDE_UNDOC_CLASSES = YES\n\n# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend\n# declarations. If set to NO, these declarations will be included in the\n# documentation.\n# The default value is: NO.\n\nHIDE_FRIEND_COMPOUNDS = NO\n\n# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any\n# documentation blocks found inside the body of a function. If set to NO, these\n# blocks will be appended to the function's detailed documentation block.\n# The default value is: NO.\n\nHIDE_IN_BODY_DOCS = NO\n\n# The INTERNAL_DOCS tag determines if documentation that is typed after a\n# \\internal command is included. If the tag is set to NO then the documentation\n# will be excluded. Set it to YES to include the internal documentation.\n# The default value is: NO.\n\nINTERNAL_DOCS = NO\n\n# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file\n# names in lower-case letters. If set to YES, upper-case letters are also\n# allowed. This is useful if you have classes or files whose names only differ\n# in case and if your file system supports case sensitive file names. Windows\n# (including Cygwin) ands Mac users are advised to set this option to NO.\n# The default value is: system dependent.\n\nCASE_SENSE_NAMES = NO\n\n# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with\n# their full class and namespace scopes in the documentation. If set to YES, the\n# scope will be hidden.\n# The default value is: NO.\n\nHIDE_SCOPE_NAMES = NO\n\n# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will\n# append additional text to a page's title, such as Class Reference. If set to\n# YES the compound reference will be hidden.\n# The default value is: NO.\n\nHIDE_COMPOUND_REFERENCE= NO\n\n# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of\n# the files that are included by a file in the documentation of that file.\n# The default value is: YES.\n\nSHOW_INCLUDE_FILES = YES\n\n# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each\n# grouped member an include statement to the documentation, telling the reader\n# which file to include in order to use the member.\n# The default value is: NO.\n\nSHOW_GROUPED_MEMB_INC = NO\n\n# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include\n# files with double quotes in the documentation rather than with sharp brackets.\n# The default value is: NO.\n\nFORCE_LOCAL_INCLUDES = NO\n\n# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the\n# documentation for inline members.\n# The default value is: YES.\n\nINLINE_INFO = YES\n\n# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the\n# (detailed) documentation of file and class members alphabetically by member\n# name. If set to NO, the members will appear in declaration order.\n# The default value is: YES.\n\nSORT_MEMBER_DOCS = YES\n\n# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief\n# descriptions of file, namespace and class members alphabetically by member\n# name. If set to NO, the members will appear in declaration order. Note that\n# this will also influence the order of the classes in the class list.\n# The default value is: NO.\n\nSORT_BRIEF_DOCS = NO\n\n# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the\n# (brief and detailed) documentation of class members so that constructors and\n# destructors are listed first. If set to NO the constructors will appear in the\n# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.\n# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief\n# member documentation.\n# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting\n# detailed member documentation.\n# The default value is: NO.\n\nSORT_MEMBERS_CTORS_1ST = NO\n\n# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy\n# of group names into alphabetical order. If set to NO the group names will\n# appear in their defined order.\n# The default value is: NO.\n\nSORT_GROUP_NAMES = NO\n\n# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by\n# fully-qualified names, including namespaces. If set to NO, the class list will\n# be sorted only by class name, not including the namespace part.\n# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.\n# Note: This option applies only to the class list, not to the alphabetical\n# list.\n# The default value is: NO.\n\nSORT_BY_SCOPE_NAME = NO\n\n# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper\n# type resolution of all parameters of a function it will reject a match between\n# the prototype and the implementation of a member function even if there is\n# only one candidate or it is obvious which candidate to choose by doing a\n# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still\n# accept a match between prototype and implementation in such cases.\n# The default value is: NO.\n\nSTRICT_PROTO_MATCHING = NO\n\n# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo\n# list. This list is created by putting \\todo commands in the documentation.\n# The default value is: YES.\n\nGENERATE_TODOLIST = YES\n\n# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test\n# list. This list is created by putting \\test commands in the documentation.\n# The default value is: YES.\n\nGENERATE_TESTLIST = YES\n\n# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug\n# list. This list is created by putting \\bug commands in the documentation.\n# The default value is: YES.\n\nGENERATE_BUGLIST = YES\n\n# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)\n# the deprecated list. This list is created by putting \\deprecated commands in\n# the documentation.\n# The default value is: YES.\n\nGENERATE_DEPRECATEDLIST= YES\n\n# The ENABLED_SECTIONS tag can be used to enable conditional documentation\n# sections, marked by \\if ... \\endif and \\cond \n# ... \\endcond blocks.\n\nENABLED_SECTIONS =\n\n# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the\n# initial value of a variable or macro / define can have for it to appear in the\n# documentation. If the initializer consists of more lines than specified here\n# it will be hidden. Use a value of 0 to hide initializers completely. The\n# appearance of the value of individual variables and macros / defines can be\n# controlled using \\showinitializer or \\hideinitializer command in the\n# documentation regardless of this setting.\n# Minimum value: 0, maximum value: 10000, default value: 30.\n\nMAX_INITIALIZER_LINES = 30\n\n# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at\n# the bottom of the documentation of classes and structs. If set to YES, the\n# list will mention the files that were used to generate the documentation.\n# The default value is: YES.\n\nSHOW_USED_FILES = YES\n\n# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This\n# will remove the Files entry from the Quick Index and from the Folder Tree View\n# (if specified).\n# The default value is: YES.\n\nSHOW_FILES = YES\n\n# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces\n# page. This will remove the Namespaces entry from the Quick Index and from the\n# Folder Tree View (if specified).\n# The default value is: YES.\n\nSHOW_NAMESPACES = YES\n\n# The FILE_VERSION_FILTER tag can be used to specify a program or script that\n# doxygen should invoke to get the current version for each file (typically from\n# the version control system). Doxygen will invoke the program by executing (via\n# popen()) the command command input-file, where command is the value of the\n# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided\n# by doxygen. Whatever the program writes to standard output is used as the file\n# version. For an example see the documentation.\n\nFILE_VERSION_FILTER =\n\n# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed\n# by doxygen. The layout file controls the global structure of the generated\n# output files in an output format independent way. To create the layout file\n# that represents doxygen's defaults, run doxygen with the -l option. You can\n# optionally specify a file name after the option, if omitted DoxygenLayout.xml\n# will be used as the name of the layout file.\n#\n# Note that if you run doxygen from a directory containing a file called\n# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE\n# tag is left empty.\n\nLAYOUT_FILE =\n\n# The CITE_BIB_FILES tag can be used to specify one or more bib files containing\n# the reference definitions. This must be a list of .bib files. The .bib\n# extension is automatically appended if omitted. This requires the bibtex tool\n# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info.\n# For LaTeX the style of the bibliography can be controlled using\n# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the\n# search path. See also \\cite for info how to create references.\n\nCITE_BIB_FILES =\n\n#---------------------------------------------------------------------------\n# Configuration options related to warning and progress messages\n#---------------------------------------------------------------------------\n\n# The QUIET tag can be used to turn on/off the messages that are generated to\n# standard output by doxygen. If QUIET is set to YES this implies that the\n# messages are off.\n# The default value is: NO.\n\nQUIET = NO\n\n# The WARNINGS tag can be used to turn on/off the warning messages that are\n# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES\n# this implies that the warnings are on.\n#\n# Tip: Turn warnings on while writing the documentation.\n# The default value is: YES.\n\nWARNINGS = YES\n\n# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate\n# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag\n# will automatically be disabled.\n# The default value is: YES.\n\nWARN_IF_UNDOCUMENTED = YES\n\n# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for\n# potential errors in the documentation, such as not documenting some parameters\n# in a documented function, or documenting parameters that don't exist or using\n# markup commands wrongly.\n# The default value is: YES.\n\nWARN_IF_DOC_ERROR = YES\n\n# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that\n# are documented, but have no documentation for their parameters or return\n# value. If set to NO, doxygen will only warn about wrong or incomplete\n# parameter documentation, but not about the absence of documentation. If\n# EXTRACT_ALL is set to YES then this flag will automatically be disabled.\n# The default value is: NO.\n\nWARN_NO_PARAMDOC = NO\n\n# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when\n# a warning is encountered.\n# The default value is: NO.\n\nWARN_AS_ERROR = NO\n\n# The WARN_FORMAT tag determines the format of the warning messages that doxygen\n# can produce. The string should contain the $file, $line, and $text tags, which\n# will be replaced by the file and line number from which the warning originated\n# and the warning text. Optionally the format may contain $version, which will\n# be replaced by the version of the file (if it could be obtained via\n# FILE_VERSION_FILTER)\n# The default value is: $file:$line: $text.\n\nWARN_FORMAT = \"$file:$line: $text\"\n\n# The WARN_LOGFILE tag can be used to specify a file to which warning and error\n# messages should be written. If left blank the output is written to standard\n# error (stderr).\n\nWARN_LOGFILE =\n\n#---------------------------------------------------------------------------\n# Configuration options related to the input files\n#---------------------------------------------------------------------------\n\n# The INPUT tag is used to specify the files and/or directories that contain\n# documented source files. You may enter file names like myfile.cpp or\n# directories like /usr/src/myproject. Separate the files or directories with\n# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING\n# Note: If this tag is empty the current directory is searched.\n\nINPUT = $(XLO_SOLN_DIR)/include/xloil\n\n# This tag can be used to specify the character encoding of the source files\n# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses\n# libiconv (or the iconv built into libc) for the transcoding. See the libiconv\n# documentation (see: https://www.gnu.org/software/libiconv/) for the list of\n# possible encodings.\n# The default value is: UTF-8.\n\nINPUT_ENCODING = UTF-8\n\n# If the value of the INPUT tag contains directories, you can use the\n# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and\n# *.h) to filter out the source-files in the directories.\n#\n# Note that for custom extensions or not directly supported extensions you also\n# need to set EXTENSION_MAPPING for the extension otherwise the files are not\n# read by doxygen.\n#\n# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,\n# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,\n# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,\n# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment),\n# *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen\n# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd,\n# *.vhdl, *.ucf, *.qsf and *.ice.\n\nFILE_PATTERNS = *.c \\\n *.cc \\\n *.cxx \\\n *.cpp \\\n *.c++ \\\n *.java \\\n *.ii \\\n *.ixx \\\n *.ipp \\\n *.i++ \\\n *.inl \\\n *.idl \\\n *.ddl \\\n *.odl \\\n *.h \\\n *.hh \\\n *.hxx \\\n *.hpp \\\n *.h++ \\\n *.cs \\\n *.d \\\n *.php \\\n *.php4 \\\n *.php5 \\\n *.phtml \\\n *.inc \\\n *.m \\\n *.markdown \\\n *.md \\\n *.mm \\\n *.dox \\\n *.doc \\\n *.txt \\\n *.py \\\n *.pyw \\\n *.f90 \\\n *.f95 \\\n *.f03 \\\n *.f08 \\\n *.f18 \\\n *.f \\\n *.for \\\n *.vhd \\\n *.vhdl \\\n *.ucf \\\n *.qsf \\\n *.ice\n\n# The RECURSIVE tag can be used to specify whether or not subdirectories should\n# be searched for input files as well.\n# The default value is: NO.\n\nRECURSIVE = NO\n\n# The EXCLUDE tag can be used to specify files and/or directories that should be\n# excluded from the INPUT source files. This way you can easily exclude a\n# subdirectory from a directory tree whose root is specified with the INPUT tag.\n#\n# Note that relative paths are relative to the directory from which doxygen is\n# run.\n\nEXCLUDE =\n\n# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or\n# directories that are symbolic links (a Unix file system feature) are excluded\n# from the input.\n# The default value is: NO.\n\nEXCLUDE_SYMLINKS = NO\n\n# If the value of the INPUT tag contains directories, you can use the\n# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude\n# certain files from those directories.\n#\n# Note that the wildcards are matched against the file with absolute path, so to\n# exclude all test directories for example use the pattern */test/*\n\nEXCLUDE_PATTERNS =\n\n# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names\n# (namespaces, classes, functions, etc.) that should be excluded from the\n# output. The symbol name can be a fully qualified name, a word, or if the\n# wildcard * is used, a substring. Examples: ANamespace, AClass,\n# AClass::ANamespace, ANamespace::*Test\n#\n# Note that the wildcards are matched against the file with absolute path, so to\n# exclude all test directories use the pattern */test/*\n\nEXCLUDE_SYMBOLS = msxll \\\n toml \\\n std \\\n detail \\\n spdlog\n\n# The EXAMPLE_PATH tag can be used to specify one or more files or directories\n# that contain example code fragments that are included (see the \\include\n# command).\n\nEXAMPLE_PATH =\n\n# If the value of the EXAMPLE_PATH tag contains directories, you can use the\n# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and\n# *.h) to filter out the source-files in the directories. If left blank all\n# files are included.\n\nEXAMPLE_PATTERNS = *\n\n# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be\n# searched for input files to be used with the \\include or \\dontinclude commands\n# irrespective of the value of the RECURSIVE tag.\n# The default value is: NO.\n\nEXAMPLE_RECURSIVE = NO\n\n# The IMAGE_PATH tag can be used to specify one or more files or directories\n# that contain images that are to be included in the documentation (see the\n# \\image command).\n\nIMAGE_PATH =\n\n# The INPUT_FILTER tag can be used to specify a program that doxygen should\n# invoke to filter for each input file. Doxygen will invoke the filter program\n# by executing (via popen()) the command:\n#\n# \n#\n# where is the value of the INPUT_FILTER tag, and is the\n# name of an input file. Doxygen will then use the output that the filter\n# program writes to standard output. If FILTER_PATTERNS is specified, this tag\n# will be ignored.\n#\n# Note that the filter must not add or remove lines; it is applied before the\n# code is scanned, but not when the output code is generated. If lines are added\n# or removed, the anchors will not be placed correctly.\n#\n# Note that for custom extensions or not directly supported extensions you also\n# need to set EXTENSION_MAPPING for the extension otherwise the files are not\n# properly processed by doxygen.\n\nINPUT_FILTER =\n\n# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern\n# basis. Doxygen will compare the file name with each pattern and apply the\n# filter if there is a match. The filters are a list of the form: pattern=filter\n# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how\n# filters are used. If the FILTER_PATTERNS tag is empty or if none of the\n# patterns match the file name, INPUT_FILTER is applied.\n#\n# Note that for custom extensions or not directly supported extensions you also\n# need to set EXTENSION_MAPPING for the extension otherwise the files are not\n# properly processed by doxygen.\n\nFILTER_PATTERNS =\n\n# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using\n# INPUT_FILTER) will also be used to filter the input files that are used for\n# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES).\n# The default value is: NO.\n\nFILTER_SOURCE_FILES = NO\n\n# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file\n# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and\n# it is also possible to disable source filtering for a specific pattern using\n# *.ext= (so without naming a filter).\n# This tag requires that the tag FILTER_SOURCE_FILES is set to YES.\n\nFILTER_SOURCE_PATTERNS =\n\n# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that\n# is part of the input, its contents will be placed on the main page\n# (index.html). This can be useful if you have a project on for instance GitHub\n# and want to reuse the introduction page also for the doxygen output.\n\nUSE_MDFILE_AS_MAINPAGE =\n\n#---------------------------------------------------------------------------\n# Configuration options related to source browsing\n#---------------------------------------------------------------------------\n\n# If the SOURCE_BROWSER tag is set to YES then a list of source files will be\n# generated. Documented entities will be cross-referenced with these sources.\n#\n# Note: To get rid of all source code in the generated output, make sure that\n# also VERBATIM_HEADERS is set to NO.\n# The default value is: NO.\n\nSOURCE_BROWSER = NO\n\n# Setting the INLINE_SOURCES tag to YES will include the body of functions,\n# classes and enums directly into the documentation.\n# The default value is: NO.\n\nINLINE_SOURCES = NO\n\n# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any\n# special comment blocks from generated source code fragments. Normal C, C++ and\n# Fortran comments will always remain visible.\n# The default value is: YES.\n\nSTRIP_CODE_COMMENTS = YES\n\n# If the REFERENCED_BY_RELATION tag is set to YES then for each documented\n# entity all documented functions referencing it will be listed.\n# The default value is: NO.\n\nREFERENCED_BY_RELATION = NO\n\n# If the REFERENCES_RELATION tag is set to YES then for each documented function\n# all documented entities called/used by that function will be listed.\n# The default value is: NO.\n\nREFERENCES_RELATION = NO\n\n# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set\n# to YES then the hyperlinks from functions in REFERENCES_RELATION and\n# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will\n# link to the documentation.\n# The default value is: YES.\n\nREFERENCES_LINK_SOURCE = YES\n\n# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the\n# source code will show a tooltip with additional information such as prototype,\n# brief description and links to the definition and documentation. Since this\n# will make the HTML file larger and loading of large files a bit slower, you\n# can opt to disable this feature.\n# The default value is: YES.\n# This tag requires that the tag SOURCE_BROWSER is set to YES.\n\nSOURCE_TOOLTIPS = YES\n\n# If the USE_HTAGS tag is set to YES then the references to source code will\n# point to the HTML generated by the htags(1) tool instead of doxygen built-in\n# source browser. The htags tool is part of GNU's global source tagging system\n# (see https://www.gnu.org/software/global/global.html). You will need version\n# 4.8.6 or higher.\n#\n# To use it do the following:\n# - Install the latest version of global\n# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file\n# - Make sure the INPUT points to the root of the source tree\n# - Run doxygen as normal\n#\n# Doxygen will invoke htags (and that will in turn invoke gtags), so these\n# tools must be available from the command line (i.e. in the search path).\n#\n# The result: instead of the source browser generated by doxygen, the links to\n# source code will now point to the output of htags.\n# The default value is: NO.\n# This tag requires that the tag SOURCE_BROWSER is set to YES.\n\nUSE_HTAGS = NO\n\n# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a\n# verbatim copy of the header file for each class for which an include is\n# specified. Set to NO to disable this.\n# See also: Section \\class.\n# The default value is: YES.\n\nVERBATIM_HEADERS = YES\n\n# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the\n# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the\n# cost of reduced performance. This can be particularly helpful with template\n# rich C++ code for which doxygen's built-in parser lacks the necessary type\n# information.\n# Note: The availability of this option depends on whether or not doxygen was\n# generated with the -Duse_libclang=ON option for CMake.\n# The default value is: NO.\n\nCLANG_ASSISTED_PARSING = NO\n\n# If clang assisted parsing is enabled you can provide the compiler with command\n# line options that you would normally use when invoking the compiler. Note that\n# the include paths will already be set by doxygen for the files and directories\n# specified with INPUT and INCLUDE_PATH.\n# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.\n\nCLANG_OPTIONS =\n\n# If clang assisted parsing is enabled you can provide the clang parser with the\n# path to the compilation database (see:\n# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) used when the files\n# were built. This is equivalent to specifying the \"-p\" option to a clang tool,\n# such as clang-check. These options will then be passed to the parser.\n# Note: The availability of this option depends on whether or not doxygen was\n# generated with the -Duse_libclang=ON option for CMake.\n\nCLANG_DATABASE_PATH =\n\n#---------------------------------------------------------------------------\n# Configuration options related to the alphabetical class index\n#---------------------------------------------------------------------------\n\n# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all\n# compounds will be generated. Enable this if the project contains a lot of\n# classes, structs, unions or interfaces.\n# The default value is: YES.\n\nALPHABETICAL_INDEX = YES\n\n# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in\n# which the alphabetical index list will be split.\n# Minimum value: 1, maximum value: 20, default value: 5.\n# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.\n\nCOLS_IN_ALPHA_INDEX = 5\n\n# In case all classes in a project start with a common prefix, all classes will\n# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag\n# can be used to specify a prefix (or a list of prefixes) that should be ignored\n# while generating the index headers.\n# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.\n\nIGNORE_PREFIX =\n\n#---------------------------------------------------------------------------\n# Configuration options related to the HTML output\n#---------------------------------------------------------------------------\n\n# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output\n# The default value is: YES.\n\nGENERATE_HTML = YES\n\n# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a\n# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of\n# it.\n# The default directory is: html.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_OUTPUT = html/doxygen\n\n# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each\n# generated HTML page (for example: .htm, .php, .asp).\n# The default value is: .html.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_FILE_EXTENSION = .html\n\n# The HTML_HEADER tag can be used to specify a user-defined HTML header file for\n# each generated HTML page. If the tag is left blank doxygen will generate a\n# standard header.\n#\n# To get valid HTML the header file that includes any scripts and style sheets\n# that doxygen needs, which is dependent on the configuration options used (e.g.\n# the setting GENERATE_TREEVIEW). It is highly recommended to start with a\n# default header using\n# doxygen -w html new_header.html new_footer.html new_stylesheet.css\n# YourConfigFile\n# and then modify the file new_header.html. See also section \"Doxygen usage\"\n# for information on how to generate the default header that doxygen normally\n# uses.\n# Note: The header is subject to change so you typically have to regenerate the\n# default header when upgrading to a newer version of doxygen. For a description\n# of the possible markers and block names see the documentation.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_HEADER =\n\n# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each\n# generated HTML page. If the tag is left blank doxygen will generate a standard\n# footer. See HTML_HEADER for more information on how to generate a default\n# footer and what special commands can be used inside the footer. See also\n# section \"Doxygen usage\" for information on how to generate the default footer\n# that doxygen normally uses.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_FOOTER =\n\n# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style\n# sheet that is used by each HTML page. It can be used to fine-tune the look of\n# the HTML output. If left blank doxygen will generate a default style sheet.\n# See also section \"Doxygen usage\" for information on how to generate the style\n# sheet that doxygen normally uses.\n# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as\n# it is more robust and this tag (HTML_STYLESHEET) will in the future become\n# obsolete.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_STYLESHEET =\n\n# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined\n# cascading style sheets that are included after the standard style sheets\n# created by doxygen. Using this option one can overrule certain style aspects.\n# This is preferred over using HTML_STYLESHEET since it does not replace the\n# standard style sheet and is therefore more robust against future updates.\n# Doxygen will copy the style sheet files to the output directory.\n# Note: The order of the extra style sheet files is of importance (e.g. the last\n# style sheet in the list overrules the setting of the previous ones in the\n# list). For an example see the documentation.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_EXTRA_STYLESHEET =\n\n# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or\n# other source files which should be copied to the HTML output directory. Note\n# that these files will be copied to the base HTML output directory. Use the\n# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these\n# files. In the HTML_STYLESHEET file, use the file name only. Also note that the\n# files will be copied as-is; there are no commands or markers available.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_EXTRA_FILES =\n\n# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen\n# will adjust the colors in the style sheet and background images according to\n# this color. Hue is specified as an angle on a colorwheel, see\n# https://en.wikipedia.org/wiki/Hue for more information. For instance the value\n# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300\n# purple, and 360 is red again.\n# Minimum value: 0, maximum value: 359, default value: 220.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_COLORSTYLE_HUE = 220\n\n# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors\n# in the HTML output. For a value of 0 the output will use grayscales only. A\n# value of 255 will produce the most vivid colors.\n# Minimum value: 0, maximum value: 255, default value: 100.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_COLORSTYLE_SAT = 100\n\n# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the\n# luminance component of the colors in the HTML output. Values below 100\n# gradually make the output lighter, whereas values above 100 make the output\n# darker. The value divided by 100 is the actual gamma applied, so 80 represents\n# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not\n# change the gamma.\n# Minimum value: 40, maximum value: 240, default value: 80.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_COLORSTYLE_GAMMA = 80\n\n# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML\n# page will contain the date and time when the page was generated. Setting this\n# to YES can help to show when doxygen was last run and thus if the\n# documentation is up to date.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_TIMESTAMP = NO\n\n# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML\n# documentation will contain a main index with vertical navigation menus that\n# are dynamically created via JavaScript. If disabled, the navigation index will\n# consists of multiple levels of tabs that are statically embedded in every HTML\n# page. Disable this option to support browsers that do not have JavaScript,\n# like the Qt help browser.\n# The default value is: YES.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_DYNAMIC_MENUS = YES\n\n# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML\n# documentation will contain sections that can be hidden and shown after the\n# page has loaded.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_DYNAMIC_SECTIONS = NO\n\n# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries\n# shown in the various tree structured indices initially; the user can expand\n# and collapse entries dynamically later on. Doxygen will expand the tree to\n# such a level that at most the specified number of entries are visible (unless\n# a fully collapsed tree already exceeds this amount). So setting the number of\n# entries 1 will produce a full collapsed tree by default. 0 is a special value\n# representing an infinite number of entries and will result in a full expanded\n# tree by default.\n# Minimum value: 0, maximum value: 9999, default value: 100.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_INDEX_NUM_ENTRIES = 100\n\n# If the GENERATE_DOCSET tag is set to YES, additional index files will be\n# generated that can be used as input for Apple's Xcode 3 integrated development\n# environment (see: https://developer.apple.com/xcode/), introduced with OSX\n# 10.5 (Leopard). To create a documentation set, doxygen will generate a\n# Makefile in the HTML output directory. Running make will produce the docset in\n# that directory and running make install will install the docset in\n# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at\n# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy\n# genXcode/_index.html for more information.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_DOCSET = NO\n\n# This tag determines the name of the docset feed. A documentation feed provides\n# an umbrella under which multiple documentation sets from a single provider\n# (such as a company or product suite) can be grouped.\n# The default value is: Doxygen generated docs.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_FEEDNAME = \"Doxygen generated docs\"\n\n# This tag specifies a string that should uniquely identify the documentation\n# set bundle. This should be a reverse domain-name style string, e.g.\n# com.mycompany.MyDocSet. Doxygen will append .docset to the name.\n# The default value is: org.doxygen.Project.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_BUNDLE_ID = org.doxygen.Project\n\n# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify\n# the documentation publisher. This should be a reverse domain-name style\n# string, e.g. com.mycompany.MyDocSet.documentation.\n# The default value is: org.doxygen.Publisher.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_PUBLISHER_ID = org.doxygen.Publisher\n\n# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.\n# The default value is: Publisher.\n# This tag requires that the tag GENERATE_DOCSET is set to YES.\n\nDOCSET_PUBLISHER_NAME = Publisher\n\n# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three\n# additional HTML index files: index.hhp, index.hhc, and index.hhk. The\n# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop\n# (see: https://www.microsoft.com/en-us/download/details.aspx?id=21138) on\n# Windows.\n#\n# The HTML Help Workshop contains a compiler that can convert all HTML output\n# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML\n# files are now used as the Windows 98 help format, and will replace the old\n# Windows help format (.hlp) on all Windows platforms in the future. Compressed\n# HTML files also contain an index, a table of contents, and you can search for\n# words in the documentation. The HTML workshop also contains a viewer for\n# compressed HTML files.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_HTMLHELP = NO\n\n# The CHM_FILE tag can be used to specify the file name of the resulting .chm\n# file. You can add a path in front of the file if the result should not be\n# written to the html output directory.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nCHM_FILE =\n\n# The HHC_LOCATION tag can be used to specify the location (absolute path\n# including file name) of the HTML help compiler (hhc.exe). If non-empty,\n# doxygen will try to run the HTML help compiler on the generated index.hhp.\n# The file has to be specified with full path.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nHHC_LOCATION =\n\n# The GENERATE_CHI flag controls if a separate .chi index file is generated\n# (YES) or that it should be included in the master .chm file (NO).\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nGENERATE_CHI = NO\n\n# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc)\n# and project file content.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nCHM_INDEX_ENCODING =\n\n# The BINARY_TOC flag controls whether a binary table of contents is generated\n# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it\n# enables the Previous and Next buttons.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nBINARY_TOC = NO\n\n# The TOC_EXPAND flag can be set to YES to add extra items for group members to\n# the table of contents of the HTML help documentation and to the tree view.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTMLHELP is set to YES.\n\nTOC_EXPAND = NO\n\n# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and\n# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that\n# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help\n# (.qch) of the generated HTML documentation.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_QHP = NO\n\n# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify\n# the file name of the resulting .qch file. The path specified is relative to\n# the HTML output folder.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQCH_FILE =\n\n# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help\n# Project output. For more information please see Qt Help Project / Namespace\n# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace).\n# The default value is: org.doxygen.Project.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_NAMESPACE = org.doxygen.Project\n\n# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt\n# Help Project output. For more information please see Qt Help Project / Virtual\n# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-\n# folders).\n# The default value is: doc.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_VIRTUAL_FOLDER = doc\n\n# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom\n# filter to add. For more information please see Qt Help Project / Custom\n# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-\n# filters).\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_CUST_FILTER_NAME =\n\n# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the\n# custom filter to add. For more information please see Qt Help Project / Custom\n# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-\n# filters).\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_CUST_FILTER_ATTRS =\n\n# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this\n# project's filter section matches. Qt Help Project / Filter Attributes (see:\n# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes).\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHP_SECT_FILTER_ATTRS =\n\n# The QHG_LOCATION tag can be used to specify the location of Qt's\n# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the\n# generated .qhp file.\n# This tag requires that the tag GENERATE_QHP is set to YES.\n\nQHG_LOCATION =\n\n# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be\n# generated, together with the HTML files, they form an Eclipse help plugin. To\n# install this plugin and make it available under the help contents menu in\n# Eclipse, the contents of the directory containing the HTML and XML files needs\n# to be copied into the plugins directory of eclipse. The name of the directory\n# within the plugins directory should be the same as the ECLIPSE_DOC_ID value.\n# After copying Eclipse needs to be restarted before the help appears.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_ECLIPSEHELP = NO\n\n# A unique identifier for the Eclipse help plugin. When installing the plugin\n# the directory name containing the HTML and XML files should also have this\n# name. Each documentation set should have its own identifier.\n# The default value is: org.doxygen.Project.\n# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES.\n\nECLIPSE_DOC_ID = org.doxygen.Project\n\n# If you want full control over the layout of the generated HTML pages it might\n# be necessary to disable the index and replace it with your own. The\n# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top\n# of each HTML page. A value of NO enables the index and the value YES disables\n# it. Since the tabs in the index contain the same information as the navigation\n# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nDISABLE_INDEX = NO\n\n# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index\n# structure should be generated to display hierarchical information. If the tag\n# value is set to YES, a side panel will be generated containing a tree-like\n# index structure (just like the one that is generated for HTML Help). For this\n# to work a browser that supports JavaScript, DHTML, CSS and frames is required\n# (i.e. any modern browser). Windows users are probably better off using the\n# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can\n# further fine-tune the look of the index. As an example, the default style\n# sheet generated by doxygen has an example that shows how to put an image at\n# the root of the tree instead of the PROJECT_NAME. Since the tree basically has\n# the same information as the tab index, you could consider setting\n# DISABLE_INDEX to YES when enabling this option.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nGENERATE_TREEVIEW = YES\n\n# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that\n# doxygen will group on one line in the generated HTML documentation.\n#\n# Note that a value of 0 will completely suppress the enum values from appearing\n# in the overview section.\n# Minimum value: 0, maximum value: 20, default value: 4.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nENUM_VALUES_PER_LINE = 4\n\n# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used\n# to set the initial width (in pixels) of the frame in which the tree is shown.\n# Minimum value: 0, maximum value: 1500, default value: 250.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nTREEVIEW_WIDTH = 250\n\n# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to\n# external symbols imported via tag files in a separate window.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nEXT_LINKS_IN_WINDOW = NO\n\n# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg\n# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see\n# https://inkscape.org) to generate formulas as SVG images instead of PNGs for\n# the HTML output. These images will generally look nicer at scaled resolutions.\n# Possible values are: png The default and svg Looks nicer but requires the\n# pdf2svg tool.\n# The default value is: png.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nHTML_FORMULA_FORMAT = png\n\n# Use this tag to change the font size of LaTeX formulas included as images in\n# the HTML documentation. When you change the font size after a successful\n# doxygen run you need to manually remove any form_*.png images from the HTML\n# output directory to force them to be regenerated.\n# Minimum value: 8, maximum value: 50, default value: 10.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nFORMULA_FONTSIZE = 10\n\n# Use the FORMULA_TRANSPARENT tag to determine whether or not the images\n# generated for formulas are transparent PNGs. Transparent PNGs are not\n# supported properly for IE 6.0, but are supported on all modern browsers.\n#\n# Note that when changing this option you need to delete any form_*.png files in\n# the HTML output directory before the changes have effect.\n# The default value is: YES.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nFORMULA_TRANSPARENT = YES\n\n# The FORMULA_MACROFILE can contain LaTeX \\newcommand and \\renewcommand commands\n# to create new LaTeX commands to be used in formulas as building blocks. See\n# the section \"Including formulas\" for details.\n\nFORMULA_MACROFILE =\n\n# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see\n# https://www.mathjax.org) which uses client side JavaScript for the rendering\n# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX\n# installed or if you want to formulas look prettier in the HTML output. When\n# enabled you may also need to install MathJax separately and configure the path\n# to it using the MATHJAX_RELPATH option.\n# The default value is: NO.\n# This tag requires that the tag GENERATE_HTML is set to YES.\n\nUSE_MATHJAX = NO\n\n# When MathJax is enabled you can set the default output format to be used for\n# the MathJax output. See the MathJax site (see:\n# http://docs.mathjax.org/en/latest/output.html) for more details.\n# Possible values are: HTML-CSS (which is slower, but has the best\n# compatibility), NativeMML (i.e. MathML) and SVG.\n# The default value is: HTML-CSS.\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_FORMAT = HTML-CSS\n\n# When MathJax is enabled you need to specify the location relative to the HTML\n# output directory using the MATHJAX_RELPATH option. The destination directory\n# should contain the MathJax.js script. For instance, if the mathjax directory\n# is located at the same level as the HTML output directory, then\n# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax\n# Content Delivery Network so you can quickly see the result without installing\n# MathJax. However, it is strongly recommended to install a local copy of\n# MathJax from https://www.mathjax.org before deployment.\n# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2.\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2\n\n# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax\n# extension names that should be enabled during MathJax rendering. For example\n# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_EXTENSIONS =\n\n# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces\n# of code that will be used on startup of the MathJax code. See the MathJax site\n# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an\n# example see the documentation.\n# This tag requires that the tag USE_MATHJAX is set to YES.\n\nMATHJAX_CODEFILE =\n\n# When the SEARCHENGINE tag is enabled doxygen will generate a search box for\n# the HTML output. The underlying search engine uses javascript and DHTML and\n# should work on any modern browser. Note that when using HTML help\n# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET)\n# there is already a search function so this one should typically be disabled.\n# For large projects the javascript based search engine can be slow, then\n# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to\n# search using the keyboard; to jump to the search box use + S\n# (what the is depends on the OS and browser, but it is typically\n# , /