From caa24d3ef9345e98ccb7cdab410eaa19ee78d4cc Mon Sep 17 00:00:00 2001 From: Brian Potchik Date: Tue, 1 Oct 2019 10:55:50 -0400 Subject: Clean-up BinaryView and Settings documentation. --- python/settings.py | 81 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 25 deletions(-) (limited to 'python/settings.py') diff --git a/python/settings.py b/python/settings.py index 0c613fe1..fec4023d 100644 --- a/python/settings.py +++ b/python/settings.py @@ -36,30 +36,30 @@ class Settings(object): values is also configurable and can be different for each level. This allows for ephemeral or platform-independent \ persistent settings storage for components within Binary Ninja or consumers of the Binary Ninja API. - Each `Settings` instance has a unique `instance_id` and a settings schema which defines the contents for the settings \ - repository. By default, a new `Settings` instance contains an empty schema. A schema can be built up by using the \ - `register_group` and `register_setting` methods, or by deserializing an existing schema with `deserialize_schema` \ - Binary Ninja provides a default `Settings` instance identified as 'default'. The 'default' settings repository defines \ + Each :class:`Settings` instance has a unique ``instance_id`` and a settings schema that define the contents for the settings \ + repository. By default, a new :class:`Settings` instance contains an empty schema. A schema can be built up by using the \ + :func:`register_group` and func:`register_setting` methods, or by deserializing an existing schema with :func:`deserialize_schema`. \ + Binary Ninja provides a default :class:`Settings` instance identified as *'default'*. The *'default'* settings repository defines \ all of the settings available for the active Binary Ninja components. .. note:: The Binary Ninja Application provides many settings that are only applicable to the UI, and thus would not be \ - defined in the 'default' settings schema for Binary Ninja headless. - - Except for default setting values, values are stored separately from the schema in a backing store. The backing store can \ - be different for each level. When accessing setting values, the order of precedence is: Context > Workspace > User > Default. - - =================== ============================ ============================== =============================== - Setting Level Settings Scope Backing Store ('default') Backing Store (Other) - =================== ============================ ============================== =============================== - Default SettingsDefaultScope Settings Schema Settings Schema - User SettingsUserScope /settings.json - Workspace SettingsWorkspaceScope - Context SettingsContextScope BinaryView (Storage in bndb) BinaryView (Storage in bndb) - =================== ============================ ============================== =============================== - - Individual settings are identified by a key, which is a string in the form of '.'. Groups provide a simple way \ - to categorize settings. Additionally, sub-categories can be expressed directly in the name part of the key with the same dot \ - notation. + defined in the *'default'* settings schema for Binary Ninja headless. + + Except for *default* setting values, setting values are optional for other levels and stored separately from the schema in a \ + backing store. The backing store can be different for each level. When querying setting values, the values returned or modified \ + are in order of preference (i.e. ``SettingsAutoScope``). It is possible to override the scope by specifying the desired ``SettingsScope``. + + ================= ========================== ============== ================================ =============================== + Setting Level Settings Scope Preference Backing Store ('default') Backing Store (Other) + ================= ========================== ============== ================================ =============================== + Default SettingsDefaultScope Lowest Settings Schema Settings Schema + User SettingsUserScope - /settings.json + Workspace SettingsWorkspaceScope - + Context SettingsContextScope Highest BinaryView (Storage in bndb) BinaryView (Storage in bndb) + ================= ========================== ============== ================================ =============================== + + Individual settings are identified by a key, which is a string in the form of **'.'**. Groups provide a simple way \ + to categorize settings. Additionally, sub-categories can be expressed directly in the name part of the key with a similar dot notation. """ handle = core.BNCreateSettings("default") @@ -95,17 +95,29 @@ class Settings(object): @property def instance_id(self): - """(read-only)""" + """Returns the ``instance_id`` for this :class:`Settings` repository (read-only)""" return self._instance_id def set_resource_id(self, resource_id = None): + """ + ``set_resource_id`` Sets the resource identifier for this class:`Settings` instance. When accessing setting values at the \ + ``SettingsContextScope`` level, the resource identifier is passed along through the backing store interface. + + .. note:: Currently the only available backing store for ``SettingsContextScope`` is a :class:`BinaryView` object. In the context \ + of a :class:`BinaryView` the resource identifier is the :class:`BinaryViewType` name. All settings for this type of backing store \ + are saved in the *'Raw'* :class:`BinaryViewType`. This enables the configuration of setting values such that they are available \ + during :class:`BinaryView` creation and initialization. + + :param str resource_id: a unique identifier + :rtype: None + """ if resource_id is None: resource_id = "" core.BNSettingsSetResourceId(self.handle, resource_id) def register_group(self, group, title): """ - ``register_group`` registers a group in the schema for this `Settings` instance + ``register_group`` registers a group in the schema for this :class:`Settings` instance :param str group: a unique identifier :param str title: a user friendly name appropriate for UI presentation @@ -121,9 +133,9 @@ class Settings(object): def register_setting(self, key, properties): """ - ``register_setting`` registers a new setting with this `Settings` instance + ``register_setting`` registers a new setting with this :class:`Settings` instance - :param str key: a unique setting identifier in the form . + :param str key: a unique setting identifier in the form **'.'** :param str properties: a JSON string describes the setting schema :return: True on success, False on failure. :rtype: bool @@ -137,12 +149,31 @@ class Settings(object): return core.BNSettingsRegisterSetting(self.handle, key, properties) def contains(self, key): + """ + ``contains`` determine if a setting identifier exists in the active settings schema + + :param str key: the setting identifier + :return: True if the identifier exists in this active settings schema, False otherwise + :rtype: bool + """ return core.BNSettingsContains(self.handle, key) def is_empty(self): + """ + ``is_empty`` determine if the active settings schema is empty + + :return: True if the active settings schema is empty, False otherwise + :rtype: bool + """ return core.BNSettingsIsEmpty(self.handle) def keys(self): + """ + ``keys`` retrieve the list of setting identifiers in the active settings schema + + :return: list of setting identifiers + :rtype: list(str) + """ length = ctypes.c_ulonglong() result = core.BNSettingsKeysList(self.handle, ctypes.byref(length)) out_list = [] -- cgit v1.3.1