Skip to content

Commit

Permalink
Documentation Update
Browse files Browse the repository at this point in the history
  • Loading branch information
@bpbecker
bpbecker committed Feb 27, 2025
1 parent 5adf118 commit da5e590
Show file tree
Hide file tree
Showing 22 changed files with 615 additions and 1,420 deletions.
170 changes: 55 additions & 115 deletions docs/conga-settings.md
View file

Large diffs are not rendered by default.

93 changes: 30 additions & 63 deletions docs/encode-methods.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,78 +6,45 @@ Base64 is a binary-to-text encoding scheme that is used to transmit binary data

### `Base64Decode`
Decode a Base64-encoded string or single-byte integer vector.
<table>
<tr><td>Syntax</td>
<td><code>out←{cpo} HttpCommand.Base64Decode b64</code></td></tr>
<tr><td><code>b64</code></td>
<td>A character vector of Base64-encoded data.</td></tr>
<tr><td><code>cpo</code></td>
<td>(optional) cpo stands for "code points only". It can be any value, its mere existence is all that is necessary. You would use it in the case where you do not want <code>Base64Decode</code> to perform a UTF-8 conversion on the result. In almost all use cases, you can ignore this argument.</td></tr>
<tr><td><code>out</code></td>
<td>A character vector representing the decoded base-64 right argument.</td></tr>
<tr><td>Example(s)</td>
<td><code> HttpCommand.Base64Decode 'RHlhbG9nIOKNuuKNtOKMig=='</code><br>
<code>Dyalog ⍺⍴⌊</code></td></tr>
</table>

|--|--|
|Syntax|`out←{cpo} HttpCommand.Base64Decode b64`|
|`b64`|A character vector of Base64-encoded data.|
|`cpo`|(optional) cpo stands for "code points only". It can be any value, its mere existence is all that is necessary. You would use it in the case where you do not want `Base64Decode` to perform a UTF-8 conversion on the result. In almost all use cases, you can ignore this argument.|
|`out`|A character vector representing the decoded base-64 right argument.|
|Example(s)|<pre style="font-family:APL;"> HttpCommand.Base64Decode 'RHlhbG9nIOKNuuKNtOKMig=='<br>Dyalog ⍺⍴⌊</pre>|

### `Base64Encode`
Base64 encode a string or integer vector.
<table>
<tr><td>Syntax</td>
<td><code>b64←{cpo} HttpCommand.Base64Encode in</code></td></tr>
<tr><td><code>in</code></td>
<td>Either an integer vector with values in the range 0-255 or a character vector to be encoded</td></tr>
<tr><td><code>cpo</code></td>
<td>(optional) cpo stands for "code points only". If not supplied, <code>Base64Encode</code> will first perform UTF-8 conversion on a character argument. If any value for <code>cpo</code> is supplied, no conversion will be performed. If <code>in</code> is integer, no conversion is performed. The only use case for this argument is when you have already UTF-8 converted the <code>in</code> and you don't want <code>Base64Encode</code> to perform a second conversion.</td></tr>
<tr><td><code>b64</code></td>
<td>A character vector representing the base-64 encoding of the right argument.</td></tr>
<tr><td>Example(s)</td>
<td><code> HttpCommand.Base64Encode 'Dyalog ⍺⍴⌊'</code><br>
<code>RHlhbG9nIOKNuuKNtOKMig==</code></td></tr>
</table>

|--|--|
|Syntax|`b64←{cpo} HttpCommand.Base64Encode in`|
|`in`|Either an integer vector with values in the range 0-255 or a character vector to be encoded|
|`cpo`|(optional) cpo stands for "code points only". If not supplied, `Base64Encode` will first perform UTF-8 conversion on a character argument. If any value for `cpo` is supplied, no conversion will be performed. If `in` is integer, no conversion is performed. The only use case for this argument is when you have already UTF-8 converted the `in` and you don't want `Base64Encode` to perform a second conversion.|
|`b64`|A character vector representing the base-64 encoding of the right argument.|
|Example(s)|<pre style="font-family:APL;"> HttpCommand.Base64Encode 'Dyalog ⍺⍴⌊'<br/>RHlhbG9nIOKNuuKNtOKMig==|


## URL Encoding
URLs can only be sent over the Internet using the ASCII character set. However, URLs often contain characters outside the ASCII character set. URL encoding converts strings to a format acceptable for transmission over the Internet. URLEncoding is also used to encode payloads for content-type `'application/x-www-form-urlencoded'`.

### `UrlDecode`

URLDecode a URLEncoded string.
<table>
<tr><td>Syntax</td>
<td><code>out←HttpCommand.UrlDecode in</code></td></tr>
<tr><td><code>in</code></td>
<td>A URLEncoded string</td></tr>
<tr><td><code>out</code></td>
<td>The URLDecoding of <code>in</code>.</td></tr>
<tr><td>Example(s)</td>
<td><code> HttpCommand.UrlDecode 'Dyalog%20%E2%8D%BA%E2%8D%B4%E2%8C%8A'</code><br/>
<code>Dyalog ⍺⍴⌊</code><br/><br/>
<code> HttpCommand.UrlDecode 'name=Donald%20Duck'</code><br/>
<code>name=Donald Duck</code><br/><br/>
<code> HttpCommand.UrlDecode 'first=Donald&last=O%27Mallard'</code><br/>
<code>first=Donald&last=O'Mallard</code><br/>
</td></tr>
</table>

|--|--|
|Syntax|`out←HttpCommand.UrlDecode in`|
|`in`|A URLEncoded string|
|`out`|The URLDecoding of `in`.|
|Example(s)|<pre style="font-family:APL;"> HttpCommand.UrlDecode 'Dyalog%20%E2%8D%BA%E2%8D%B4%E2%8C%8A'<br/>Dyalog ⍺⍴⌊<br/><br/> HttpCommand.UrlDecode 'name=Donald%20Duck'<br/>name=Donald Duck<br/><br/> HttpCommand.UrlDecode 'first=Donald&last=O%27Mallard'<br/>first=Donald&last=O'Mallard|


### `UrlEncode`
URLEncode a string or a set of name/value pairs.
<table>
<tr><td>Syntax</td>
<td><code>out←{name} HttpCommand.UrlEncode in</code></td></tr>
<tr><td><code>in</code></td>
<td>One of:<ul>
<li>a simple character vector to be URLEncoded</li>
<li>a set of <a href="/request-settings#namevalue-pairs">name/value pairs</a></li>
</ul></td></tr>
<tr><td><code>name</code></td>
<td>(optional) The name for the URLEncoded right argument. Applies only in the case where <code>in</code> is a simple character vector.</td></tr>
<tr><td><code>out</code></td>
<td>The URLEncoding of <code>in</code>.</td></tr>
<tr><td>Example(s)</td>
<td><code> HttpCommand.UrlEncode 'Dyalog ⍺⍴⌊'</code><br/>
<code>Dyalog%20%E2%8D%BA%E2%8D%B4%E2%8C%8A</code><br/><br/>
<code> 'name' HttpCommand.UrlEncode 'Donald Duck'</code><br/>
<code>name=Donald%20Duck</code><br/><br/>
<code> HttpCommand.UrlEncode ('first' 'Donald') ('last' 'O''Mallard')</code><br/>
<code>first=Donald&last=O%27Mallard</code><br/>
</td></tr>
</table>

|--|--|
|Syntax|`out←{name} HttpCommand.UrlEncode in`|
|`in`|One of:<ul><li>a simple character vector to be URLEncoded</li><li>a set of <a href="/request-settings#namevalue-pairs">name/value pairs</a></li></ul>|
|`name`|(optional) The name for the URLEncoded right argument. Applies only in the case where `in` is a simple character vector.|
|`out`|The URLEncoding of `in`.|
|Example(s)|<pre style="font-family:APL;"> HttpCommand.UrlEncode 'Dyalog ⍺⍴⌊'<br/>Dyalog%20%E2%8D%BA%E2%8D%B4%E2%8C%8A<br/><br/> 'name' HttpCommand.UrlEncode 'Donald Duck'<br/>name=Donald%20Duck<br/><br/> HttpCommand.UrlEncode ('first' 'Donald') ('last' 'O''Mallard')<br/>first=Donald&last=O%27Mallard|
4 changes: 2 additions & 2 deletions docs/examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ The example above uses no authentication and therefore returns only publicly-ava
Some web services allow you to use HTTP Basic authentication using userid and password credentials. **Any request that includes authentication data should be sent using HTTPS if possible**. `HttpCommand` allows you to specify these credentials in a few ways:

* in the `URL` by including `userid:password@` before the domain name
* by setting `AuthType` to `'Basic'` and </br>`Auth` to `HttpCommand.Base64Encode 'userid:password'`
* by including an "Authorization" header in the format</br>`'Basic ',HttpCommand.Base64Encode 'userid:password'`
* by setting `AuthType` to `'Basic'` and <br/>`Auth` to `HttpCommand.Base64Encode 'userid:password'`
* by including an "Authorization" header in the format<br/>`'Basic ',HttpCommand.Base64Encode 'userid:password'`

The following examples use the "basic-auth" endpoint of the website [http://httpbin.org](http://httpbin.org). httpbin.org provides many useful endpoints for testing HTTP requests. In this case, the userid and password are concatenated to the URL so the endpoint can validate the credentials.

Expand Down
4 changes: 2 additions & 2 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,9 +109,9 @@ See [HttpCommand and Conga](./conga.md) for more information on how `HttpCommand

If your application has other components that also use Conga, we recommend that you use the "multiple roots" feature of the `Conga` namespace:

* Copy the `Conga` namespace from the `conga` workspace.</br>
* Copy the `Conga` namespace from the `conga` workspace.<br/>
`'Conga' #.⎕CY 'conga'`
* Set [`HttpCommand.CongaRef`](conga.md#overriding-default-locations) setting to refer to the `Conga` namespace.</br>
* Set [`HttpCommand.CongaRef`](conga.md#overriding-default-locations) setting to refer to the `Conga` namespace.<br/>
`HttpCommand.CongaRef←#.Conga`
* Similarly configure the other Conga-using components to refer to the `Conga` namespace.
* Now each component can create their own Conga "root" using `Conga.Init`.<br/>`HttpCommand` does this for you automatically.
Expand Down
Loading

0 comments on commit da5e590

Please sign in to comment.