diff --git a/lib/vega_lite.ex b/lib/vega_lite.ex index 398f646..38b18a5 100644 --- a/lib/vega_lite.ex +++ b/lib/vega_lite.ex @@ -99,6 +99,12 @@ defmodule VegaLite do `axis: [label_angle: -45]`, this library will automatically rewrite it `labelAngle`, which is the name used by the VegaLite specification. + + ## Export + + `VegaLite` graphics can be exported into various formats, such as + SVG, PNG and PDF thorugh the [`:vega_lite_convert`](https://hexdocs.pm/vega_lite_convert) + package. """ @schema_url "https://vega.github.io/schema/vega-lite/v5.json" diff --git a/lib/vega_lite/export.ex b/lib/vega_lite/export.ex index 31376bf..f938b73 100644 --- a/lib/vega_lite/export.ex +++ b/lib/vega_lite/export.ex @@ -1,40 +1,10 @@ +# TODO: remove on v1.0 defmodule VegaLite.Export do - @moduledoc """ - Various export methods for a `VegaLite` specification. - - All of the export functions depend on the `:jason` package. - Additionally the PNG, SVG and PDF exports rely on npm packages, - so you will need Node.js, `npm`, and the following dependencies: - - ```console - $ npm install -g vega vega-lite canvas - ``` - - Alternatively you can install the dependencies in a local directory: - - ```console - $ npm install vega vega-lite canvas - ``` - """ + @moduledoc false alias VegaLite.Utils - @doc """ - Saves a `VegaLite` specification to file in one of - the supported formats. - - ## Options - - * `:format` - the format to export the graphic as, - must be either of: `:json`, `:html`, `:png`, `:svg`, `:pdf`. - By default the format is inferred from the file extension. - - * `:local_npm_prefix` - a relative path pointing to a local npm project directory - where the necessary npm packages are installed. For instance, in Phoenix projects - you may want to pass `local_npm_prefix: "assets"`. By default the npm packages - are searched for in the current directory and globally. - - """ + @deprecated "Use VegaLite.Convert.save!/3 in from the :vega_lite_convert package instead" @spec save!(VegaLite.t(), binary(), keyword()) :: :ok def save!(vl, path, opts \\ []) do {format, opts} = @@ -69,9 +39,7 @@ defmodule VegaLite.Export do @compile {:no_warn_undefined, {Jason, :encode!, 1}} - @doc """ - Returns the underlying Vega-Lite specification as JSON. - """ + @deprecated "Use VegaLite.Convert.to_json/1 in from the :vega_lite_convert package instead" @spec to_json(VegaLite.t()) :: String.t() def to_json(vl) do Utils.assert_jason!("to_json/1") @@ -81,12 +49,7 @@ defmodule VegaLite.Export do |> Jason.encode!() end - @doc """ - Builds an HTML page that renders the given graphic. - - The HTML page loads necessary JavaScript dependencies from a CDN - and then renders the graphic in a root element. - """ + @deprecated "Use VegaLite.Convert.to_html/1 in from the :vega_lite_convert package instead" @spec to_html(VegaLite.t()) :: binary() def to_html(vl) do json = to_json(vl) @@ -113,62 +76,26 @@ defmodule VegaLite.Export do """ end + @doc false + def to_html_no_deprecation(vl), do: to_html(vl) + defp escape_double_quotes(json) do String.replace(json, ~s{"}, ~s{\\"}) end - @doc """ - Renders the given graphic as a PNG image and returns - its binary content. - - Relies on the `npm` packages mentioned above. - - ## Options - - * `:local_npm_prefix` - a relative path pointing to a local npm project directory - where the necessary npm packages are installed. For instance, in Phoenix projects - you may want to pass `local_npm_prefix: "assets"`. By default the npm packages - are searched for in the current directory and globally. - - """ + @deprecated "Use VegaLite.Convert.to_png/1 in from the :vega_lite_convert package instead" @spec to_png(VegaLite.t(), keyword()) :: binary() def to_png(vl, opts \\ []) do node_convert(vl, "png", "to_png/1", opts) end - @doc """ - Renders the given graphic as an SVG image and returns - its binary content. - - Relies on the `npm` packages mentioned above. - - ## Options - - * `:local_npm_prefix` - a relative path pointing to a local npm project directory - where the necessary npm packages are installed. For instance, in Phoenix projects - you may want to pass `local_npm_prefix: "assets"`. By default the npm packages - are searched for in the current directory and globally. - - """ + @deprecated "Use VegaLite.Convert.to_svg/1 in from the :vega_lite_convert package instead" @spec to_svg(VegaLite.t(), keyword()) :: binary() def to_svg(vl, opts \\ []) do node_convert(vl, "svg", "to_svg/1", opts) end - @doc """ - Renders the given graphic into a PDF and returns its - binary content. - - Relies on the `npm` packages mentioned above. - - ## Options - - * `:local_npm_prefix` - a relative path pointing to a local npm project directory - where the necessary npm packages are installed. For instance, in Phoenix projects - you may want to pass `local_npm_prefix: "assets"`. By default the npm packages - are searched for in the current directory and globally. - - """ + @deprecated "Use VegaLite.Convert.to_pdf/1 in from the :vega_lite_convert package instead" @spec to_pdf(VegaLite.t(), keyword()) :: binary() def to_pdf(vl, opts \\ []) do node_convert(vl, "pdf", "to_pdf/1", opts) diff --git a/lib/vega_lite/viewer.ex b/lib/vega_lite/viewer.ex index d2e77c4..da0a867 100644 --- a/lib/vega_lite/viewer.ex +++ b/lib/vega_lite/viewer.ex @@ -1,25 +1,14 @@ +# TODO: remove on v1.0 defmodule VegaLite.Viewer do - @moduledoc """ - Graphics rendering using Erlang's `:wx` bindings. + @moduledoc false - This method is useful for viewing graphics in scripts - and IEx sessions. Note it requires Erlang/OTP 24+ with - a recent WxWidgets installation with webview support. - """ - - @doc """ - Renders a `VegaLite` specification in GUI window widget. - - Requires Erlang compilation to include the `:wx` module. - """ + @deprecated "Use VegaLite.Convert.open_viewer/1 in from the :vega_lite_convert package instead" @spec show(VegaLite.t()) :: :ok | :error def show(vl) do with {:ok, _pid} <- start_wx_viewer(vl), do: :ok end - @doc """ - Same as `show/1`, but blocks until the window widget is closed. - """ + @deprecated "Use VegaLite.Convert.open_viewer_and_wait/1 in from the :vega_lite_convert package instead" @spec show_and_wait(VegaLite.t()) :: :ok | :error def show_and_wait(vl) do with {:ok, pid} <- start_wx_viewer(vl) do @@ -33,7 +22,7 @@ defmodule VegaLite.Viewer do defp start_wx_viewer(vl) do vl - |> VegaLite.Export.to_html() + |> VegaLite.Export.to_html_no_deprecation() |> VegaLite.WxViewer.start() end end diff --git a/lib/vega_lite/wx_viewer.ex b/lib/vega_lite/wx_viewer.ex index ae52af7..3f701e1 100644 --- a/lib/vega_lite/wx_viewer.ex +++ b/lib/vega_lite/wx_viewer.ex @@ -1,3 +1,4 @@ +# TODO: remove on v1.0 defmodule VegaLite.WxViewer do @moduledoc false