Metadata-Version: 1.1
Name: dcode
Version: 0.1.2
Summary: A URL scheme to share code
Home-page: https://github.com/deckardai/dcode
Author: Aurélien Nicolas
Author-email: info@deckard.ai
License: Apache2
Description: # dcode://
        
        Dcode is a URL scheme for sharing code.
        
            pip install --user dcode && python -m dcode install
        
        # Link-to-code
        
        A 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 mode
        
        A 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 mode
        
        URLs 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.
        
        # Examples
        
        Absolute minimum. When referring to a file, simply add "dcode colon triple slash" in front of it.
        
            dcode:///some_pretty_specific/filename.js
        
        If the path is not unique enough (like main.js), add the repo name between the slashes:
        
            dcode://my_project/main.js
        
        Add basic in-file location:
        
            dcode://my_project/main.js?line=12
        
        Make 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,function
        
        Make 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=3
        
        Of course, those would rather be generated by tools, for instance editor plugins.
        
        
        # Specification
        
        A dCode URL is composed of a mandatory path and optional repository and file information (spaces for readability):
        
            dcode:// repo_name / path ? repo_spec & code_spec
        
        `path`: 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_spec` can indicate version control details, such as branch names and commit ids.
        
        `code_spec` can 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 specification
        
        `git`: 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.
        
        `commit` or `h`: a specific commit hash.
        
        `branch` or `b`: a branch or tag.
        
        `date` or `d`: a date as YYYY-MM-DD, representing the last commit of the day in UTC, in the specified or the default branch.
        
        ## Code specification
        
        `line` or `l`: line number starting at 1.
        
        `column` or `c`: column number starting at 1.
        
        `word` or `w`: 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.
        
        ## Name
        
        A name or comment can be added at the end of URLs like this: `#--Some_name`. This makes links easier to manage.
        
        
        # Implementation
        
        The 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!
        
        
        # Install
        
            pip install --user dcode && python -m dcode install
        
        This 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
        
        # Configure
        
            Edit `~/.dcode.json` to choose your actual IDE.
        
        You should now be able to click links and end up right in your text editor.
        
        # Demo
        
        Demo link: [dcode://_demo/demo.txt?l=3&c=30](dcode://_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'
        
        # Contributing
        
        Ideas and bug reports are welcome in *Issues*, 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 clone https://github.com/deckardai/dcode.git
            cd dcode
            pip install --user -e .
        
Keywords: url code file sharing development
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
