Skip to content

Commit

Permalink
Adding IDE/Editor support for env, documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@lovestaco
lovestaco committed Jul 23, 2023
1 parent a61ef7d commit ca8cadf
Show file tree
Hide file tree
Showing 10 changed files with 118 additions and 54 deletions.
4 changes: 2 additions & 2 deletions docs/Lama2/docs/explanation/l2format.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ The search for `l2config.env` extends from the present directory up to the root

![l2config.env at Project root level](l2configAtRoot.png)

Go to [Example](../tutorials/examples.html#case-2-root-variables)
Go to [Example](../tutorials/examples.md#case-2-root-variables)

Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0022_l2config_declare)

Expand All @@ -139,7 +139,7 @@ The local variable's value will always be considered over the root variable, ens

![l2config.env at Project root level](l2envOverideL2config.png)

Go to [Example](..g/tutorials/examples.html#case-3-override-root-variable-with-local-variable)
Go to [Example](../tutorials/examples.md#case-3-override-root-variable-with-local-variable)

Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0020_override_project_root_local)

Expand Down
2 changes: 1 addition & 1 deletion docs/Lama2/docs/tutorials/editor.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ The extension author can simply read the `stdout` after executing the command, a

![l2configvariable variable](l2configvariable.png)

Go to [Example](../tutorials/examples.html#case-3-override-root-variable-with-local-variable)
Go to [Example](../tutorials/examples.md#case-3-override-root-variable-with-local-variable)

## Syntax Highlighting

Expand Down
25 changes: 13 additions & 12 deletions docs/Lama2/site/explanation/l2format.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -531,11 +531,11 @@
</li>

<li class="md-nav__item">
<a href="#environment-variables-switch-base-url" class="md-nav__link">
Environment Variables: Switch base URL
<a href="#environment-variables" class="md-nav__link">
Environment Variables
</a>

<nav class="md-nav" aria-label="Environment Variables: Switch base URL">
<nav class="md-nav" aria-label="Environment Variables">
<ul class="md-nav__list">

<li class="md-nav__item">
Expand Down Expand Up @@ -864,11 +864,11 @@
</li>

<li class="md-nav__item">
<a href="#environment-variables-switch-base-url" class="md-nav__link">
Environment Variables: Switch base URL
<a href="#environment-variables" class="md-nav__link">
Environment Variables
</a>

<nav class="md-nav" aria-label="Environment Variables: Switch base URL">
<nav class="md-nav" aria-label="Environment Variables">
<ul class="md-nav__list">

<li class="md-nav__item">
Expand Down Expand Up @@ -995,7 +995,7 @@ <h3 id="cookies-are-sent-as-headers">Cookies are sent as headers<a class="header
<p>Cookies are specified in a <code>Cookie</code> header as follows:</p>
<div class="highlight"><pre><span></span><code>Cookie:&#39;sessionid=foo;another-cookie=bar&#39;
</code></pre></div>
<h3 id="environment-variables-switch-base-url">Environment Variables: Switch base URL<a class="headerlink" href="#environment-variables-switch-base-url" title="Permanent link">&para;</a></h3>
<h3 id="environment-variables">Environment Variables<a class="headerlink" href="#environment-variables" title="Permanent link">&para;</a></h3>
<h4 id="api-variables-can-be-defined-in-apirequestl2">API variables can be defined in <code>apirequest.l2</code><a class="headerlink" href="#api-variables-can-be-defined-in-apirequestl2" title="Permanent link">&para;</a></h4>
<p>Variables are declared within the JS processor block and serve as dynamic placeholders for data used in API requests.
By utilizing these variables, L2 enables flexibility and reusability in defining API endpoints and data payloads.</p>
Expand All @@ -1016,21 +1016,22 @@ <h4 id="api-variables-can-be-defined-in-apirequestl2">API variables can be defin
<h4 id="api-environment-variables-can-be-defined-locally-in-l2env">API environment variables can be defined locally in <code>l2.env</code><a class="headerlink" href="#api-environment-variables-can-be-defined-locally-in-l2env" title="Permanent link">&para;</a></h4>
<p>L2 provides a convenient way to define environment variables through the l2.env file.
This file is automatically searched for in the present directory,
and its contents are loaded to create a set of variables(local).</p>
and its contents are loaded to create a set of variables (local).</p>
<p>In the <code>l2.env</code> file, you can specify environment-specific values for variables used in your L2 scripts, such as URLs, authentication tokens, or any other data that may vary depending on the environment in which the API requests are executed.</p>
<p><img alt="l2.env at API level" src="l2env.png" /></p>
<p>Go to <a href="https://hexmos.com/lama2/tutorials/examples.html#case-1-l2env-adjacent-to-an-api-file">Example</a></p>
<p>Go to <a href="../tutorials/examples.html#case-1-l2env-adjacent-to-an-api-file">Example</a></p>
<p>Get <a href="https://github.com/HexmosTech/Lama2/tree/main/examples/0023_l2env_declare">Source File</a></p>
<h4 id="api-environment-variables-can-be-defined-at-project-root-using-l2configenv">API environment variables can be defined at project root using <code>l2config.env</code><a class="headerlink" href="#api-environment-variables-can-be-defined-at-project-root-using-l2configenv" title="Permanent link">&para;</a></h4>
<p>The <code>l2config.env</code> file serves as a centralized storage for environment variables located at the project root, streamlining the management of configuration settings across all L2 scripts. With this file present, every L2 script within the project automatically inherits the defined variables, effectively eliminating the necessity to duplicate configurations in individual subdirectories using <code>l2.env</code>.</p>
<p>The search for <code>l2config.env</code> extends from the present directory up to the root directory (<code>/</code>). During this process, the variables defined in the root file are loaded and made available for use in all relevant scripts. This approach significantly enhances efficiency and maintainability, as it ensures consistent settings throughout the project while reducing redundancy in configuration data.</p>
<p><img alt="l2config.env at Project root level" src="l2configAtRoot.png" /></p>
<p>Go to <a href="https://hexmos.com/lama2/tutorials/examples.html#case-2-root-variables">Example</a></p>
<p>Go to <a href="../tutorials/examples.html#case-2-root-variables">Example</a></p>
<p>Get <a href="https://github.com/HexmosTech/Lama2/tree/main/examples/0022_l2config_declare">Source File</a></p>
<h4 id="if-l2configenvroot-variables-are-redeclared-in-l2envlocal">If <code>l2config.env</code>(root) variables are redeclared in <code>l2.env</code>(local)<a class="headerlink" href="#if-l2configenvroot-variables-are-redeclared-in-l2envlocal" title="Permanent link">&para;</a></h4>
<p>In situations where both root and local variables share the same variable name, the local variable takes precedence over the root variable. This behavior remains consistent, even if both <code>l2config.env</code> (root) and <code>l2.env</code> (local) files reside in the same directory. The local variable's value will always be considered over the root variable, ensuring that specific configurations defined at the local level effectively override any corresponding settings present in the root file. This approach provides developers with granular control and flexibility in tailoring environment variables to suit specific needs within different parts of the project while maintaining the overall structure and organization of configuration settings.</p>
<p>In situations where both root and local variables share the same variable name, the local variable takes precedence over the root variable. This behavior remains consistent, even if both <code>l2config.env</code> (root) and <code>l2.env</code> (local) files reside in the same directory. </p>
<p>The local variable's value will always be considered over the root variable, ensuring that specific configurations defined at the local level effectively override any corresponding settings present in the root file. This approach provides developers with granular control and flexibility in tailoring environment variables to suit specific needs within different parts of the project while maintaining the overall structure and organization of configuration settings.</p>
<p><img alt="l2config.env at Project root level" src="l2envOverideL2config.png" /></p>
<p>Go to <a href="https://hexmos.com/lama2/tutorials/examples.html#case-3-override-root-variable-with-local-variable">Example</a></p>
<p>Go to <a href="../tutorials/examples.html#case-3-override-root-variable-with-local-variable">Example</a></p>
<p>Get <a href="https://github.com/HexmosTech/Lama2/tree/main/examples/0020_override_project_root_local">Source File</a></p>
<h3 id="the-environment-file-can-load-results-of-commands">The environment file can load results of commands<a class="headerlink" href="#the-environment-file-can-load-results-of-commands" title="Permanent link">&para;</a></h3>
<p>Use the backtick notation <code>\</code>command`` to place the results of
Expand Down
2 changes: 1 addition & 1 deletion docs/Lama2/site/search/search_index.json
View file

Large diffs are not rendered by default.

50 changes: 25 additions & 25 deletions docs/Lama2/site/sitemap.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,127 +2,127 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://hexmos.com/lama2/index.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/about/contact.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/about/hexmos.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/explanation/faq.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/explanation/l2format.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/explanation/syntax.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/api.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/architecture.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/cmdexec.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/cmdgen.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/controller.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/grammar.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/lama2cmd.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/outputmanager.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/parser.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/philosophy.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/preprocess.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/reference/utils.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/codegen.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/collaboration.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/editor.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/examples.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/installation.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/misc.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://hexmos.com/lama2/tutorials/postman.html</loc>
<lastmod>2023-07-22</lastmod>
<lastmod>2023-07-23</lastmod>
<changefreq>daily</changefreq>
</url>
</urlset>
Binary file modified docs/Lama2/site/sitemap.xml.gz
View file
Binary file not shown.
73 changes: 67 additions & 6 deletions docs/Lama2/site/tutorials/editor.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -575,10 +575,30 @@
</li>

<li class="md-nav__item">
<a href="#the-command" class="md-nav__link">
The Command
<a href="#the-commands" class="md-nav__link">
The Commands
</a>

<nav class="md-nav" aria-label="The Commands">
<ul class="md-nav__list">

<li class="md-nav__item">
<a href="#execute-current-file" class="md-nav__link">
Execute current file
</a>

</li>

<li class="md-nav__item">
<a href="#providing-environment-variable-autocompletion" class="md-nav__link">
Providing environment variable autocompletion
</a>

</li>

</ul>
</nav>

</li>

<li class="md-nav__item">
Expand Down Expand Up @@ -727,10 +747,30 @@
</li>

<li class="md-nav__item">
<a href="#the-command" class="md-nav__link">
The Command
<a href="#the-commands" class="md-nav__link">
The Commands
</a>

<nav class="md-nav" aria-label="The Commands">
<ul class="md-nav__list">

<li class="md-nav__item">
<a href="#execute-current-file" class="md-nav__link">
Execute current file
</a>

</li>

<li class="md-nav__item">
<a href="#providing-environment-variable-autocompletion" class="md-nav__link">
Providing environment variable autocompletion
</a>

</li>

</ul>
</nav>

</li>

<li class="md-nav__item">
Expand Down Expand Up @@ -766,6 +806,7 @@ <h2 id="useful-options">Useful Options<a class="headerlink" href="#useful-option
<p>The <code>l2</code> command provides some helpful options for
extension developers. The options are:</p>
<ol>
<li><code>--env</code> or <code>-e</code> outputs a JSON of environment variables (in CLI);</li>
<li><code>--nocolor</code> or <code>-n</code> disables colored output in httpie-go (in CLI);</li>
<li><code>--output=&lt;target.json</code> or <code>-o</code> writes a structured JSON
output to the target file (without colors). The following is the content
Expand All @@ -786,8 +827,9 @@ <h2 id="useful-options">Useful Options<a class="headerlink" href="#useful-option
<p class="admonition-title">Note</p>
<p>Right now, all the three values in the JSON are strings. In the future, we may transform the values further to provide a more parse-friendly structure.</p>
</div>
<h2 id="the-command">The Command<a class="headerlink" href="#the-command" title="Permanent link">&para;</a></h2>
<p>Combining the above two options, we get:</p>
<h2 id="the-commands">The Commands<a class="headerlink" href="#the-commands" title="Permanent link">&para;</a></h2>
<h3 id="execute-current-file">Execute current file<a class="headerlink" href="#execute-current-file" title="Permanent link">&para;</a></h3>
<p>Combining the options <code>-n</code> and <code>-o</code>, we get:</p>
<div class="highlight"><pre><span></span><code>l2<span class="w"> </span>-n<span class="w"> </span>-o<span class="w"> </span>/tmp/lama2.json<span class="w"> </span>my_api.l2
</code></pre></div>
<p>The command mentioned above disables HTTPie colors,
Expand All @@ -797,6 +839,25 @@ <h2 id="the-command">The Command<a class="headerlink" href="#the-command" title=
display the contents to users appropriately. For an
example, see <a href="https://github.com/HexmosTech/Lama2Code">Lama2 for VSCode</a>
(also see <a href="https://marketplace.visualstudio.com/items?itemName=hexmos.Lama2">Marketplace page</a>).</p>
<h3 id="providing-environment-variable-autocompletion">Providing environment variable autocompletion<a class="headerlink" href="#providing-environment-variable-autocompletion" title="Permanent link">&para;</a></h3>
<p>To obtain a combined JSON representation of environment variables from <code>l2.env</code> and <code>l2config.env</code>, use option <code>-e</code> or <code>--env</code>. This will output the result to <code>stdout</code>.
<div class="highlight"><pre><span></span><code>l2<span class="w"> </span>-e<span class="w"> </span>/path/to/my_api.l2
</code></pre></div>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="w"> </span><span class="nt">&quot;AHOST&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">&quot;src&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;l2env&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;val&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;http://127.0.0.1:8000&quot;</span>
<span class="w"> </span><span class="p">},</span>
<span class="w"> </span><span class="nt">&quot;BHOST&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">&quot;src&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;l2configenv&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;val&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;https://httpbin.org&quot;</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span>
</code></pre></div>
The extension author can simply read the <code>stdout</code> after executing the command, and display the variables to users appropriately.</p>
<p><img alt="l2envvariable variable" src="l2envvariable.png" /></p>
<p><img alt="l2configvariable variable" src="l2configvariable.png" /></p>
<p>Go to <a href="examples.html#case-3-override-root-variable-with-local-variable">Example</a></p>
<h2 id="syntax-highlighting">Syntax Highlighting<a class="headerlink" href="#syntax-highlighting" title="Permanent link">&para;</a></h2>
<p>The VSCode plugin implements a rudimentary syntax highlighting for <code>.l2</code> files. We use <a href="https://eeyo.io/iro/documentation/">Iro</a> for syntax grammar generation. Find <a href="https://github.com/HexmosTech/Lama2/tree/main/syntax/README.md">more details</a> if interested.</p>

Expand Down
Loading

0 comments on commit ca8cadf

Please sign in to comment.