Package: dcode
# dcode://Dcode is a URL scheme for sharing code.pip install –user dcode && python -m dcode install# Link-to-codeA dCode URL represents a location in a codebase.A dCode handler finds this code on a particular computer and opens it with the user’s preferred editor.URLs can be shared within a team, embedded in documentation, tickets, comments, or simply stored as personal bookmarks. Same as HTTP.URLs support different degrees of precision and are capable of describing what a location means across code changes. It can mean “this exact place and time” or “this function definition in the latest master”.## Strict modeA dCode URL that contains a repository URL, commit ID, path, line and column numbers uniquely identifies a location. It may also contain other details for readability, or to allow friendly alternative behaviors of handlers.## Human-friendly modeURLs may omit all parts but the path. This makes it easy to write them by hand or to generate them from other tools. Handlers should make their best efforts to locate the code that best matches the URL.# ExamplesAbsolute minimum. When referring to a file, simply add “dcode colon triple slash” in front of it.dcode:///some_pretty_specific/filename.jsIf the path is not unique enough (like main.js), add the repo name between the slashes:dcode://my_project/main.jsAdd basic in-file location:dcode://my_project/main.js?line=12Make it robust to changes using words. The handler can be smart and find it even after the code has changed, within reason:dcode://my_project/main.js?line=12&column=4&word=MyComponent,functionMake it unambiguous across spacetime, complete with git url and commit id.dcode://my_project/README.md?git=git%40github.com%3Adeckardai%2Fdcode.git&h=63d2f71&line=12&column=3Of course, those would rather be generated by tools, for instance editor plugins.# SpecificationA dCode URL is composed of a mandatory path and optional repository and file information (spaces for readability):dcode:// repo_name / path ? repo_spec & code_specpath: the path to a file relative to the root of a project, typically a git repository.repo_name: the common name of the repo, the last part of a repo url and typically the name of the local working directory.repo_speccan indicate version control details, such as branch names and commit ids.code_speccan indicate the location of code inside of a file.Parameters, if present, should appear in the following order, so that people can learn to read them quickly.## Repository specificationgit: a URL that can be interpreted by git. Must be URL-encoded.hg: a URL that can be interpreted by mercurial. Must be URL-encoded.commitorh: a specific commit hash.branchorb: a branch or tag.dateord: a date as YYYY-MM-DD, representing the last commit of the day in UTC, in the specified or the default branch.## Code specificationlineorl: line number starting at 1.columnorc: column number starting at 1.wordorw: one or more words that should appear at the URL location. Several words can be given, separated by commas. Words should be interpreted as case-insensitive, unless they explicitely contain an uppercase letter. This allows handlers to find code across changes.## NameA name or comment can be added at the end of URLs like this:#–Some_name. This makes links easier to manage.# ImplementationThe current implementation looks for all git or mercurial repositories in the home directory, by default. It can open files at the right place in any code editor. A couple of presets are provided. Contributions welcome!# Installpip install –user dcode && python -m dcode installThis will install the url handler and open a test file after a few seconds.
DCode will likely select a basic text editor.If you don’t have pip yet:easy_install pip# ConfigureEdit~/.dcode.jsonto choose your actual IDE.You should now be able to click links and end up right in your text editor.# DemoDemo link: [dcode://_demo/demo.txt?l=3&c=30](http://dcode.online/_demo/demo.txt?l=3&c=30)Or simulating if the link is not clickable for you:python -m dcode ‘dcode://_demo/demo.txt?l=3&c=30’# ContributingIdeas and bug reports are welcome inIssues, or code as pull requests.Examples:Editor plugins generating URLs.Make something more robust in a particular environment.Make URLs more robust to code changes, multiple branches, and such.## Development setup:git clonehttps://github.com/deckardai/dcode.gitcd dcode
pip install –user -e .