Metadata-Version: 2.3
Name: djblue.portal
Version: 0.64.1
Summary: A clojure tool to navigate through your data.
License: MIT License
         
         Copyright (c) 2020 Chris Badahdah
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Keywords: clojure,basilisp,inspector,portal,datafy,nav
Author: djblue
Author-email: djblue@users.noreply.github.com
Requires-Python: >= 3.8
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiohttp (>=3.11.11)
Requires-Dist: asyncio (>=3.4.3)
Requires-Dist: basilisp (>=0.4.0)
Project-URL: Changelog, https://github.com/djblue/portal/blob/master/CHANGELOG.md
Project-URL: Documentation, https://cljdoc.org/d/djblue/portal/
Project-URL: Homepage, https://github.com/djblue/portal
Project-URL: Issues, https://github.com/djblue/portal/issues
Project-URL: Standalone, https://djblue.github.io/portal/
Description-Content-Type: text/markdown

# portal

A clojure tool to navigate through your data.

[![cljdoc][cljdoc-badge]][cljdoc]
[![Clojars Project][clojars-badge]][clojars]
[![PyPI][pypi-badge]][pypi]
[![VS Code Extension][vscode-badge]][vscode]
[![Version][intellij-badge]][intellij]
[![Get help on Slack][clojurians-badge]][clojurians]



<a target="_blank" href="https://djblue.github.io/portal/?content-type=application/edn&content-url=https://raw.githubusercontent.com/djblue/portal/gh-pages/docs.edn">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/1986211/196015562-238cf450-6467-451c-a985-04c7a9b49dba.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/1986211/196015567-74ba9153-341a-4fd7-be47-2c26f0c88c2e.png">
  <img src="https://user-images.githubusercontent.com/1986211/196015562-238cf450-6467-451c-a985-04c7a9b49dba.png">
</picture>
</a>

The portal UI can be used to inspect values of various shapes and sizes. The UX
will probably evolve over time and user feedback is welcome!

For an in-depth explanation of the UI, you can jump to the [UI][ui-concepts]
docs.

## Demo

To get an overview of the Portal UI and workflow, checkout the following
recording of a [live demo][live-demo] I gave for [London
Clojurians][london-clojurians].

<a target="_blank" href="https://www.youtube.com/watch?v=Tj-iyDo3bq0">
<img src="https://img.youtube.com/vi/Tj-iyDo3bq0/hqdefault.jpg" alt="London Clojurians Demo" />
</a>

More video presentations on Portal can be found [here](./doc/videos.md).

## Usage

To start a repl with portal, run the **clojure >= 1.10.0** cli with:

```bash
clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.64.1"}}}'
```

or for a **web** **clojurescript >= 1.10.773** repl, do:

```bash
clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.64.1"}
                    org.clojure/clojurescript {:mvn/version "1.10.844"}}}' \
    -m cljs.main
```

or for a **node** **clojurescript >= 1.10.773** repl, do:

```bash
clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.64.1"}
                    org.clojure/clojurescript {:mvn/version "1.10.844"}}}' \
    -m cljs.main -re node
```

or for a **babashka >=0.2.4** repl, do:

```bash
bb -Sdeps '{:deps {djblue/portal {:mvn/version "0.64.1"}}}'
```

or for a lein `project.clj`, add:

```clojure
{:profiles {:dev {:dependencies [[djblue/portal "0.64.1"]]}}}
```

or as a global profile, add to `~/.lein/profiles.clj`:

```clojure
{:portal {:dependencies [[djblue/portal "0.64.1"]]}}
```

> [!NOTE]
> If you add Portal to a profile other than `:dev`, when starting a REPL
> start it with `with-profiles +portal`. The `+` is important.

or for [**Clojure CLR**][clojure-clr], checkout this [example project](./examples/clr),

or for examples on how to integrate portal into an existing project, look
through the [examples](./examples) directory.

> [!NOTE]
> Portal can also be used without a runtime via the [standalone version](./doc/guides/standalone.md).

### API

Try the [portal api](./src/portal/api.cljc) with the following commands:

```clojure
;; for node and jvm
(require '[portal.api :as p])

;; for web
;; NOTE: you might need to enable popups for the portal ui to work in the
;; browser.
(require '[portal.web :as p])


(def p (p/open)) ; Open a new inspector

;; or with an extension installed, do:
(def p (p/open {:launcher :vs-code}))  ; jvm / node only
(def p (p/open {:launcher :intellij})) ; jvm / node only

(add-tap #'p/submit) ; Add portal as a tap> target

(tap> :hello) ; Start tapping out values

(p/clear) ; Clear all values

(tap> :world) ; Tap out more values

(prn @p) ; bring selected value back into repl

(remove-tap #'p/submit) ; Remove portal from tap> targetset

(p/close) ; Close the inspector when done

(p/docs) ; View docs locally via Portal - jvm / node only
```

> [!WARNING] 
> Portal will keep objects from being garbage collected until they are cleared
> from the UI.

### Options

Options for `portal.api/open`:

| Option          | Description                                 | Default             | Spec                                                                        |
|-----------------|---------------------------------------------|---------------------|-----------------------------------------------------------------------------|
| `:window-title` | Custom window title for UI                  | "portal"            | string?                                                                     |
| `:theme`        | Default theme for UI                        | :portal.colors/nord |                                                                             |
| `:value`        | Root value of UI                            | (atom (list))       |                                                                             |
| `:app`          | Launch UI in Chrome app window              | true                | boolean?                                                                    |
| `:launcher`     | Launch UI using this editor                 |                     | #{[:vs-code][vs-code-docs] [:intellij][intellij-docs] [:emacs][emacs-docs]} |
| `:editor`       | Enable editor commands, but use separate UI |                     | #{[:vs-code][vs-code-docs] [:intellij][intellij-docs] [:emacs][emacs-docs]} |
| `:port`         | Http server port for UI                     | 0                   | int?                                                                        |
| `:host`         | Http server host for UI                     | "localhost"         | string?                                                                     |


For more documentation, take a look through the [docs][docs].

[cljdoc]: https://cljdoc.org/d/djblue/portal/CURRENT
[cljdoc-badge]: https://cljdoc.org/badge/djblue/portal
[clojars]: https://clojars.org/djblue/portal
[clojars-badge]: https://img.shields.io/clojars/v/djblue/portal?color=380036
[vscode]: https://marketplace.visualstudio.com/items?itemName=djblue.portal
[vscode-badge]: https://img.shields.io/visual-studio-marketplace/v/djblue.portal?label=vs-code&color=007ACC&logo=vs
[intellij]: https://plugins.jetbrains.com/plugin/18467-portal
[intellij-badge]: https://img.shields.io/jetbrains/plugin/v/18467?label=intellij

[clojurians]: https://clojurians.slack.com/channels/portal
[clojurians-badge]: https://img.shields.io/badge/slack-clojurians%20%23portal-4A154B?color=63B132

[live-demo]: https://www.youtube.com/watch?v=Tj-iyDo3bq0
[london-clojurians]: https://www.youtube.com/channel/UC-pYfofTyvVDMwM4ttfFGqw
[docs]: https://cljdoc.org/d/djblue/portal/0.64.1/doc/ui-concepts
[ui-concepts]: https://cljdoc.org/d/djblue/portal/0.64.1/doc/ui-concepts

[vs-code-docs]: ./doc/editors/vs-code.md
[intellij-docs]: ./doc/editors/intellij.md
[emacs-docs]: ./doc/editors/emacs.md#xwidget-webkit-embed

[clojure-clr]: https://github.com/clojure/clojure-clr

[pypi-badge]: https://img.shields.io/pypi/v/djblue.portal?color=ffd343
[pypi]: https://pypi.org/project/djblue.portal/
