{"id":20292905,"url":"https://github.com/fdch/pddb","last_synced_at":"2025-12-31T01:03:21.230Z","repository":{"id":54609499,"uuid":"449421261","full_name":"fdch/pddb","owner":"fdch","description":"A Pure Data Data Base","archived":false,"fork":false,"pushed_at":"2022-08-09T11:05:13.000Z","size":51,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-14T09:15:55.294Z","etag":null,"topics":["c","database","json","pure-data"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fdch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-18T19:34:18.000Z","updated_at":"2022-08-12T03:45:26.000Z","dependencies_parsed_at":"2022-08-13T21:20:47.882Z","dependency_job_id":null,"html_url":"https://github.com/fdch/pddb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdch%2Fpddb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdch%2Fpddb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdch%2Fpddb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdch%2Fpddb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fdch","download_url":"https://codeload.github.com/fdch/pddb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241787485,"owners_count":20020101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","database","json","pure-data"],"created_at":"2024-11-14T15:19:52.488Z","updated_at":"2025-12-31T01:03:21.195Z","avatar_url":"https://github.com/fdch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nThis repository has been archived in favor of https://github.com/pdpy-org/pddb\n\n---\n\n# PDDB - Pure Data Data Base Specification\n\n`pddb` is a JSON database that parses the Pure Data source code to get data about\nthe internal objects. It is useful in the context of the `pdpy` project, with\npossible other uses like autocomplete, error check when typing, etc. In the\nfollowing text there is a brief description of the JSON data structure.\n\n## Live querying\n\nSimply run `make start`, start typing your queries.\nYou should see a message like this on your Terminal:\n\n```sh\nStarting live database...\nType your queries, eg: osc~, and hit RETURN to get the result.\nType QUIT and hit RETURN to quit.\nStarting server...\nStarting client...\nListening on 127.0.0.1:9226\nConnected by ('127.0.0.1', 61874)\n```\n\nFor example, when typing `osc~` and hitting return, this is the result:\n\n```sh\nosc~\nReceived: [True, namespace(inlets=2, outlets=1), 1]\n```\n\nWhich means that `osc~`\n\n- is an object --\u003e `True`\n- has 2 inlets and 1 outlet --\u003e `namespace(inlets=2, outlets=1))`\n- takes 1 optional creation argument --\u003e `1`\n\n## Grab the database\n\nSimply run `wget https://raw.githubusercontent.com/fdch/pddb/main/pddb.json`\n\n## Make the database\n\n1. Clone or download the [Pure Data distribution](https://github.com/pure-data/pure-data)\n2. Clone or download this repository.\n3. Run the following:\n\n```bash\ncd pddb\nmake PDDIR=/path/to/pure-data\n```\n\nWhere `/path/to/pure-data` is the path to *your* Pure Data distribution.\nMine looks like `~/Development/pure-data`, which is the default.\n\n## Goals\n\nThe purpose of this database is to better understand the internal structure of\nthe `Pure Data` source code, and to enable language checks for the `pdpy` project.\nPRs are welcome.\n\n## Loading PDDB with python\n\nYou can load `pddb.json` as a json object like this:\n\n```python\nimport json\nwith open('pddpy.json') as f:\n  data = json.load(f)\n\nprint(data)\n```\n\nNOTE: the `data` variable will be used in the python examples that follow.\n\n## JSON data structure\n\nThis database is an `Array` of `Object`s, meaning that:\n\n1. A single `Array` encloses the entire database.\n2. Every element contains exactly one [Entry Object](#entry-object).\n\n## Entry Object\n\nEach **entry** `Object` has two keys named `file` and `classes`. The structure\nlooks like this:\n\n```json\n[\n {\n   \"file\" : '',\n   \"classes\" : []\n }, ...\n]\n```\n\n### `file`\n\n```python\n\u003e\u003e\u003e data[0]['file']\n'/path/to/pure-data/extra/pique/pique.c'\n```\n\nThis key contains exactly one `String` with the path to the Pure Data `.c` file\nfrom which the data of that specific entry was obtained.\n\nIn python, you can extract all `file` keys like this:\n\n```python\n\u003e\u003e\u003e [entry['file'] for entry in data]\n['/path/to/pure-data/extra/pique/pique.c', ... ****]\n```\n\n### `classes`\n\n```python\n\u003e\u003e\u003e data[0]['classes']\n[{'className': 'pique', 'attributes': {'patchable': False, 'newmethod': 'pique_new', 'arguments': {'name': 'pique', 'args': ['A_DEFFLOAT']}, 'methods': ['list', {'name': 'errthresh', 'args': ['A_FLOAT']}], 'description': {'kind': 'data', 'subkind': 'array'}, 'iolets': {'outlets': 1}}}]\n```\n\nThis key contains an `Array` of [Class Objects](#class-object) that describe the Pure Data classes found in the file path to which `file` points. In this `classes` key you will find most of the data.\n\n## Class Object\n\nEach **class** `Object` has two keys: `className` and `attributes`.\n\n```json\n[\n {\n   \"file\": \"\",\n   \"classes\": [\n       {\n           \"className\": \"\",\n           \"attributes\": {} | []\n       }, ...\n }, ...\n]\n```\n\n### `className`\n\n```python\n\u003e\u003e\u003e data[0]['classes'][0]['className']\n'pique'\n```\n\nThis key has exactly one `String` with the name by which this specific class\nis refered to internally in the source code.\n\n### `attributes`\n\n```python\n\u003e\u003e\u003e data[0]['classes'][0]['attributes']\n{'patchable': False, 'newmethod': 'pique_new', 'arguments': {'name': 'pique', 'args': ['A_DEFFLOAT']}, 'methods': ['list', {'name': 'errthresh', 'args': ['A_FLOAT']}], 'description': {'kind': 'data', 'subkind': 'array'}, 'iolets': {'outlets': 1}}\n```\n\nThis key can hold either one or multiple [Attribute Objects](#attribute-object).\nTherefore, it can be either an `Object` or an `Array` of `Object`s and needs\nto be parsed accordingly.\n\n## Attribute Object\n\nThis `Object` contains variable keys depending on the Pure Data class it describes. The possible keys are:\n\n| Key           | Type                  | Description                                                                                            |\n| --------------| :-------------------: | ------------------------------------------------------------------------------------------------------ |\n| `patchable`   | `bool`                | Describes if object has inlets or not.                                                                 |\n| `newmethod`   | `String`              | The method by which the class is instantiated as a new object.                                         |\n| `arguments`   | `Object|String`       | Describes the object's creation arguments. See [Arguments](#arguments).                                |\n| `methods`     | `String|Object|Array` | Describes the object's [methods](#methods).                                                            |\n| `description` | `Object`              | Describes the object with `kind` and a `subkind`  keys. See [Description Object](#description-object). |\n| `iolets`      | `Object`              | Describes the objects `inlets` and `outlets`. See [iolet Object](#iolets-object).                      |\n| `signal`      | `bool`                | Describes if object processes audio or not.                                                            |\n| `alias`       | `String`              | This contains an alias string that can be used to create the object when patching.                     |\n| `help`        | `String`              | This contains the help file identifier when multiple objects are grouped into the same help file.      |\n\n## `arguments`\n\n```python\n\u003e\u003e\u003e data[0]['classes'][0]['attributes']['arguments']\n{'name': 'pique', 'args': ['A_DEFFLOAT']}\n```\n\nThis key can either be a `String` or an **argument** `Object` (See [Argument Object](#argument-object))  \n\n### `arguments` Sring\n\n```python\n\u003e\u003e\u003e data[3]['classes'][0]['attributes']['arguments']\n'loop~'\n```\n\nIf `arguments` is a `String`, this means that the Pure Data object does not take any arguments except the creation argument. So, the `String` represents the argument needed to create the object when patching.\n\n### `argument` Object\n\n```python\n\u003e\u003e\u003e data[23]['classes'][0]['attributes']['arguments']\n{'name': 'delay', 'args': ['A_DEFFLOAT', 'A_DEFFLOAT', 'A_DEFSYM']}\n```\n\nIf `arguments` is an `Object`, then the Pure Data object takes arguments besides its creation argument.\n\nThe **argument** `Object` contains a `name` and an `args` keys, for example:\n\n```json\n\"arguments\": {\n    \"name\": \"moses\",\n    \"args\": [\n        \"A_DEFFLOAT\"\n    ]\n}\n```\n\n#### `argument[\"name\"`]\n\nIf the **argument** `Object` is within the `arguments` key, then the `name` key points to the creation argument (e.g., `\"moses\"` or `\"array define\"`). \n\n```python\n\u003e\u003e\u003e data[0]['classes'][0]['attributes']['arguments']['name']\n'pique'\n```\n\nHowever, it it is within the `methods` key, then the `name` key points to the \"message\" header. \n\nFor example, in the case of the `netreceive` object, the message header to set the internal port is \"listen\", and it takes a `list` as argument. This looks like this:\n\n```json\n\"name\": \"listen\",\n\"args\": [\n    \"A_GIMME\"\n]\n```\n\n#### `argument[\"args\"]`\n\nThe `args` key contains an `Array` of argument types as defined in the Pure Data source code (e.g., `\"A_DEFFLOAT\"`). The list of possible argument types is:\n\n| Type          | Description                                                                                                              |\n| ------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| `A_DEFFLOAT`  |  A `float` type argument that can either be present or the Pure Data object falls back to the argument's default value.  |\n| `A_GIMME`     |  A `list` of arguments.                                                                                                  |\n| `A_DEFSYM`    |  A `symbol` type argument that can either be present or the Pure Data object falls back to the argument's default value. |\n| `A_DEFSYMBOL` |  Same as `\"A_DEFSYM\"`                                                                                                    |\n| `A_FLOAT`     |  A `float` type argument that *must* be present.                                                                         |\n| `A_SYMBOL`    |  A `symbol` type argument that *must* be present.                                                                        |\n\n## `methods`\n\nThis key describes the way to interface with the object via Pure Data \"messages\". The `methods` key can be either a `String` or an **argument** `Object` or an `Array` combining both.\n\nIf there is no `methods` key present, then the object takes no messages.\n\n### `methods` Array\n\nThis `Array` can hold a combination of `String` and **argument** `Object`s.\nThis needs to be taken into account when parsing. Continue reading for each specification.\n\n### `methods` Sring\n\n```python\n\u003e\u003e\u003e data[26]['classes'][0]['attributes']['methods']\n'list'\n```\n\nIf `methods` is a `String`, this means that the Pure Data object takes only one message. So, the `String` represents the message that takes exactly one symbol, for example, the \"bang\" message. The above\nexample is from the `midiin` object.\n\n### `methods` Object\n\n```python\n\u003e\u003e\u003e data[23]['classes'][0]['attributes']['methods']\n['bang', 'stop', {'name': 'float', 'args': ['A_FLOAT']}, {'name': 'tempo', 'args': ['A_FLOAT', 'A_SYMBOL']}]\n```\n\nThis `Object` describes the way to construct the message to interface with the Pure Data object. It is exactly like the arguments object. See [Argument Object](#argument-object).\nThe above example is from the `delay` object.\n\n## `description` Object\n\n```python\n\u003e\u003e\u003e data[26]['classes'][0]['attributes']['description']\n{'kind': 'interface', 'subkind': 'midi'}\n```\n\nThe **description** `Object` contains two keys, `kind` and `subkind`, each holding a `String` that attempts to classify the Pure Data object in the following way:\n\n### `description[\"kind\"]`\n\nThese are the different kinds of Pure Data objects that this description performs:\n\n```json\ndata, signal, interface, parsing, control, operators\n```\n\n| Kind | Description |\n| ---  |      ---    |\n| `signal` | The object processes audio in DSP blocks\u003c/td\u003e|\n| `interface` | Objects that handle user interface actions |\n| `operators` | Control operators |\n| `data` | Handle various data structures |\n| `parsing` | Parsing functions |\n| `control` | Control flow |\n| `nonobj` | Non public objects |\n| `obsolete` | Objects marked as obsolete |\n| `extra` | None of the above `kind` |\n\n### `description[\"subkind\"]`\n\nThese are the different sub-kinds of Pure Data objects that this description performs:\n\n```json\narray, analysis, midi, generators, block, list, system, time, gui, math, stream, other, text, struct, fourier, filters, canvas, format, network, control_to_sig, flow, delays, comparison, binary, keyboard, route, types\n```\n\n### `signal`\n\n| `signal` | Description |\n| --- | ---|\n| `math` | Performs mathematical functions on the audio block.\n| `fourier` | Performs the Fast Fourier Transform on the audio block.\n| `filters` | Filters the audio signal block.\n| `flow` | Signal object inlets and outlets.\n| `delays` | Delays a signal block.\n| `route` | Signal routing.\n| `generators` | Signal generators.\n| `system` | Input/Output to disk or to audio interface.\n| `control_to_sig` | Converts control to signal.\n| `array` | Interface signals with tables and arrays.\n| `block` | Interface to change the DSP block.\n| `analysis` | Analyze the signal block.\n\n### `interface`\n\n| `interface` | Description |\n| --- | --- |\n|`midi` | Handle MIDI input and output |\n|`keyboard` | Handle Keyboard events |\n|`system` | Handle System events |\n|`gui` | Graphical User Interface objects |\n\n### `operators`\n\n| `operators` | Description |\n| --- | --- |\n| `math` | Mathematical operators |\n| `binary` | Binary operators |\n| `comparison` | Comparison perators |\n\n### `data`\n\n| `data` | Description |\n| --- | --- |\n| `array` | Tables and Arrays |\n| `struct` | Data Structures |\n| `text` | Text objects |\n| `canvas` | Subpatches |\n| `other` | None of the above |\n\n### `parsing`\n\n| `parsing` | Description |\n| --- | --- |\n| `list` | Parse list elements |\n| `stream` | Parse an incoming stream |\n| `forma` | Format parsing |\n\n### `control`\n\n| `control` | Description |\n| --- | --- |\n| `flow` | Inlets and Outlets|\n| `network` | Network objects |\n| `math` | Mathematical operations |\n| `time` | Delay and time operations |\n| `generators` | Control flow Generators |\n| `types` | Type casting |\n\n## `iolets` Object\n\n```python\n\u003e\u003e\u003e data[35]['classes'][0]['attributes']['iolets']\n{'inlets': 2, 'outlets': 1}\n```\n\nThe **iolets** `Object` contains two keys, `inlets` and `outlets`, each\nholding a `Number` that describes how many `inlet` and `outlet` the Pure Data\nobject box has. The above example is from the `hip~` object.\n\n## Example\n\nThis is an example of the `x_misc.c` entry. The only class that is shown is the\n`random` class, the rest are omitted:\n\n```json\n[\n {\n   \"file\": \"/Users/fd/Development/pure-data/src/x_misc.c\",\n        \"classes\": [\n            {\n                \"className\": \"random\",\n                \"attributes\": {\n                    \"patchable\": true,\n                    \"newmethod\": \"random_new\",\n                    \"arguments\": {\n                        \"name\": \"random\",\n                        \"args\": [\n                            \"A_DEFFLOAT\"\n                        ]\n                    },\n                    \"methods\": \"bang\",\n                    \"description\": {\n                        \"kind\": \"control\",\n                        \"subkind\": \"generators\"\n                    },\n                    \"iolets\": {\n                        \"inlets\": 2,\n                        \"outlets\": 1\n                    }\n                }\n            }, ...\n }, ...\n]\n```\n\n### Limitations\n\nThe `\"random\"` `className` is located in the `x_misc.c` file. The\nPure Data object is created with the `\"random\"` symbol and an\noptional float (`A_DEFFLOAT`). It has a single method that is\nrepresented by the `\"bang\"` string, and it is described as a\n`control` object of the `generators` subkind. It has `2` inlets and\n`1` outlet.\n\nWhile this is true, it is incomplete. From this description alone,\nwe are missing information about the functionality of the object.\nFor example, we cannot know what the object does. Other limitations come from the fact that the `.c` files are not loaded but parsed,\nand some object attributes may depend on creation arguments and other\ncircumstances during instantiation. Accounting for these is still in the todo list.\n\nYou are of course welcome to help in any way. Please file an issue or make a PR!\n\n## Credits\n\nFede Camara Halac (fdch)\n\nPure Data by Miller Puckette.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffdch%2Fpddb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffdch%2Fpddb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffdch%2Fpddb/lists"}